Telemetry signals

Prometheus series, OTLP log records and their attributes, and example records. See Monitor transfers and device reports for how to read them.

Prometheus metrics

IRIS serves Prometheus on :9101 /metrics and exports the same values as OTLP metrics. Every family carries {image, info_hash} labels only; per-device and per-peer detail is in OTLP log records.

Throughput and progress are omitted for an image with no fresh device, rather than published as zero; freshness age is exported alongside. The iris_transfer_lifecycle_* family is omitted whole when the plan store is unreadable. The five iris_instruction_* families report on the two offline root keys: certificate and keylist age in days, roots attested within 180 days, and two status gauges (root_ceremony_overdue reads 0 on schedule, 1 due, 2 overdue). A field the server cannot read is omitted.

Traced and untraced origin bytes

The origin seeder knows exactly how many bytes it sent; which device received them is sampled from aria2's per-connection counters.

A peer that connects, takes bytes and disconnects between two samples is counted as untraced, not lost. Metric names use attributed; the matching OTLP attribute is iris.peer.attribution, covered under iris.device.peer_transfer_record below.

Prometheus labels never carry per-peer or per-device identity, because that would put unbounded peer identity into label cardinality. That detail is available only in the OTLP log records below.

OTLP log records

Terminal per-device reports, tracker lifecycle events, peer-policy operations, and measured peer rates and byte totals flow as OTLP logs. Event identity is the top-level eventName field. These are the otel.log.name values IRIS emits:

iris.device.transfer.report

The iris.device.report record is a reduced projection: device.id, iris.image.id, iris.report.event, iris.transfer.peers_total, network.peer.address. Use iris.device.transfer.report for completed bytes and verification fields; counting both counts one delivery twice.

iris.tracker.peer

iris.peer.policy

This record is count-only: it never carries role membership lists, raw rules, addresses, or origin-QoS option values.

See Roles and sharing-policy API for the fields behind these attributes.

iris.swarm.peer_rate

iris.transfer.lifecycle

A plan is the decision that one device should hold one image. It carries two ids for the life of that transfer:

Two event values, in the order they occur:

A planned record carries: event, iris.transfer.id, iris.plan.id, iris.device.id, device.id (both spellings, so either join works), iris.image.id, iris.torrent.info_hash, iris.transfer.planned_at. A seeding_started record repeats every planned attribute and adds iris.transfer.seeding_started_at, iris.transfer.checksum_verified_at, iris.transfer.report_received_at, iris.transfer.tracker_seeder_at, iris.device.observed_at, iris.device.report_created_at and, on a recovered promotion only, iris.transfer.recovered_promotion. See Monitor transfers and device reports for what these events prove.

A missing value is absent, never an empty string or a default: a plan minted before its torrent existed carries no iris.torrent.info_hash.

A planned event

The attributes array of a planned record (eventName is iris.transfer.lifecycle, severityText is INFO):

[
  { "key": "otel.log.name", "value": { "stringValue": "iris.transfer.lifecycle" } },
  { "key": "iris.telemetry.schema.version", "value": { "intValue": "2" } },
  { "key": "event", "value": { "stringValue": "planned" } },
  { "key": "iris.transfer.id", "value": { "stringValue": "4d1a6e0c73b94f2ea85d10c6b7f3928a" } },
  { "key": "iris.plan.id", "value": { "stringValue": "9f2c4b7a1d8e4f60b3a25c9107de4412" } },
  { "key": "iris.device.id", "value": { "stringValue": "203.0.113.3" } },
  { "key": "device.id", "value": { "stringValue": "203.0.113.3" } },
  { "key": "iris.image.id", "value": { "stringValue": "cat9k_iosxe.26.01.01" } },
  { "key": "iris.torrent.info_hash", "value": { "stringValue": "c8f4e2a1b09d7635fe1428a0d5c93b7614e0af82" } },
  { "key": "iris.transfer.planned_at", "value": { "stringValue": "2026-09-02T12:43:11.482Z" } },
  { "key": "event.id", "value": { "stringValue": "9f2c4b7a1d8e4f60b3a25c9107de4412.planned" } }
]

A seeding_started event

The same plan, ten minutes later. It repeats every planned attribute, including iris.transfer.planned_at, and adds:

[
  { "key": "event", "value": { "stringValue": "seeding_started" } },
  { "key": "iris.transfer.seeding_started_at", "value": { "stringValue": "2026-09-02T12:53:44.117Z" } },
  { "key": "iris.transfer.checksum_verified_at", "value": { "stringValue": "2026-09-02T12:53:44.117Z" } },
  { "key": "iris.transfer.report_received_at", "value": { "stringValue": "2026-09-02T12:53:44.117Z" } },
  { "key": "iris.transfer.tracker_seeder_at", "value": { "stringValue": "2026-09-02T12:48:30.905Z" } },
  { "key": "iris.device.observed_at", "value": { "doubleValue": 1788353602.0 } },
  { "key": "iris.device.report_created_at", "value": { "doubleValue": 1788353604.4 } },
  { "key": "event.id", "value": { "stringValue": "9f2c4b7a1d8e4f60b3a25c9107de4412.seeding_started" } }
]

iris.transfer.planned_at, iris.transfer.seeding_started_at, iris.transfer.checksum_verified_at, iris.transfer.report_received_at and iris.transfer.tracker_seeder_at are RFC 3339 strings with a fixed shape:

2026-09-02T12:43:11.482Z

UTC, always; exactly three fractional digits (...:11.000Z, never ...:11Z); a literal Z, never +00:00. The matching Splunk pattern is %Y-%m-%dT%H:%M:%S.%N%Z; these are string attributes, not int64. iris.device.observed_at and iris.device.report_created_at are float epochs on the device's own clock, not RFC 3339 strings. Show them, but never subtract a server instant from one as though the clocks agreed.

iris.swarm.peer_bytes

iris.device.peer_transfer_record

Emitted once per peer per completed transfer, from a device-side completion hook reading aria2's per-peer counters when the last piece lands.

The server classifies and pins each row's attribution once, at first export; see Data formats and states. A row the server did not resolve stays unknown rather than being folded into device.

The telemetry_observation payload

While a transfer is active, a device with streaming enabled embeds one telemetry_observation payload in its heartbeat, bounded at 8 KB. Only schema v == 2 is accepted; a malformed field is dropped without failing the heartbeat.

Announce counters are the device's own

The announce counters, including bytes uploaded and bytes downloaded, are device-authored: the device reports them and the tracker records what it was told.

Event identity

The device creates a report_id, frozen before its first POST. A retry after a crash sends the same report bytes and identifier, so the server stores it once. The exported event.id preserves that identity for downstream deduplication. Use the device observation timestamp for when the measurement was made, not the record's ingest timestamp. See Monitor transfers and device reports for how delivery stays consistent across a restart.

Reading iris_legacy_announce_participants

iris_legacy_announce_participants counts authenticated peers with no attributed device or seeder identity. A rotated-out seeder credential stays valid for IRIS_SEEDER_PREV_TTL; after that, its peer drops out of this gauge. Check iris_tracker_announces_refused_total and iris_tracker_announces_refused_expired_total alongside it, comparing changes over the same window.