Skip to main content

Telemetry & Compatibility

Canonical reference for FleetForge's OpenTelemetry integration, semantic-versioning policy, and collector settings. Pair this page with docs/roadmap/roadmap-and-status.md to track delivery of new telemetry capabilities.

GenAI semantic conventions​

  • FleetForge instruments every runtime hop with the GenAI semantic conventions plus the FleetForge-specific trust.* attribute family (trust.capability_token_id, trust.attestation_id, trust.policy_decision_id, trust.subject, trust.semconv.version). See core/runtime/src/otel.rs for the canonical list.
  • Set OTEL_SEMCONV_STABILITY_OPT_IN=gen-ai on collectors/exporters so they decode the GenAI schema and avoid “unknown attribute” warnings while the spec iterates.
  • trust.semconv.version records the proposal version emitted during a run. Operators can pin older dashboards to that version while shimming queries for the upcoming release.

Dual emission & pinning​

  • During upgrades, the runtime dual-emits the current and previous semantic convention sets. Translators in core/telemetry/ handle the downgrade path so collectors never see incomplete spans.
  • Use FLEETFORGE_TRUST_SEMCONV_PIN=vX.Y (or the Helm equivalent) to force a workspace onto a specific schema while downstream dashboards catch up. The runtime logs the pin at startup and annotates spans with trust.semconv.pinned=true for auditing.
  • When the pin is removed, the runtime automatically promotes the workspace to the latest version and stops emitting the compat layer after one release cycle.

Collector checklist​

  1. Metrics + traces – Export both metrics and traces pipelines so budgets, replay drift, and attestation metadata stay correlated. The default Grafana dashboards in deploy/otel/dashboards/ expect both.
  2. Attribute allowlists – If you are stripping attributes for PII compliance, make sure the allowlist includes every trust.* key; otherwise receipts and policy IDs will disappear downstream.
  3. Testing – The how-to/clickhouse-grafana guide covers local validation against the demo collector. Re-run that guide whenever OTEL dependencies change to ensure the shim + pin flags still work.

References​

  • Implementation: core/runtime/src/otel.rs, core/telemetry/.
  • Demos: docs/quickstart/hello-fleet.md (Hello Fleet exposes the same spans you see in /demo).
  • Roadmap commitments: Telemetry versioning policy.