Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sawmills.ai/llms.txt

Use this file to discover all available pages before exploring further.

To start working with Sawmills, you’ll install the Sawmills OpenTelemetry (OTel) Collector distribution. Installation deploys a remote operator into your Kubernetes cluster, which then manages the Sawmills Collector.
A Sawmills account and access to the product dashboard is required to proceed with installation.

​
Prerequisites

  • Kubernetes Cluster: Access to the target cluster.
  • kubectl: Installed and configured to interact with the cluster.
  • Helm 3+: Installed and configured.
  • Permissions: Ability to create namespaces, secrets, and deploy Helm charts.

​
Install the Sawmills Collector

  1. Log in to the Sawmills dashboard.
  2. Go to the Collectors section (located at the bottom tab of the left navigation menu).
  3. Click New Collector to open the installation wizard.
If you use Kubectl to check Sawmills collector pods, initially you will only see the Sawmills operator running, as the collector service is started when a pipeline is deployed. See How to deploy a pipeline.

​
Step 1: Configure the Collector

  • Name: Provide a unique, descriptive name for the collector.
  • Namespace: The Kubernetes namespace where the collector will be installed.
The name should follow your organization’s naming conventions.

​
Advanced Options

  • Require manual deployment for pipeline changes: Enable this only if your environment prevents Sawmills from applying collector updates automatically. When enabled, Sawmills generates chart metadata and values files for each deployment, and your team applies them through your Helm release process. See Manual Collector Deployment.
Click Next to proceed.

​
Step 2: Install the Collector

This step provides the commands needed to deploy the remote operator, which manages the collector in your cluster.
  1. Create a Namespace (only if it does not already exist)
kubectl create namespace sawmills
  1. Create a Secret with your organization API key (only if it does not already exist)
kubectl create secret generic sawmills-secret \
  -n sawmills --from-literal api-key=****************
Warning: If you use a different secret name or key, update apiKeyExistingSecret and apiKeySecretKey in values.yaml, plus managedChartsValues.sawmills-collector.apiSecret.name and managedChartsValues.sawmills-collector.apiSecret.key.
  1. Install or Upgrade the Remote Operator using Helm
Copy the command shown in the Sawmills UI. It includes the remote operator chart version and controller address for your environment. 
helm upgrade --install sawmills-remote-operator \
  oci://public.ecr.aws/s7a5m1b4/sawmills-remote-operator-chart \
  --version <version-from-ui> \
  --create-namespace \
  --namespace <namespace> \
  --set apiKeyExistingSecret=sawmills-secret \
  --set operatorAddress=<operator-address-from-ui> \
  --set collectorName="<collector-name>"
Q: What if Helm cannot pull the Remote Operator chart from public ECR?A: Authenticate Helm to Amazon ECR Public, then rerun the install command:
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws

​
Updating Collector Values

The remote operator deploys the collector into the cluster. Collector values are passed as a values file to the remote operator Helm chart. To change collector configuration for an automatically managed collector, update the managedChartsValues.sawmills-collector section in values.yaml and upgrade the remote operator. The legacy managedCharts key continues to work as an alias, but managedChartsValues is preferred. For manually managed collectors, download the generated values artifacts from Sawmills and apply them through your Helm workflow. For details, see Collector Customization.

​
Step 3: Validate the Collector

Wait for the install to complete and all pods to enter a Running state. Validate the collector by clicking Test Installation. This confirms the collector is deployed and communicating back to Sawmills.
When validation passes, you’ll see success messages and a link to create or assign a pipeline via Pipelines Editor. If you created the collector but haven’t completed installation yet, its status will show as Awaiting Deployment on the Collectors page.

​
Next Actions

  • Pipelines Editor: Create a new pipeline or assign an existing pipeline to your collector.
  • Done: Finish without creating a pipeline.
  • Previous: Go back to change settings.

​
Remote Operator Resources

By default, 3 replicas of the remote operator are deployed with the following resource requests and limits: 
requests:
  memory: 256Mi
  cpu: 250m
limits:
  memory: 1Gi
  cpu: 500m

​
Autoscaling

Autoscaling is enabled by default with a minimum of 3 and a maximum of 10 collector instances.

​
Capacity Planning

For detailed guidance on sizing and scaling, see Capacity Planning.

​
KEDA Autoscaling

We recommend using KEDA for autoscaling. KEDA supports more flexible scaling rules and metrics. Enable it by setting keda.enabled to true in values.yaml: 
managedChartsValues:
  sawmills-collector:
    keda:
      enabled: true
See KEDA Autoscaling for more information.

​
Anti-Affinity

Anti-affinity is enabled by default to ensure collector pods are spread across nodes.