Metrics & Logs Reference¶

This is the as-built reference for every telemetry signal tailscale2otel emits: metrics (exported as OTLP and, on Grafana Cloud, normalized into Prometheus series) and structured log records (exported as OTLP logs, landing in Loki). It documents the OTEL source names, their units and instrument types, the normalized Prometheus names you actually query in Grafana Cloud, the key attributes/labels on each signal, and the conditions under which optional signals appear.

If you are wiring dashboards or alerts, query against the Prometheus (normalized) name column — that is what exists in the metrics store. The OTEL name is the source-of-truth identifier used in the code and in any non-Grafana OTEL backend.

Naming conventions¶

OpenTelemetry semantic-convention naming (the source names)¶

All metrics and log attributes are authored to follow OpenTelemetry semantic conventions:

• Dotted, lowercase, namespaced names — e.g. tailscale.network.io, tailscale.device.online, tailscale2otel.scrape.duration. Words within a segment use snake_case where needed (e.g. last_seen, key.expiry).
• UCUM units — units are expressed in the Unified Code for Units of Measure: By (bytes), s (seconds), d (days), 1 (a dimensionless ratio/flag), and "annotation" units like {packet}, {flow}, {route}, {event}, {record} for dimensionless counts of a thing.
• No _total suffix in the source. Monotonic counters are named without the Prometheus _total convention; that suffix is added later by the backend, not by us.
• Attribute keys are dotted/namespaced too — e.g. network.io.direction, http.response.status_code, service.version, host.name. Tailscale-specific keys use a tailscale.* prefix (e.g. tailscale.src_node, tailscale.audit.action).

Grafana Cloud OTLP → Prometheus normalization¶

When OTLP metrics are ingested by Grafana Cloud (Mimir/Prometheus), the names and labels are rewritten by the OTLP-to-Prometheus translation rules. The rules that matter here:

1. Dots become underscores — in both metric names and attribute (label) keys. tailscale.network.io → tailscale_network_io; the label network.io.direction → network_io_direction; http.response.status_code → http_response_status_code.
2. Monotonic counters get a _total suffix. tailscale.network.io (counter) → tailscale_network_io..._total.
3. Units are appended to the name for known UCUM units:
4. By → _bytes
5. s → _seconds
6. d → _days
7. A unit of 1 on a gauge gets a _ratio suffix. This is meant for true ratios (0..1), but the translation applies it to any gauge whose unit is 1.

Quirk — count gauges become *_ratio. Several of our gauges are dimensionless counts (e.g. tailscale.devices.count, tailscale.acl.rules, tailscale.dns.nameservers.count) that carry unit 1 because UCUM has no "count" unit for a gauge. The normalizer therefore appends _ratio to them, so you end up with tailscale_devices_count_ratio, tailscale_acl_rules_ratio, etc. These are counts, not ratios — read the Description column. The same applies to boolean/flag gauges (online, enabled, available) which are 0/1 and also land as *_ratio. This is a known cosmetic artifact of the OTLP→Prometheus mapping; the values are correct, only the suffix is misleading.

Note that annotation units in curly braces — {packet}/{flow}/{event}/{route} — are dropped entirely; they are never appended to the name, for either counters or gauges. So tailscale.network.packets (counter) → tailscale_network_packets_total, and tailscale.device.routes.advertised (gauge) → tailscale_device_routes_advertised (no _routes).

Worked examples¶

Labels follow the same dots→underscores rule, so the OTEL attributes tailscale.src.node / tailscale.dst.node are queried as the labels tailscale_src_node / tailscale_dst_node.

Metrics¶

Instrument column: counter = monotonic cumulative (rendered as _total in Prometheus, use rate()/increase()); gauge = point-in-time value.

Self-observability (tailscale2otel.*)¶

Emitted by the service about itself. Use these for health, scrape success, API behavior, and exporter health.

Network / flow (tailscale.network.*, tailscale.config.audit.*)¶

