OpenTelemetry conventions

Maple accepts telemetry over the OpenTelemetry Protocol (OTLP). This page describes the attributes and conventions Maple reads to build its dashboards, service map and analytics.

Maple stores every OTel attribute you send verbatim. A curated set gets special treatment: pre-extracted into indexed columns at ingest, exposed as short filter aliases, rendered as colored badges, used to draw the service map, or ranked higher in the log attribute chips. Most of these follow the OpenTelemetry semantic conventions. If your SDK emits standard attributes, you usually don’t need to do anything extra.

Audit with Claude Code: maple-audit reviews an existing setup against these conventions per service, with severities, and fixes the gaps. See the maple-audit skill.

Sending data

This page covers what to put on your telemetry. Endpoints, authentication headers, content types and the standard OTEL_* environment variables are in the Ingest API reference. To set up an SDK, start at Instrument your application.

Service identity

The bare minimum every span needs. service.name is the primary axis Maple groups by. Without it, spans go to a synthetic unknown_service bucket.

Deployment and version tracking

Tag every span with these and you get per-environment and per-version slices across the services table, service map, and per-service overview.

vcs.repository.url.full and vcs.ref.head.revision are the OpenTelemetry semantic-convention keys. Use them exactly as named. Legacy spellings like deployment.commit_sha, git.repo, or app.repo_url are not read.

Set resource attributes via environment variable:

export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production,vcs.repository.url.full=https://github.com/acme/api,vcs.ref.head.revision=abc123"

In the search bar, env, environment, and commit_sha are short aliases. See Filter aliases below.

Span status codes

Maple stores span status codes as title-case strings. Maple’s ingest converts the OTLP status enum on the way in:

Set status through your SDK’s status API. You don’t need to convert anything yourself.

Title case matters when you filter or write queries. StatusCode = 'Error' matches. Uppercase (ERROR) or lowercase (error) variants match zero rows.

Only spans with status Error appear in error analytics.

Span kinds

Client spans get a small outgoing-arrow icon in HTTP labels and render their route as host+path so the destination is visible. Server spans render path-only. The service map and a service’s dependencies are built only from Client and Producer spans. A network call left on Internal does not appear on either.

HTTP attributes

The most heavily instrumented namespace. Maple extracts three fields into indexed columns at write time, then renders method, route, and status code in trace rows.

Fast columns

Filtering on these scans a small column instead of doing a per-row map lookup. The legacy and current OTel semconv names map to the same column. The first non-empty source wins, so you don’t need to migrate just for fast filtering.

Method color pills

http.method / http.request.method drives a colored pill on the span row:

Status badge tiers

http.status_code / http.response.status_code is rendered as a colored badge in the trace list:

In log chips, the same key scores 95, just below exception.*. See Attribute prominence scoring.

Route extraction and fallback chain

For full HTTP info, Maple tries each source in order until one matches:

• Method: http.method → http.request.method → span name (e.g. http.server GET /path, or bare GET /path).
• Route on server spans: http.route → http.target → url.path.
• Route on client spans: http.route → parsed url.full / http.url (host+path) → server.address / net.peer.name combined with url.path / http.target.
• Status: http.status_code → http.response.status_code.

If none of the route attributes are set, Maple falls back to the route in the span name.

So url.full (e.g. https://api.stripe.com/v1/charges) on a Client span is enough for route rendering. Emitting http.route is still preferred, because it’s a semantic path (/api/users/:id) instead of a high-cardinality URL.

Service map

The service map draws a node for each service and each database, and an edge for the calls between them. Calls to external HTTP hosts, message queues and RPC services are not drawn on the map. They are listed on the service’s Dependencies tab. Four rules make sure your spans show up correctly.

1. Service-to-service edges

Maple draws an edge when a Client or Producer span in one service has a child Server or Consumer span in another service, in the same trace. Two things make that work:

• The callee is instrumented, so it records its own Server or Consumer span.
• The caller propagates trace context (the traceparent header), so the callee’s span becomes a child of the client span.

Instrumented HTTP and RPC clients do both for you.

api:    GET /v1/users  (span.kind=Client, span_id=a1)
users:  GET /v1/users  (span.kind=Server, parent_span_id=a1)
                            └──> draws an edge api → users

peer.service does not draw edges. If the callee is not instrumented, or the caller drops traceparent, no edge is drawn. The call shows up at most as an external dependency on the caller’s Dependencies tab (see rule 3).

2. Database nodes

Set db.system.name and db.namespace on database Client spans. The legacy db.system spelling is also accepted. Maple keys each database node on the pair, so services that call the same database share one node.

SELECT * FROM users  (span.kind=Client, db.system.name=postgresql, db.namespace=users_db)
                            └──> draws an edge api → postgresql users_db

Without db.system.name, the call is treated as an external HTTP or other dependency, not a database. Without db.namespace, Maple falls back to the legacy db.name, then to the host (server.address). With none of these set, every database behind that driver collapses into one node.

3. External dependencies

Other outbound Client and Producer spans become external dependencies. They are listed on the calling service’s Dependencies tab, not drawn on the map. Maple names each one from these attributes:

HTTP client instrumentation sets server.address automatically.

4. Pick canonical names

Keep db.system.name, messaging.system, and rpc.system values spelled the same across services. If one service emits db.system.name=postgresql and another emits PostgreSQL, they become separate database nodes. Use the OpenTelemetry well-known values where one exists.

Database queries

Besides the service map, these drive the log chips and the AI error-debug prompt context.

Caching

Maple detects a cache span when cache.system or cache.result is present. When detected, the trace UI renders a hit/miss badge and an operation pill (GET / SET / DELETE) on the span row.

Errors and exceptions

Drives the error banner in the log detail panel and the highest-priority chip on every log row.

Any attribute matching exception.* scores 100 (top of the log chips) and is toned error (red).

If the message runs past 3 lines or 160 characters, the banner collapses by default and shows a “Show more” toggle.

RPC

For gRPC and other RPC frameworks.

User identity

Promotes user/customer context to the log chips so it’s visible at a glance on every log row.

Logs

Severity levels

SeverityText drives the per-row text color in the log list and the trace detail timeline.

ERROR and FATAL severities also show the error banner at the top of the log detail panel.

Trace correlation

Logs are automatically correlated with traces when TraceId and SpanId fields are present. Most OTel SDKs inject these fields when a span is active.

Kubernetes and infrastructure

Kubernetes resource attributes power the service map’s pod-count badges and the Infrastructure pages. The maple-k8s-infra Helm chart sets most of these for you via the OTel operator and the k8sattributes processor.

Workload identity (joins to service.name)

Promoted to log chips

Resource attributes normally stay out of log chips. These are the exceptions, along with deployment.environment.

Node detail metadata

Cloud and platform badges

These set the platform badge and runtime icon next to a service on the service map. SDKs running on common platforms detect most of them automatically. The keys are listed here so self-instrumenters can match.

A service with k8s.pod.name or k8s.deployment.name gets the Kubernetes badge. Cloudflare takes precedence over Lambda, and Lambda over Kubernetes.

nodejs, bun, deno, workerd, rust, python (or cpython), ruby, and the JVM (jvm, java, or the OTel-canonical OpenJDK Runtime Environment) render as their logo next to the service name. go, dotnet, php, and anything unrecognized render as a short text chip, because their logos are wordmarks that are unreadable at icon size. A runtime the platform badge already implies (workerd on a Cloudflare service) is not shown a second time.

Common aliases are folded together (node/nodejs, go/golang). Keep the value consistent across services on the same runtime anyway. An unlisted variant falls through to the text chip, and one fleet ends up wearing two different marks.

Filter aliases

In Maple’s WHERE-clause search bar (trace list, log search, dashboard widgets), you can type a short alias and it resolves to the canonical attribute:

So env = "production" and deployment.environment = "production" mean the same thing. Pick whichever is shorter.

Reserved namespace

maple_* is reserved for Maple platform internals (org routing, ingest auth keys). Do not use this prefix for your own attributes. The UI hides anything starting with maple_ from log attribute chips.

Attributes Maple hides from log chips

These are stored on the row but skipped from the log attribute chips because they’re noisy or already shown elsewhere (service column, etc.):

• service.name, service.namespace, service.instance.id, service.version
• telemetry.sdk.*
• process.runtime.*, process.executable.*
• os.*
• host.arch, host.name
• maple_*

The data is still queryable. You can filter or group by these in the search bar. They just don’t appear in the row’s attribute chips.

Appendix: attribute prominence scoring

Each log row shows every attribute that isn’t hidden as a chip, ordered by score. Higher score comes first.

Resource attributes appear in chips only if they’re in the promoted set (deployment.environment, deployment.environment.name, k8s.pod.name, k8s.namespace.name, cloud.region). A promoted resource attribute scores 10 lower than the same key on the log itself.

Metrics

Maple accepts OTLP metrics at /v1/metrics: sums (counters), gauges, histograms, and exponential histograms. Summary data points are not supported and are dropped at ingest.

For exact RED (rate, error, duration) metrics alongside sampled traces, derive metrics from every span with the Collector’s SpanMetrics connector before sampling. See Exact counts with SpanMetrics.

Data retention

How long each signal is kept depends on your plan. See Retention.