Dashboards¶

tailscale2otel ships ready-to-use Grafana dashboards in the deploy/grafana/ directory: two v2-schema dashboards for Grafana 13+, generated from code, and nothing else - the four legacy single-purpose dashboards were removed (see below).

Two dashboards, two questions¶

The dashboards split on the question they answer, not on data source:

Open Tailnet for anything about the fleet, its network traffic, or its security posture. Open Exporter health when you suspect data is missing, stale, or wrong, and you need to know whether that's the exporter's fault rather than the tailnet's. Each dashboard carries a cross-link to the other in its controls menu (Exporter health → / ← Tailnet), so you don't need to remember both uids.

Both use the Grafana v2 dashboard schema (dashboard.grafana.app/v2, Grafana 13+) with tabbed, often nested navigation and conditional rendering - a tab or row only appears when its underlying data is actually present, so each dashboard adapts to whichever optional collectors and features you have enabled.

Both are generated from code (gen/build.py + gen/dashboards.py, standard-library Python). Edit the generator, not the JSON, and regenerate with:

python3 gen/build.py --out-dir .

tailscale2otel-tailnet tabs¶

Fleet & Network and Security & Policy are nested domains - each has sub-tabs, and one of them (Devices, Security & Audit, Policy & Config) is nested a level deeper still.

tailscale2otel-health tabs¶

Removed: the four classic-schema dashboards¶

tailscale-fleet.json (ts2otel-fleet), tailscale-network.json (ts2otel-network), tailscale-audit-events.json (ts2otel-audit-events) and tailscale-exporter-health.json (ts2otel-exporter-health) have been removed. They were hand-maintained schemaVersion: 39 JSON, duplicated content the v2 dashboards already cover, and were excluded from every generator and drift gate - so they drifted silently and were the only dashboards nothing tested.

tailscale2otel targets Grafana 13+ and the v2 dashboard schema only. The v2 dynamic layout (tabs, nested navigation, conditional rendering) cannot be expressed in the classic schema, so a compatibility copy could not have shown the same thing anyway.

If you had one of those UIDs provisioned, point at the two dashboards above instead. The tab that replaces each is:

Both dashboards' tabs hide themselves when their backing signal is absent, so you see less than the old dashboards showed only where the old ones were rendering empty panels.

Importing¶

gcx (recommended):

gcx resources push -f tailscale2otel-tailnet.json
gcx resources push -f tailscale2otel-health.json

Grafana UI: Dashboards → New → Import → Upload JSON file, then map the datasources.

File provisioning: drop the JSON into a path referenced by a dashboards provider and restart Grafana.

Datasource variables¶

All dashboards resolve datasources by template variable - no pinned UIDs - so they are portable across stacks:

• ${DS_PROM} / ds_prometheus - a Prometheus datasource (Grafana Cloud default UID: grafanacloud-prom)
• ${DS_LOKI} / ds_loki - a Loki datasource (Grafana Cloud default UID: grafanacloud-logs)

Both dashboards also expose one Instance / environment ad-hoc control. In a stack receiving several exporter installations, add service_instance_id and/or deployment_environment_name filters there to keep every Prometheus panel on the intended install.

OTLP → Prometheus naming¶

Grafana Cloud's OTLP ingest pipeline normalizes metric names before they reach PromQL. The dashboard queries use the normalized names, not the raw OTEL names. The key rules:

• Dots become underscores in both metric names and label keys.
• Monotonic counters gain a _total suffix.
• Units are appended: By → _bytes, s → _seconds, d → _days.
• A gauge with unit "1" gets a _ratio suffix - including plain integer counts, so tailscale_devices_count becomes tailscale_devices_count_ratio.

See Metrics for the full naming rules and the complete metric catalog.