Configuring the Agent

The agent is configured with a YAML file plus a handful of environment variables. On Linux it reads /etc/hexcovery-agent/config.yaml; in Kubernetes the same content comes from a ConfigMap (set via Helm values). This page is the reference for what you can configure.

For installation, see Agent on Linux and Agent on Kubernetes.

Connection

The agent needs to know where to send data and which API key to use:

server:
  endpoint: ingest.hexcovery.com:4317   # host:port of the ingest endpoint
  tls: true                             # use TLS for the connection
  api_key: ""                           # prefer the env var below

The API key authenticates your organization. Create one in the dashboard — see API keys and Authentication.

Keep the key out of the config file

Set the key via the environment instead of writing it into YAML. The environment variable overrides server.api_key.

Environment variables

All agent environment variables are prefixed HEXCOVERY_:

Variable	Description
`HEXCOVERY_API_KEY`	API key (overrides `server.api_key`)
`HEXCOVERY_SERVER_ENDPOINT`	Ingest endpoint (`host:port`)
`HEXCOVERY_SERVER_TLS`	Enable TLS (`true` / `false`)
`HEXCOVERY_PROFILE`	Profile name (see below)
`HEXCOVERY_INTERVAL`	Global collection interval
`HEXCOVERY_CLUSTER_NAME`	Kubernetes cluster name

Profiles

A profile sets sensible collector defaults for a deployment type. Explicit config in the YAML overrides the profile.

Profile	Use case	System collectors	Kubernetes collectors
`linux`	Linux host	enabled	disabled
`bare-metal`	Bare-metal Kubernetes	enabled	enabled
`eks`	AWS EKS	disabled	enabled
`gke`	Google GKE	disabled	enabled
`aks`	Azure AKS	disabled	enabled

Collection intervals

Each collector runs on its own ticker. The interval is resolved in this order: a collector-specific setting, then the global interval, then the built-in default (10s).

interval: 10s            # global default
collectors:
  disk:
    interval: 20s        # override for one collector

Recommended cadences: host and network every 10s; disk and filesystem every 20s; process and Kubernetes collectors every 30s.

Choosing what to collect

The profile decides which collector groups run. You can enable or disable individual collectors under collectors: to trim what you ship — for example, dropping the process collector on a host where per-process detail isn't needed.

Host log collection

The agent tails host logs from files and journald units. Logs are attributed per-path and per-unit — there is no global default — so each entry declares its own service and Project:

logs:
  paths:
    - path: /var/log/myapp/app.log
      service: orders-api          # → service.name
      project: superpippo          # → service.namespace (the dashboard "Project")
  journald:
    units:
      - name: myapp.service
        service: orders-api
        project: superpippo

service: maps to the OTel service.name; project: maps to service.namespace — the dashboard's Project. See Services and Projects.
Paths and units left without service:/project: are still tailed, but their lines land unattributed and are filtered out of the Projects page.
In Kubernetes, log attribution comes from pod annotations instead — see Agent on Kubernetes.

Deprecated attribution keys

The older top-level logs.service / logs.service_namespace, per-path application: / service_namespace:, and the HEXCOVERY_SERVICE / HEXCOVERY_SERVICE_NAMESPACE environment variables have no effect. Attribute logs per-path and per-unit with service: / project: as shown above.

Buffering and batching

The agent buffers and batches data locally before sending it. Collectors hand typed messages to an exporter that batches them by type, flushes on a size threshold or a timer, attaches the API key, and retries with exponential backoff on transient failures. This means brief network interruptions to the ingest endpoint don't lose data — the agent holds it and retries.