# DRR-Experiment-Telemetry: Adoption of OpenTelemetry for FPF Compliance
**Status:** Accepted
**Date:** 2026-01-10
**Context:** Experiment Design (`SharedSchema/design/experiment.md`)
## 1. Context & Problem
To validate FPF Agent patterns, the experiment defined in `experiment.md` requires rigorous, lawful telemetry (G.12) to measure `TimeToCompletion` (A.15.1) and `HelpQuestionCount` (G.12).
Ad-hoc logging ("print statements") violates FPF Pattern A.15.1 `U.Work`, which requires a consistent, 4-dimensional record of occurrence (Identity, Window, Spec, Performer) grounded in a `U.BoundedContext`.
**Constraint:** We need a standard "carrier" for `U.Work` records that supports distributed tracing (for multi-step agent tasks) without building a custom observability stack.
## 2. Decision
Use **OpenTelemetry (OTel)** as the standard carrier for `U.Work` records, with a strict attribute schema to enforce FPF compliance.
### Schema Mapping
We implicitly map `U.Work` slots to OTel Attributes:
| FPF Anchor (A.15.1) | OTel Attribute | Rationale |
| :--- | :--- | :--- |
| **U.Work** (Holon) | `trace_id` + `span_id` | OTel's W3C context provides globally unique identity. |
| **Window** | `start_time` / `end_time` | Native OTel timestamps provide nanosecond precision. |
| **IsExecutionOf** | `fpf.spec_ref` | Mandatory. Links the run to its design-time `MethodDescription`. |
| **PerformedBy** | `fpf.performer_ref` | Mandatory. Identifies the `RoleAssignment` active. |
| **ExecutedWithin** | `fpf.context_ref` | Mandatory. Identifies the `U.BoundedContext`. |
| **EditionPins** | `fpf.edition_pins` | Captures versioning for reproducibility (Pattern A.4). |
## 3. Consequences
### Positive
- **Standardization:** We leverage industry-standard tooling (viewers, collectors) for FPF traces.
- **Lawful Telemetry:** Metrics (`duration`, `counts`) are derived *only* from these spans, ensuring single source of truth (G.12).
- **Auditability:** The `telemetry/` directory (containing JSON spans) becomes a valid `EvidenceGraph` carrier (G.6).
### Negative
- **Instrumentation Overhead:** All agent code must carry the `Otel Context` and propagate it.
- **Strictness:** Spans without `fpf.*` attributes are considered "non-conformant" and legally invisible to the experiment metrics.
## 4. Compliance Verification
(Per A.15.1 Checklists)
- [x] Does the carrier support start/end windows? (Yes, OTel Span)
- [x] Is the Spec reference mandatory? (Yes, via `fpf.spec_ref` attribute)
- [x] Is the Context explicit? (Yes, via `fpf.context_ref`)
