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

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.