/maple-otel-spec-review

name: maple-otel-spec-review
description: "Review a diff, PR, or specific file in this repo for OpenTelemetry *specification* compliance, grounded in the source-linked spec corpus at docs/otel-spec/ (snapshot v1.58.0). Triggers on requests like 'is this spec compliant', 'review this PR against the OTel spec', 'spec-review this diff', 'check my partial-success handling', 'are these retryable status codes right', 'does apps/ingest honor the OTLP spec', and on reviews of changes touching the OTLP server surface in apps/ingest (partial success, retryable set {429, 502, 503, 504}, protobuf Status bodies, gzip, OTLP/JSON encoding), self-instrumentation (apps/api tracer setup, apps/ingest/src/otel.rs, packages/effect-sdk), or consumers of span status / SeverityNumber / db.query.text (WarehouseQueryService, query-engine). Spec MUSTs and SHOULDs only. For Maple house conventions use maple-telemetry-conventions; for whole-project instrumentation audits use maple-audit; for general diff correctness use /code-review."
metadata:
  internal: true

OTel spec-compliance review

Review a diff, PR, or named file of *Maple's own code* against the *OpenTelemetry specification* as snapshotted in `docs/otel-spec/` (spec **v1.58.0**, researched 2026-07-05). The deliverable is spec findings: MUST/SHOULD violations with normative citations.

Neighbouring skills cover other ground:

• `maple-audit`: whole-project instrumentation-quality audit against Maple conventions, mostly for external projects.
• `maple-telemetry-conventions`: the house-conventions reference. Cross-reference it here; never enforce it from here.
• `/code-review`: generic diff correctness.

`docs/otel-spec/README.md` is the routing hub. The nine spec files beside it are the **only authority this skill may cite**. Every section in them carries an inline `Source:` deep link to the official spec; findings copy that link.

Severity

Severity comes from the spec's own normative word, not intuition:

| Severity | Meaning | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `critical` | Violates a MUST / MUST NOT / SHALL / REQUIRED in a Stable spec section: failing a whole batch instead of returning partial success, wrong retryable status set, non-protobuf error body, an SDK code path that can throw into the host app, dropping gzip decode. | | `warn` | Violates a SHOULD / SHOULD NOT, or newly relies on a deprecated path: new span-event usage for event-shaped data, deprecated semconv keys without coalescing, missing throttle hints on 429/503. | | `info` | MAY/recommendation divergence; anything grounded in a Development/Experimental-stability section; **any finding touching a README known-gap item (mandatory cap, tagged "unverified")**. |

Routing table

Map what the diff touches to the minimal spec sections. Route by heading text, never by line numbers. The surfaces are the three from `docs/otel-spec/README.md`: **1** ingest gateway as OTLP server · **2** self-instrumentation as SDK consumer · **3** UI/query as data consumer.

| Diff touches (path or content signal) | Surface | Load (file → `##`/`###` headings) | | --- | --- | --- | | `apps/ingest` OTLP handlers: request decode, response building, status codes | 1 | otlp.md → `Request/response shapes` (esp. `Partial success (server MUST rules)`, `When to use partial success vs full failure (server MUST)`), `Failure handling` (esp. `HTTP status codes: retryable matrix`, `Throttling / backpressure (server SHOULD)`) | | OTLP/JSON parsing or serialization (IDs, enums, unknown fields) | 1 | otlp.md → `JSON encoding (OTLP/HTTP JSON): deviations from standard protobuf JSON`; proto field questions → `Proto schema essentials` | | gzip / content-type / transport handling in ingest | 1 | otlp.md → `Transports: gRPC vs HTTP` (esp. `Compression`, `Content types`) | | Inbound `traceparent`/`tracestate`/baggage handling; propagator config | 1/2 | context-propagation.md → `W3C Trace Context: traceparent` (esp. `Practical MUSTs for an ingest gateway`), `W3C Trace Context: tracestate`, `Baggage`; propagator wiring → `Propagators API` | | Span creation/status/kind sites: `apps/ingest/src/otel.rs`, `tracing::info_span!` / `otel.kind`, `apps/api` tracer setup, `packages/effect-sdk/` | 2 | traces.md → `3. Span`, `4. SpanKind`, `6. TracerProvider / Tracer`; error-handling posture → stability-and-compliance.md → `5. Error-handling principles (fail-safe requirements)`; scope naming → stability-and-compliance.md → `7. Library / instrumentation guidelines` | | Span processors, exporters, sampling config | 2 | traces.md → `12. Sampling (SDK)`, `15. Span Processor`, `16. Span Exporter`, `13. Span Limits` | | Resource attributes, `OTEL_*` env vars, exporter endpoints | 2 | resource-and-config.md → `1. Resource: definition, immutability, merge rules`, `3. Key resource semantic conventions`, `5. SDK environment-variable spec (consolidated table)`; endpoint rules → otlp.md `Exporter configuration (OTEL_EXPORTER_OTLP_*)` | | New/renamed attribute keys (`setAttribute`, `annotateCurrentSpan`, `record(...)`, `#[instrument(fields(...))]`) | 2/3 | semantic-conventions.md → `General rules` + the one matching domain section (`HTTP`, `Database`, `Messaging`, `RPC`, `Exceptions`, `Gen-AI`) | | Consumers of status / severity / db keys: `WarehouseQueryService` (`packages/backend/src/services/warehouse/`), `packages/query-engine`, `packages/domain/src/tinybird/`, UI classification code | 3 | semantic-conventions.md → matching domain section (HTTP status rule: