Collection Options¶

When registering an agent, you declare which data it should collect. These settings are stored server-side and baked into the Alloy configuration file that agent register generates. Most settings can be changed later with agent edit.

Required: hostname¶

Every agent must have a hostname. It is used as a label on all collected telemetry and appears in Grafana dashboards.

finchctl agent register --agent.hostname web-01 finch.example.com

Log sources¶

At least one log source is required. Multiple sources can be combined freely.

systemd journal (Linux)¶

--agent.logs.journal

Collects all entries from the systemd journal on the agent host.

Docker container logs (Linux / macOS)¶

--agent.logs.docker

Collects stdout/stderr from all running Docker containers. Requires access to /var/run/docker.sock on the agent host.

File log paths¶

--agent.logs.files /var/log/app.log --agent.logs.files /var/log/nginx/*.log

Tails one or more file paths. Glob patterns are supported. Repeat the flag for each path.

Windows event log channels¶

--agent.logs.events Application --agent.logs.events System

Collects entries from named Windows Event Log channels. Only valid when --agent.node windows. See Windows Agents for setup details.

Metrics¶

--agent.metrics

Enables node-level metrics collection (CPU, memory, disk, network) via the Prometheus node_exporter integration in Alloy and listens locally on port 9091 for metrics data.

Custom metrics targets¶

--agent.metrics.targets http://localhost:9100/metrics

Scrapes additional Prometheus endpoints. Repeat the flag for each target URL. Setting --agent.metrics.targets requires --agent.metrics to be enabled.

Profiles¶

--agent.profiles

Enables continuous profiling via Pyroscope and listens locally on port 4040 for profile data.

Labels¶

--agent.labels env=production --agent.labels team=backend

Attaches arbitrary key-value labels to all telemetry from this agent. Labels appear as Grafana datasource selectors and can be used in dashboard queries and alert rules. Repeat the flag for each label. Both agent register and agent edit accept labels.

Node type¶

--agent.node unix      # default
--agent.node windows

Sets the target operating system for the Alloy configuration. Use windows for Windows agents (enables Windows-specific log and metrics pipelines). Cannot be changed after registration.

Agent file (YAML)¶

All registration options can be provided via a YAML file instead of individual flags:

finchctl agent register \
  --agent.file agent.yaml \
  --agent.config web-01.cfg \
  finch.example.com

The file uses key names corresponding to the cli flags, with nested keys for dot notation. For example:

hostname: web-01
logs:
  journal:
    enable: true
  docker:
    enable: true
  files:
    - /var/log/app.log
metrics:
  enable: true
  targets:
    - http://localhost:9100/metrics
profiles:
  enable: false
labels:
  - env=production
  - team=backend

Any rid field in the file is silently ignored, a new resource ID is always generated on registration. This makes YAML files safe to reuse.

finchctl agent describe \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  --output.json \
  finch.example.com | \
  yq --input-format json --outformat yaml > agent.yaml

agent edit also accepts --agent.file, but the hostname and node fields are ignored (they cannot be changed after registration).