Aggregated, low-cardinality counters derived from flow logs and audit logs. The full-fidelity per-connection detail is emitted as log records (see Log events).

Label gating on network.io/network.packets: tailscale_src_node/tailscale_dst_node are gated by cardinality.flow.node_dims (on by default); source_port/destination_port are gated by cardinality.flow.source_port / cardinality.flow.destination_port (both off by default, as ports add cardinality).

Per-metric cardinality cap. Every metric is bounded by cardinality.metric_limit (default 10000) — the OTLP SDK's hard limit on distinct series per instrument per export cycle. Series past it collapse into a single {otel_metric_overflow="true"} series (silent loss of per-series detail). So a label-less tailscale_network_io_bytes_total{otel_metric_overflow="true"} (or the same on network.packets) means you are over the cap — raise metric_limit or lower flow cardinality (ephemeral source_port is the biggest driver). tailscale2otel.series.active pins at the same cap, so it flags the condition too.

Devices (tailscale.device.*, tailscale.devices.count)¶

Per-device gauges plus a fleet roll-up. "id dims" below is shorthand for the common device-identity attribute set: host_name, host_id, os_type, os_version, tailscale_user.

Users (tailscale.users.count, tailscale.user.*, tailscale.user_invites.count)¶

User roll-ups and per-user gauges. Per-user "id dims" = enduser_id, tailscale_user_login.

Keys (tailscale.key.*, tailscale.keys.count)¶

Per-entity gauge gating: the per-device, per-user, and per-key gauges above are gated by cardinality.per_entity.device / cardinality.per_entity.user / cardinality.per_entity.key (all on by default). Set one to false to drop that collector's per-entity series and keep only its aggregate *.count roll-up; the key-expiry warning log still fires regardless.

Settings / ACL / DNS (tailscale.setting.*, tailscale.acl.*, tailscale.dns.*)¶

Contacts (tailscale.contact.*)¶

Tailnet contact verification status. The contact email is never emitted (PII); only whether each contact type (account/support/security) still needs verification — an unverified security contact is worth alerting on.

Webhook endpoints (tailscale.webhook_endpoint*.*)¶

Inventory of configured webhook endpoints (where Tailscale posts event notifications) — distinct from the stream/webhook receiver metrics. Endpoint URL, secret and creator are never emitted. The per-endpoint subscriptions gauge is gated by cardinality.per_entity.webhook.

Posture integrations (tailscale.posture_integration*.*)¶

Device-posture provider integrations (MDM/EDR such as Intune) and their sync health. Alert on tailscale.posture_integration.last_sync going stale. Provider identifiers (clientId/tenantId/cloudId) are never emitted.

Log streaming health (tailscale.logstream.*)¶

Tailscale's own view of whether it is successfully delivering your configuration and network logs to a configured SIEM sink (a meta-signal, independent of the flow/audit collectors). The cumulative counters are emitted as deltas (use rate()). On a tailnet with no SIEM sink the status endpoint returns 4xx/empty → tailscale.logstream.configured = 0 and no health series (no error noise). The error text is on the tailscale.logstream.error log event, never a metric label.

Tailscale Services / VIP (tailscale.service*.*)¶

Tailscale Services (VIP services) and their backing hosts. Service addresses, comments and annotations are never emitted. The per-service ports/hosts gauges are gated by cardinality.per_entity.service; hosts additionally requires collect_hosts (one extra API call per service).

Features (tailscale.feature.*)¶

tailscale.feature.enabled for network-flow-logging is emitted in both ingestion modes: the flowlogs poller emits it directly when polling, and under source: stream a lightweight feature probe emits it on the flowlogs interval — so the signal is never lost when only the receiver runs.

Receivers — stream & webhook (tailscale.stream.*, tailscale.webhook.*)¶

Health/throughput counters for the optional HEC log-stream receiver and the webhook receiver.

Node metrics scraper (tailscale.node.* + forwarded series)¶

