- Linux · macOS · Windows · Kubernetes · Docker
Enroll and manage collectors with policies
A policy decides what a group of collectors collects and where they write it. Every collector enrolls into exactly one policy and runs that policy's integrations, so you change a whole fleet by changing one policy.
How policies work
A policy holds three things:
- Integrations: the receivers the collectors run, such as host metrics, SNMP, syslog or a cloud account. A policy needs at least one.
- Output: where the collectors write. Every policy starts with your workspace's own data store, shown as Tracix store.
- Collector updates: whether collectors on the policy follow the stable release automatically. See Upgrade collectors.
When you save a change, Tracix gives the policy a new numbered revision (r1, r2 and so on) and turns it into an OpenTelemetry Collector configuration. Tracix checks that configuration first: a change that would produce one collectors can't load is refused, with the reason. The configuration is signed with Ed25519, and each collector checks the signature before it uses it.
Tracix pushes each new revision to the policy's collectors over a WebSocket they keep open to your workspace. When the WebSocket is unavailable, a collector falls back to checking for changes over HTTPS about every 60 seconds.
A collector also validates every new revision before applying it. If a revision fails to load on that host, the collector keeps running the last configuration it applied and reports why it refused the new one.
The default policy
If you install a collector without choosing a policy, it joins a policy named default. Tracix creates it the first time it is needed, with the host metrics integration (CPU, memory, disk, network, load and file systems every 30 seconds).
Create a policy
You need a role that can manage collectors.
Open Policies
In your workspace, open Collectors › Policies and select Create policy.
Name the policy
Enter a Policy name, such as
Edge routers - Production, and an optional description.Choose how collectors update
Automatically update managed collectors is on by default: collectors on this policy move to each new stable release on their own. Clear it if you want to upgrade them yourself.
Add integrations
Select add integration, pick an integration and fill in its settings. Add at least one; you can add more at any time.
Create it
Select Create policy. The policy opens at revision
r1, with the workspace's default output and a first enrollment token namedToken for <policy name>.
You can also start from an existing policy: open it and choose Actions › Duplicate policy. The copy keeps the integrations, their saved credentials, the output and the update setting, and gets (copy) added to its name.
Enroll collectors into a policy
Collectors enroll with an enrollment token. Each token belongs to one policy, so the token you install with decides the policy the collector joins.
Use the install steps
The simplest way is to let the console write the install command for you:
- Open the policy and choose Actions › Add collector to this policy. You can also open Collectors, select Deploy collector and pick the policy on the Policy step, or create a new policy there.
- Pick the install path: Windows, Linux, MacOS, Kubernetes or Docker.
- Run the command the Install step shows. It carries the policy's newest active enrollment token, and the page waits until the first heartbeat arrives.
For what each part of the command does, see Install the Tracix Collector.
Manage enrollment tokens
A policy can hold several named tokens, for example one per site or team. Each one enrolls any number of collectors until it is revoked or expires.
Open the policy's settings
Open Collectors › Policies, select the policy and open the Settings tab. Tokens are listed under Enrollment tokens, with their status, expiry, last use and how many collectors enrolled with them.
Create a token
Select Create token, give it a Name and choose when it Expires: never, or after 1, 7, 30 or 90 days. Copy the value from the dialog.
Show or revoke a token
Show displays an active token's value again. Tokens created before values could be shown again can't be shown. Revoke stops new collectors from enrolling with the token.
Treat enrollment tokens like passwords
Anyone with a token can enroll a collector into your workspace. Keep tokens out of chat and source control, and prefer --token-file or the installer's hidden prompt over --token on shared hosts.
Revoking a token does not affect collectors that already enrolled with it. At enrollment each collector receives its own credential, and that credential is what it uses from then on.
Change what collectors collect
Open the policy's Integrations tab:
- Add integration adds a receiver and configures it.
- Each integration's menu offers Edit, Disable (or Enable) and Remove.
Every save creates a new revision, which every collector on the policy picks up. If someone else saved the policy while you were editing it, Tracix refuses your save rather than overwriting their change, loads the latest revision and asks you to make your change again.
The Settings tab holds the policy's details, the Automatically update managed collectors setting, the output, the assigned collectors and the enrollment tokens.
When a collector refuses a revision
If collectors can't load a revision, the policy page shows a Config rejected notice with the revision, the collectors that refused it and the reason. Those collectors keep running the last configuration they applied and pick up the next revision they can load, so fix the integration the reason names and save again.
If one integration loads but fails to start, for example because another process holds its port, the collector switches off that integration and keeps running everything else. The collector shows Integration failed, with the error under the integration. See Troubleshoot the collector.
Revisions and rollback
The policy page shows the current revision in its header, and the Settings tab lists it with the policy's ID and dates.
No rollback in the console yet
The console has no revision history or rollback button yet. Today you undo a change by editing the policy back, which creates a new revision.
Move collectors to another policy
A policy with collectors can't be deleted, so collectors are never left without a configuration. Deleting one moves its collectors first:
- Open the policy and choose Actions › Delete policy.
- Choose the Target policy the collectors move to.
- Confirm. The collectors pick up the target policy's configuration immediately, then the policy is deleted.
A policy with no collectors is deleted after a confirmation. Deleting can't be undone.
Unenroll or uninstall a collector
Open Collectors, select a collector and use the buttons at the bottom of its details. You can also select several collectors and use the bulk actions above the list.
| Action | What happens |
|---|---|
| Unenroll | Revokes the collector's access immediately and removes it from the list. The installed service or container keeps running until you remove it yourself, and Tracix can't uninstall it remotely afterwards. |
| Uninstall | Removes the collector's installation, then retires it from the list. Available only when the installation supports managed uninstall. |
Managed uninstall works on Linux, macOS, Windows and Kubernetes installs made with a current installer or chart. Docker containers and older host installs need to be removed by hand; run the current installer once on an older host to add the capability.
On Kubernetes, uninstall deletes the collector's DaemonSet, which retires every node's collector from that installation. The chart's other resources stay behind, so remove the release with helm uninstall when you are done. If a GitOps tool such as Flux or Argo CD manages the chart, remove it there too, or it recreates the DaemonSet.