Configuration Reference¶

This is the exhaustive, per-key reference for tailscale2otel configuration. It is the companion to two other docs:

• config.example.yaml — a commented starter showing the common knobs. The fastest way to get started.
• docs/metrics.md — every metric and log signal the exporter emits (and the OTLP→Prometheus name normalization you query in Grafana Cloud).

Use this page when you need the precise meaning, default, valid values, and gotchas of a specific setting.

This file is hand-maintained (unlike docs/metrics.md, which is generated). If you change the config schema in internal/config/, update this page too.

Layered configuration¶

Configuration is loaded in three layers, lowest precedence first:

1. Built-in defaults — the exporter runs without a config file; any key you do not set keeps its default (defined in internal/config/defaults.go).
2. YAML file (optional) — pass -config path/to/file.yaml; the file overrides defaults for any key it mentions. A non-existent path passed with -config is an error; omitting -config entirely is not.
3. Environment variables — highest precedence; override both defaults and the file.

Environment-variable convention¶

Every config field is settable via an environment variable:

• Prefix: TS2OTEL_
• Nesting delimiter: __ (double underscore) between levels
• Within a name: single underscores are preserved (e.g. client_id stays CLIENT_ID)

For the complete, generated list of every TS2OTEL_* variable with its default and description, see env-vars.md. The samples below just illustrate the rule.

Mapping examples¶

Scalar lists¶

Fields whose type is a list of strings accept a comma-separated value as an env var. Examples:

TS2OTEL_TAILSCALE__AUTH__OAUTH__SCOPES=all:read,log_streaming
TS2OTEL_COLLECTORS__NODE_METRICS__METRIC_ALLOW=tailscaled_inbound.*,tailscaled_outbound.*
TS2OTEL_COLLECTORS__NODE_METRICS__DROP_LABELS=job,prometheus_replica
TS2OTEL_COLLECTORS__NODE_METRICS__DISCOVERY__INCLUDE_TAGS=tag:server,tag:relay
TS2OTEL_COLLECTORS__DEVICES__ATTRIBUTE_NAMESPACES=intune,jamf,ip

File-only fields¶

These fields cannot be set via flat env vars because they are maps or lists of structs:

• otlp.headers — use the YAML file (or use otlp.grafana_cloud for Grafana Cloud).
• collectors.node_metrics.targets — each target is a struct; static targets require a YAML file.
• profiling.pyroscope.tags — a string→string map; set via YAML.

Unknown-variable advisory¶

A TS2OTEL_* env var that does not match any known config key is logged at startup as a WARN — this almost always means a typo in the variable name. The exporter still starts; the variable is ignored.

Conventions¶

• Default is the value used when the key is not set in either the file or an env var.
• Durations use Go's syntax: 500ms, 30s, 5m, 1h, 168h (= 7 days).
• Validation — invalid enum values and inconsistent combinations are rejected at startup by Config.Validate() (the exporter refuses to start). Softer issues are surfaced as startup WARN advisories by Config.Warnings() but do not block startup. Both are noted below.

Contents¶

• Top level
• tailscale — API connection & authentication
• otlp — the OTLP exporter
• enrichment — device-name cache
• cardinality — metric/label cardinality controls
• collectors — per-source polling
• checkpoint — poll high-water marks
• streaming — Splunk-HEC log receiver
• webhook — event webhook receiver
• self_observability — the exporter's own telemetry
• admin — admin HTTP server (probes + status page)
• profiling — pprof & Pyroscope

Top level¶

tailscale — API connection & authentication¶

tailscale.auth¶

Prefer OAuth: its tokens are short-lived, auto-refreshing, and not bound to a user.

WARN (advisory): method: apikey triggers a startup warning — a personal API key expires in ≤90 days and stops working when the user who created it is suspended or removed. For an unattended exporter, prefer method: oauth.

tailscale.http¶

The HTTP client used for all Tailscale API calls.

otlp — the OTLP exporter¶

The single egress path for metrics and logs. internal/telemetry is the only component that touches OTLP.

otlp.grafana_cloud¶

Convenience for Grafana Cloud: when both are set, an Authorization: Basic <base64(instance:token)> header is built for you (no need to hand-craft it in otlp.headers).

otlp.tls¶

Transport security for grpc/http.

enrichment — device-name cache¶

The in-memory IP/nodeID→name cache, populated by the devices collector and used to enrich flow and audit records.

Enrichment depends on the devices collector. If devices is disabled, flow/audit IP→name resolution silently degrades to unknown/external.

enrichment.reverse_dns¶

Optional async reverse-DNS (PTR) enrichment of external (non-Tailscale) flow addresses. Off by default. When enabled, resolved hostnames replace the external bucket / raw IP in tailscale.src.node / tailscale.dst.node on flow logs and metrics. Lookups are async and cached; the hot path never blocks.

cardinality — metric/label cardinality controls¶

These knobs trade detail for active-series count. They apply to the shared processors, so they take effect no matter whether logs arrive by poll or by stream.

Top-level cardinality keys¶

cardinality.flow — flow metric shaping¶

These knobs affect flow metrics only. Flow logs always carry full detail regardless.

cardinality.per_entity — per-entity gauge gates¶

When a toggle is false, only the low-cardinality aggregate *.count rollup is emitted; the per-entity gauge series (one per device/user/key/…) are dropped. All default true.

collectors — per-source polling¶

Each collector has at least enabled and interval. The two log collectors (flowlogs, auditlogs) additionally have source and a set of windowing fields; the rest are point-in-time snapshots.

Common fields¶

source and the windowing fields (flowlogs / auditlogs only)¶

source selects how the log collector obtains data:

• poll (default) — the exporter pulls logs from the Tailscale API on interval, one time-window per tick.
• stream — logs are pushed to the streaming receiver instead; the exporter does not poll this log type.
• both — poll and accept the stream. Discouraged: the same record can be double-counted. Cross-source de-duplication is a best-effort failsafe, not a guarantee, and a startup WARN fires.

Pick exactly one method per log type. Which fields are honored depends on source:

¹ Under poll the budget is shared across the whole poll window; under stream it is applied per received record. Either way, metrics are never capped — only logs.

The four windowing fields exist purely to drive the poller, so they are ignored when source: stream. The streaming/webhook receivers and the pollers feed the same processors, which is why log_mode and the cardinality.* knobs apply on every path.

collectors.devices¶

collectors.flowlogs¶

Network flow logs → aggregated traffic counters + per-connection flow logs.

collectors.auditlogs¶

Configuration/audit events → event logs + a counter.

Snapshot collectors¶

collectors.services¶

collectors.node_metrics¶

Optional scraper that pulls tailscaled per-node Prometheus /metrics and forwards them centrally over OTLP (counters as deltas, gauges as gauges, plus a per-target tailscale.node.up). Off by default, and inert unless it has at least one static target or discovery enabled. Node identity is carried as the instance label, not an OTEL Resource. See docs/node-metrics.md for the operator how-to.

These filters apply only to forwarded samples — never to tailscale.node.up or the discovery.* gauges.

collectors.node_metrics.targets[]¶

A static list of endpoints to scrape (keys below are relative to each list entry). Native tailscaled endpoints are plain HTTP and need no auth/TLS; the optional fields cover proxied/HTTPS targets.

collectors.node_metrics.discovery¶

Discover scrape targets dynamically from the Tailscale devices API (keys below are relative to the discovery block). Discovered targets are unioned (deduped by URL, static wins) with the static targets, on this block's own interval.

checkpoint — poll high-water marks¶

Checkpoints record how far each polled log collector (flowlogs/auditlogs with source: poll or both) has read, so a restart resumes without gaps or large overlaps. The store is unused if you stream both log types or disable them.

• file (default) — the high-water mark is persisted to file_path with an atomic write on each tick and reloaded at startup, so polling resumes from the exact high-water mark across restarts (minor boundary overlap is de-duplicated). For the checkpoint to actually survive a restart, mount a writable, persistent path at the file's directory (a volume in Kubernetes/Docker). If the path is not writable (e.g. a read-only root filesystem with no volume, or a local run without access to /var/lib), the exporter logs a WARN and transparently falls back to memory rather than erroring.
• memory — the high-water mark lives in RAM only and is lost on restart. After a restart the poller cold-starts from initial_lookback, so any downtime longer than initial_lookback leaves a gap. Needs no volume; fine for streamed or stateless deployments where the checkpoint is unused or disposable.

streaming — Splunk-HEC log receiver¶

Optional receiver for Tailscale's log streaming (a Splunk-HEC sink). When you enable it, set the relevant log collector(s) to source: stream so each log type is ingested by exactly one path. Off by default.

Validation: auto_configure: true errors at startup unless both streaming.enabled: true and a non-empty streaming.public_url are set. Running the poller and this receiver for the same log type triggers a dual-ingestion WARN.

webhook — event webhook receiver¶

Optional receiver for real-time Tailscale events (HMAC-verified). Off by default.

self_observability — the exporter's own telemetry¶

admin — admin HTTP server (probes + status page)¶

Always-off-by-default HTTP server exposing liveness/readiness probes plus an optional status page. The status page surfaces operational metadata (collector health, cardinality, discovered nodes, redacted config) but never secret values. Bind it to a tailnet/loopback address, not the public internet.

WARN (advisory): if landing_page is served on a wildcard (all-interfaces) bind with no admin.auth.token, a startup warning fires — the page exposes internal state to anyone who can reach the port. Set a token or bind to loopback/tailnet.

profiling — pprof & Pyroscope¶

Optional continuous/on-demand profiling. Everything here is off by default and carries no Tailscale data. The pprof handlers mount on the admin server.

Validation / advisories: - pprof.enabled errors at startup unless admin.enabled: true and admin.auth.token is set (heap/goroutine dumps can expose in-memory secrets, so pprof must not be served unauthenticated). - pyroscope.enabled errors at startup without pyroscope.server_address. - A grafana.net server_address with an empty basic_auth_password triggers a WARN — Grafana Cloud Profiles requires the Basic-auth credentials.

version_checks — outbound "is a newer release available?" checks¶

Optional outbound checks that compare the running build / device client versions against the latest releases. Both sub-checks make external HTTPS calls and are fail-open (a failed or blocked fetch silently emits nothing, never errors). Disable both for air-gapped deployments.

Advisories: - version_checks.devices.enabled=true with collectors.devices.enabled=false triggers a WARN — the per-device version-skew metrics need the devices collector to run.