tailscale2otel¶
tailscale2otel exports device fleet state, network flows and configuration changes from Tailscale as OpenTelemetry metrics and logs. Choose OTLP push, Prometheus pull, or both for separate destinations. It runs as a single static Go binary.
Headscale supports a reduced set: devices, users, keys, ACL and node metrics. Source code and releases are on GitHub.
Quickstart¶
Choose a destination before collecting credentials: Grafana Cloud over OTLP, Prometheus pull, or stdout. The Getting Started page is the canonical command reference for Docker, Compose, Helm, and a local binary; it states the expected first result for each route.
Start here¶
- Getting started - choose a destination, create Tailscale authentication, and reach a first observable signal.
- Installation - Docker, Helm, docker-compose, or a prebuilt binary for Linux, macOS and Windows.
- Configuration - every key, its default, and the
TS2OTEL_*environment variable that overrides it. - Metrics catalog - all 332 metrics and 30 log-event types, with their OTLP→Prometheus names.
What it collects¶
17 collectors run on independent schedules, each isolated so one failing source cannot stall the others:
| Area | What you get |
|---|---|
| Network flow logs | Throughput, packet and flow counters aggregated for dashboards, plus per-connection records as logs for drill-down. Cardinality is bounded by a top-N rollup, to limit series growth. See configuration. |
| Audit logs | Every tailnet configuration change as a structured log event, plus a security-categorized counter you can alert on. |
| Device fleet | Online state, last seen, key and cert expiry, client version skew, NAT and connectivity quality, per-DERP latency, subnet routes, tailnet lock, and hygiene roll-ups. |
| Identity & access | Users and roles, auth keys, OAuth clients, API tokens and their expiry, plus outstanding invites. |
| Policy & posture | ACL size and change detection with structural risk scoring, DNS configuration, tailnet settings, and MDM/EDR posture integrations. |
| PAM | Border0 connector, service, policy and identity inventory, plus session telemetry. See PAM. |
| Node metrics | tailscaled's own :5252 metrics, scraped centrally with automatic target discovery. See node metrics. |
How the data gets in¶
Flow and audit logs can enter through three sources that feed the same processors:
- Polling the Tailscale API on a schedule: the default; it needs no inbound listener.
- Log streaming - Tailscale pushes flow and audit logs to a built-in Splunk-HEC-compatible receiver. Lower latency, but requires an endpoint Tailscale can reach.
- Object storage - tailscale2otel reads the exports Tailscale writes to an S3-compatible bucket. This is the durable batch path and supports backfill.
Pick exactly one source per log type. Webhooks are a separate fourth path for real-time, HMAC-verified tailnet events, not an alternative source for flow or audit logs. Details and the trade-offs are in streaming & webhooks.
Where it sends data¶
OTLP over gRPC or HTTP is the primary path, with Grafana Cloud authentication built in. A separate, opt-in Prometheus pull endpoint serves the same metrics on its own listener if you would rather scrape than push. The two can run at once. There is also a stdout mode for local debugging with no backend at all.
Ready-made dashboards and alert rules ship with the project.
Reading further¶
| Feature guide | Every user-facing feature and its setup reference |
| High availability | Kubernetes coordination, state and rollouts |
| Flow view | Local traffic queries and exports |
| Event explorer | Recent audit and webhook events |
| Architecture | How collectors, processors and the OTEL facade fit together |
| Node metrics | Central tailscaled scraping and target discovery |
| Streaming & webhooks | Receiver setup, auth, and auto_configure |
| Environment variables | The complete generated TS2OTEL_* reference |
| Security | Data handling, PII redaction, receiver authentication |
| Upgrading | Version-to-version migration notes |
| Troubleshooting | Common failure modes and how to diagnose them |
| Runbooks | Alert investigation and remediation |
| Kubernetes audit | Optional tsrecorder audit ingestion and signals |
Project¶
tailscale2otel is open source under the Apache 2.0 licence. Bug reports, feature requests and pull requests are welcome on GitHub - see the open issues or the latest release.