opentelemetry

name	opentelemetry
description	OpenTelemetry instrumentation conventions. Use when instrumenting code with spans, setting up tracing, or writing trace tests.
user-invocable	true
disable-model-invocation	true

OpenTelemetry

Span Naming

Use short, low-cardinality names from semantic conventions:

• HTTP: GET /users/{id} (method + route template, never full URL path)
• DB: SELECT users (operation + table)
• RPC: grpc.health.v1.Health/Check
• Messaging: orders process (destination + operation)

Attributes

Use semantic convention attribute names — never invent your own:

• HTTP: http.request.method, url.full, http.response.status_code, server.address
• DB: db.system, db.statement, db.namespace
• General: error.type, service.name

Import from the versioned semconv package (e.g., go.opentelemetry.io/otel/semconv/v1.x).

Status

Only set status on errors: span.SetStatus(codes.Error, err.Error()). Never set Ok — unset is the success state. Call RecordError alongside SetStatus; it only adds a span event, doesn't change status.

For HTTP: 4xx is Error on client spans, Unset on server spans. 5xx is always Error.

Testing

Use in-memory exporters with SimpleSpanProcessor (not batch — batch introduces timing). Assert on exported spans' names, attributes, and status. No mocking needed.

Boundaries

Instrument network calls, I/O, and queue operations — not every function. Use span events (AddEvent) instead of separate log statements for events within a traced operation.