maple-telemetry-conventions

# Maple Telemetry Conventions Reference for the language-agnostic OpenTelemetry conventions Maple uses across TypeScript (`apps/api` and the other Workers, via `@maple-dev/effect-sdk` in `packages/effect-sdk/`), Rust (`apps/ingest`), and any future Python service. These conventions are load-bearing. Tinybird materialized views pre-extract some attribute keys into columns, dashboards filter on Title Case status strings, and throughput math depends on the `SampleRate` column. Use the exact attribute spellings here in every language. ## When to apply - Adding `setAttribute` / `Effect.annotateCurrentSpan` / `Span::current().record(...)` / `#[instrument(fields(...))]` to any code path - Setting span status (Ok / Error / Unset) - Wiring a new query through `WarehouseQueryService.compiledQuery()` (the `context` and `profile` options become span attributes) - Configuring an OTLP exporter, tracer provider, or resource builder - Introducing a new pre-extracted MV column or a new vendor attribute under `maple.*` - Reviewing a PR that touches `packages/query-engine/src/execution/executor.ts`, `apps/ingest/src/main.rs`, `apps/ingest/src/otel.rs`, `apps/api/src/http/api-observability.ts`, `packages/effect-sdk/src/cloudflare/`, `packages/infra/src/cloudflare/worker-telemetry.ts`, or `packages/domain/src/tinybird/materializations.ts` ## Index - `rules/span-attributes.md`: the main custom attribute keys Maple emits, grouped by namespace, with the file that sets each. - `rules/status-and-kind.md`: Title Case status codes (`Ok`/`Error`/`Unset`), the server-span 4xx rule, and span kinds (`Server` / `Client` / `Internal`). - `rules/resource-attributes.md`: `service.*` identity, `deployment.environment.name` resolution order, the deprecated `deployment.environment` dual-emit and read-side coalesce, and `maple_org_id`. - `rules/language-bindings.md`: parallel TypeScript / Rust / Python snippets that emit the same attribute keys. - `rules/mv-first-class-columns.md`: which span and resource attributes Tinybird MVs pre-extract into columns, and the rule for adding new ones. - `rules/service-map-attribution.md`: what the service map needs to draw service edges, database nodes, runtime icons, and platform badges, plus the `peer.service` naming registry. - `rules/loop-prevention.md`: the guards that keep Maple's self-traffic from feeding back on itself: the API `TracerDisabledWhen` filter, the ingest loopback guard, and sampling. ## Quick reference | Topic | Rule | |---|---| | Status codes | Always Title Case: `"Ok"`, `"Error"`, `"Unset"`. Never `OK`, `ERROR`, `SUCCESS`, `FAILED`. | | Vendor namespace | Custom attributes go under `maple.*`. Sub-namespaces include `maple.ingest.*`, `maple.cloudflare.*`, `maple.query.*`. | | Standard semconv | Use OTel semconv keys verbatim: `service.name`, `http.request.method`, `db.system.name`, `error.type`. | | Org identity | `orgId` (camelCase) in TypeScript spans, `maple.org_id` (dotted) in Rust spans. Don't unify until MVs migrate. | | Deployment env | Emit `deployment.environment.name` (our SDKs dual-emit the deprecated `deployment.environment` too). **Read** both via `DEPLOYMENT_ENV_SQL` / `deploymentEnvExpr`, never a bare map lookup. | | Warehouse SQL spans | Every `WarehouseQueryService.executeSql` span (a `Client` span) carries `db.system.name`, `peer.service`, `db.query.text`, `db.query.fingerprint`, `db.duration_ms`, `result.rowCount`, `orgId`, `query.context`, and `query.profile` when set. Legacy spans (pre 2026-06) use `db.statement*`/`db.system`; warehouse readers coalesce both. | | Service map | Service-to-service edges come from joining a `Client`/`Producer` span to its child `Server`/`Consumer` span in another service, so propagate trace context and set span kinds. Database nodes need `db.system.name` (plus `db.namespace`) on a `Client`/`Producer` span. Runtime icon and platform badge need `process.runtime.name`, `cloud.platform`, `maple.sdk.type` on the resource. See `rules/service-map-attribution.md`. | | Loop prevention | Never remove `HttpMiddleware.TracerDisabledWhen` (`apps/api/src/http/api-observability.ts`) or the ingest loopback guard (`init_tracing` in `apps/ingest/src/main.rs`). | ## Canonical references (do not modify from this skill) - `packages/query-engine/src/execution/executor.ts`: `WarehouseQueryService.executeSql` span emission, the canonical TS example. - `apps/ingest/src/otel.rs`: resource builder (`build_resource`), platform detection, and the client-span helpers (`forward_client_span`, `export_client_span`). The canonical Rust example for resource and outbound-span attribution. - `apps/ingest/src/main.rs`: `handle_signal` and `handle_cloudflare_logpush` open the Server-kind `tracing::info_span!` for inbound OTLP and Logpush. - `apps/api/src/http/api-observability.ts`: the `TracerDisabledWhen` filter and header redaction list. - `packages/effect-sdk/src/cloudflare/index.ts`: `MapleCloudflareSDK` tracer setup. Maple's own Workers wrap it with `WorkerTelemetry` in `packages/infra/src/cloudflare/worker-telemetry.ts`. - `packages/domain/src/tinybird/materializations.ts`: MV `SELECT` lists that pre-extract attribute keys into columns.