OpenTelemetry span and attribute naming

Contract

Enforces OpenTelemetry semantic-convention names on every span and attribute you create: span names stay low-cardinality (template, never instance), attribute keys come from the registry in lowercase dot-namespaced form, and custom keys live in their own namespace. Apply when writing or reviewing tracing instrumentation; not for metrics, logs, backend choice, or sampling.

Rules

1. A span name identifies a class of operations, never one call. Nothing high-cardinality in

the name: no concrete ids, no full URLs, no query strings, no user names, no timestamps.

1. HTTP server span name = {method} {route template} — GET /users/{id},

POST /checkout. The template keeps its placeholder; concrete values go into attributes. If no route template is available, the name is just the method (GET) — never the raw path.

1. HTTP client span name = {method} (plus the template only when the client truly knows

it). POST, not POST https://host/v2/pay?attempt=3.

1. Database span name = {operation} {target} — SELECT invoices,

INSERT shipment_events, find sessions. Never the query text as the name.

1. HTTP attribute keys come from the registry:

• http.request.method — the method (GET) — not method, httpMethod, verb
• http.response.status_code — the code (200) — not status, statusCode, code
• http.route — the matched template (/users/{id})
• url.path — the concrete path (/users/4711) on the server side
• url.full — the complete URL on the client side (credentials redacted)
• server.address / server.port — the logical target host and port

1. Database attribute keys: db.system.name (postgresql, mysql, redis, mongodb),

db.operation.name (SELECT, GET, find), db.collection.name (table or collection), and db.query.text only when capture is deliberate and parameterized.

1. Errors: record the low-cardinality failure class under error.type (exception class

name, or the status code as a string) and set the span status to error. The human-readable message is never promoted into an attribute KEY.

1. Naming grammar for every key: lowercase; namespaces joined by dots; multi-word segments

in snake_case (status_code). Never camelCase, never spaces, never bare words.

1. Custom attributes get your own namespace — app.cart.value, app.user.plan_tier, or a

company-domain namespace. Never invent keys inside a registry namespace (http.*, db.*, url.*, server.*), and never emit bare keys like userId or cartValue.

Worked examples

Server span name — instance data moves out of the name into attributes:

BEFORE  tracer.start_span("GET https://api.shipfast.example/shipments/8842?expand=events")

AFTER   tracer.start_span("GET /shipments/{shipment_id}")
        span.set_attribute("http.route", "/shipments/{shipment_id}")
        span.set_attribute("url.path", "/shipments/8842")
        span.set_attribute("server.address", "api.shipfast.example")

Attribute keys — invented camelCase becomes registry keys; the custom key gets a namespace:

BEFORE  span.set_attribute("httpMethod", "GET")
        span.set_attribute("statusCode", 200)
        span.set_attribute("userId", "u-99")

AFTER   span.set_attribute("http.request.method", "GET")
        span.set_attribute("http.response.status_code", 200)
        span.set_attribute("app.user.id", "u-99")

Database span — the statement is not the name:

BEFORE  with tracer.start_as_current_span("SELECT * FROM invoices WHERE customer_ref = %s"):

AFTER   with tracer.start_as_current_span("SELECT invoices"):
            span.set_attribute("db.system.name", "postgresql")
            span.set_attribute("db.operation.name", "SELECT")
            span.set_attribute("db.collection.name", "invoices")

Failure recording — class, not prose, and no invented key:

BEFORE  span.set_attribute("errorMessage", "timed out after 30s talking to fx.upstream.example")

AFTER   span.set_attribute("error.type", "TimeoutError")
        span.set_status(StatusCode.ERROR)

Edge cases & exceptions

• No route template exists (raw middleware, catch-all proxy): the span name is the bare

method; the concrete path still goes to url.path.

• Query strings: never in the span name. On the client side the whole URL belongs in

url.full, with credentials stripped.

• One endpoint multiplexing many actions (a single RPC-over-POST route): keep the route in

the name; put the action under a namespaced custom key (app.action), don't fork the name.

• Retries: each attempt is its own span with the SAME name; the attempt number is an

attribute, not a name suffix.

• Migration from legacy keys: rename in code and translate old keys at the collector —

never emit both schemas from new code.

Do / Don't

• Do name server spans {method} {template}. Don't put ids, hosts, or query strings in a name.
• Do use http.request.method / http.response.status_code. Don't coin httpMethod /

statusCode / verb / code.

• Do put the concrete path in url.path. Don't overload the span name with it.
• Do record db.system.name + db.operation.name. Don't make SQL text the span name.
• Do namespace custom keys (app.*). Don't emit bare userId / cartValue keys.
• Do snake_case multi-word segments. Don't camelCase anything.

Common mistakes

• Full URL as the span name — a new name per request, so nothing aggregates.
• Handler-function span names with instance data baked in (getUser_4711).
• camelCase keys (httpMethod, responseTimeMs, dbQueryString).
• Free-text message keys (errorMessage, failureReason) instead of error.type + status.
• Custom data shoved into registry namespaces (http.user_id).
• The whole SQL statement as the database span name.

Quick checklist

• Span name: {method} {template} (server), {method} (client), {operation} {target} (db).
• No ids, URLs, query strings, or messages in any span name.
• HTTP keys: http.request.method, http.response.status_code, http.route, url.path,

url.full, server.address.

• DB keys: db.system.name, db.operation.name, db.collection.name.
• Failures: error.type + error status; custom keys namespaced, lowercase, dot/snake.