The scraper emits one curated metric — the per-target health gauge below — and otherwise forwards every scraped tailscaled series verbatim. Those forwarded series are runtime-named and are not part of the curated catalog; see the dedicated Node metrics scraper section for the forwarding behavior and setup.

Reverse DNS (tailscale.rdns.*)¶

Self-observability for the reverse-DNS (PTR) enrichment cache (enrichment.reverse_dns). Emitted only when self_observability.enabled is true; the admin status page shows the same figures directly from the cache regardless. queries is the load placed on the upstream resolver and should stay low relative to lookups; a non-zero overflows rate means max_entries is too small.

Log events¶

Structured OTEL log records. They are exported via OTLP and land in Loki under datasource uid grafanacloud-logs, all tagged with the label service_name="tailscale2otel".

The OTEL event type is carried in the native log-record EventName field (set via the log SDK's SetEventName, log v0.20.0+ — not a separate event.name attribute). Grafana Cloud's OTLP→Loki ingestion exposes it as event_name, so you filter on event_name in LogQL (e.g. | event_name="tailscale.config.audit"); the value keeps its dots. Verified live against Grafana Cloud: the native EventName produces the same event_name key the earlier event.name attribute did, so existing queries and the bundled dashboards are unaffected by the S4-1 migration.

The tailscale_node_hostname attribute on tailscale.network.flow is populated only when the node IP/ID could be resolved against the device-enrichment cache; otherwise the record carries the raw tailscale_node_id/addresses without a hostname.

Device posture — metric vs. log. Posture is exposed two ways. The metric tailscale.device.posture (→ tailscale_device_posture_ratio, a constant-1 info gauge, one series per device) carries a curated, low-cardinality label set (os, os_version, ts_version, auto_update, encrypted, track) and is emitted every scrape — use it for fleet analytics (version skew, auto-update/encryption coverage, release-track outliers). The log tailscale.device.posture carries the full raw posture attribute set and, by default (posture_log_mode: changes), is emitted only when a device's posture changes — a full baseline dump on the first scrape after start, then per-device deltas — so it reads as an audit trail rather than a per-minute snapshot. Note that the device's own OS is node_os / node_osVersion (and the metric's os / os_version labels); the resource-level os_type / os_description on any signal describe the collector host, not the device.

Device posture attributes as metrics (MDM/identity integrations). Beyond the curated tailscale.device.posture gauge above, the allow-listed posture-attribute namespaces (default: intune, jamf, kandji, crowdstrike, sentinelone, kolide, ip — see collectors.devices.attribute_namespaces) are promoted to two metrics, reusing the same per-device attribute fetch (no extra API calls; both gated by collect_posture). Each attribute lands in exactly one, by value type: booleans/numbers become tailscale_device_attribute_ratio (the value carries meaning — 0/1 for booleans, the number otherwise), and strings/enums become tailscale_device_attribute_info_ratio (constant 1, the value carried in the value label). So avg(tailscale_device_attribute_ratio{attribute="intune:isEncrypted"}) is the encrypted-fleet fraction, tailscale_device_attribute_ratio{attribute="intune:isEncrypted"} == 0 finds unencrypted devices, and count by(value)(tailscale_device_attribute_info_ratio{attribute="intune:complianceState"}) breaks the fleet down by compliance state. Series count ≈ devices × allow-listed attributes present (bounded for enum/bool); node:* is omitted from the default (already on the curated posture gauge) and custom:* is excluded by default since its values are operator-defined. Set attribute_namespaces: ["*"] to promote every namespace, or [] to disable.

Node metrics scraper¶

The node metrics scraper (P3) is an optional, gated collector that scrapes the Prometheus metrics endpoint exposed by tailscaled on one or more nodes and forwards them through the same OTLP pipeline. For how to expose those endpoints on each node (enabling --webclient, the :5252 port, the required ACL grant, and per-target auth/TLS), see How to expose tailscaled metrics.

Key behavior:

• Verbatim forwarding. Each scraped tailscaled series is re-emitted with its original metric name and original labels preserved — these are not renamed into the curated tailscale.* namespace and are not subject to our semconv naming. (Grafana Cloud's standard OTLP→Prometheus normalization still applies on ingest.)
• An added tailscale_node label. Every forwarded series gains a tailscale_node label (OTEL attribute tailscale.node) identifying the scraped node, so you can distinguish series across targets. It is deliberately not called instance: on Grafana Cloud the OTLP→Prometheus translation promotes the exporter's service.instance.id resource attribute to the instance label, which would overwrite a per-node instance and collapse every node's series onto the collector host.
• Instrument mapping. Counters from the node are re-emitted as deltas; gauges are re-emitted as gauges.
• Per-target up signal. A tailscale.node.up gauge (→ tailscale_node_up_ratio) is emitted per target with the tailscale_node label, reporting whether the last scrape of that node succeeded.
• Cardinality controls (optional). collectors.node_metrics.metric_allow / metric_deny (anchored regexes on the forwarded metric name, allow-then-deny) and drop_labels (label keys stripped from every forwarded series) trim the verbatim stream. They never affect tailscale.node.up or the tailscale2otel.nodemetrics.discovery.* gauges, and the tailscale_node label is never dropped. The scraper also enforces per-target max_response_bytes / max_samples limits, while dynamic discovery is bounded by discovery.max_targets.

Node identity is carried as labels (notably tailscale_node) on the forwarded series, not as OTEL Resource attributes. This keeps the forwarded metrics queryable alongside the rest of the fleet without needing resource-attribute joins.

Cross-source de-duplication (a failsafe — pick one method)¶

Choose ONE ingestion method per log type. For flow and audit logs, run either the poller (source: poll) or the HEC stream receiver (source: stream) — not both. Running both (source: both, or streaming.enabled while a collector still polls) means the same data can arrive twice; the exporter logs a WARN at startup when it detects this.

When data does arrive over more than one path, the shared audit and flow processors carry a dedup set that drops already-seen records (keyed on their stable identity) before the metric counters and log emitters. This is a best-effort FAILSAFE, not a guarantee — do not rely on it as a supported mode:

• Flow poll↔stream de-dup is reliable: the key is the connection tuple (nodeId|start|end|proto|src|dst), identical across both sources.
• Audit poll↔stream de-dup keys on the event identity eventGroupID|action|target.id|property (time-free, because a streamed audit record has no inner eventTime and is timed from the HEC envelope — its millisecond timestamp never matches the API's nanosecond eventTime). This is reliable in practice but theoretical edge cases exist, hence "failsafe".
• webhook + audit de-duplication is best-effort on a normalized (verb, subject, time-bucket) key (the two sources don't always share a perfectly stable key), so treat overlapping webhook/audit configurations as approximately, not exactly, deduplicated.

Querying in Grafana¶

Default datasources: metrics → grafanacloud-prom, logs → grafanacloud-logs.

PromQL (metrics)¶

Total network throughput (bytes/sec), summed across all dimensions:

sum(rate(tailscale_network_io_bytes_total[$__rate_interval]))

Throughput broken out by direction:

sum by (network_io_direction) (rate(tailscale_network_io_bytes_total[$__rate_interval]))

Number of devices currently online (filter the boolean gauge to 1):

count(tailscale_device_online_ratio == 1)

Is the exporter up?

tailscale2otel_up_ratio

Devices whose node key expires within 7 days:

(tailscale_device_key_expiry_seconds - time()) < (7 * 24 * 3600)

Scrape error rate by collector:

sum by (tailscale_collector) (rate(tailscale2otel_scrape_errors_total[$__rate_interval]))

LogQL (logs)¶

All audit events for the service:

{service_name="tailscale2otel"} | event_name="tailscale.config.audit"

Only audit events that were emitted at WARN (i.e. carried an error):

{service_name="tailscale2otel"} | event_name="tailscale.config.audit" | severity="WARN"

Per-connection flow records to a specific destination node:

{service_name="tailscale2otel"} | event_name="tailscale.network.flow" | tailscale_dst_node="my-host"