Collector configuration reference

A Tracix Collector takes almost all of its configuration from its policy. Only a few settings live on the host: where the control plane is, how to reach it, and what the host allows the collector to do. This page lists both, with the files the collector keeps on each platform.

What the policy controls

You manage these in the console, on the policy, and every collector on the policy picks up the change:

Tracix turns the policy into an OpenTelemetry Collector configuration and writes it to the collector's config.yaml. Every generated configuration also:

• adds policy.id and policy.name resource attributes to everything the collector sends;
• removes credentials from URLs in the application spans and OTLP logs the collector handles, such as user:password@ in a URL, webhook paths and token query parameters, before it exports them;
• keeps the collector's management connection, its local health check and its own metrics.

The configuration on disk never contains the credential the collector writes with. It holds a reference, which the collector resolves in memory when it loads the configuration.

What stays on the host

The installer writes these, and they change only when you run the installer again:

• the control plane URL the collector enrolls with;
• an outbound proxy, if you passed --proxy;
• the collector's display name;
• what the host lets the collector do, such as the eBPF permissions --enable-obi grants.

Installer flags

The installer for Linux and macOS takes these flags. The Windows installer takes the PowerShell equivalents shown in Install the Tracix Collector.

The console's install command adds the flags the selected policy needs. Running the installer again without a flag removes what that flag granted.

Files on each platform

The state directory

The state directory is what makes a host the same collector across restarts, upgrades and reinstalls against the same workspace. Running the installer against a different workspace moves the old identity and configuration to backups/ and enrolls the host as a new collector.

The bootstrap config.yaml

On Linux, macOS and Windows, the installer writes a minimal configuration that does one thing: enroll. Once the collector has enrolled, it replaces the file with its policy's configuration. Each install keeps the previous file beside it as config.yaml.bak.<timestamp>. This is the Linux and macOS version; Windows reads the same values with ${env:…}.

# tracix-bootstrap
extensions:
health_check:
  endpoint: 127.0.0.1:13133
remoteconfig:
  endpoint: ${CONTROL_PLANE_URL}
  auth_token: ${AGENT_TOKEN}
  config_path: ${TRACIX_CONFIG_PATH}
  state_dir: ${TRACIX_STATE_DIR}
  poll_interval: 30s
  timeout: 10s

receivers:
nop: {}

exporters:
nop: {}

service:
extensions: [health_check, remoteconfig]
pipelines:
  metrics:
    receivers: [nop]
    exporters: [nop]

The nop pipeline sends nothing; it only makes the file a valid collector configuration. The values in ${…} come from the environment file. Docker and Kubernetes collectors start from a similar configuration that also sends host metrics until the policy arrives.

The environment file

On Linux the file is /etc/tracix-collector/tracix-collector.env; on macOS, /usr/local/etc/tracix-collector/tracix-collector.env. The enrollment token is never in it.

To change a value, run the installer again with the new flags rather than editing the file. The installer rewrites the file each time and keeps a copy of the old one in backups/.

Local health check

Every collector answers a health check on port 13133. On Linux, macOS and Windows hosts it listens on 127.0.0.1 only, so it can't be reached from the network. In containers it listens on every interface, so Kubernetes probes and Docker port mappings can reach it.

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:13133

200

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:13133

200

(Invoke-WebRequest http://127.0.0.1:13133 -UseBasicParsing).StatusCode

200

kubectl get pods -n tracix

docker inspect --format '{{.State.Health.Status}}' tracix-agent

healthy

The collector also serves its own metrics in Prometheus format on port 18888, on the same interfaces as the health check. Tracix doesn't collect them; they are there for you to inspect.

Next steps