Otel Name Span

Review or Create OpenTelemetry Span Names

Review or create span names that follow OTel Semantic Conventions, ensuring low cardinality, correct protocol-specific patterns, and proper attribute separation.

Before applying any rule below, fetch the latest naming guidance to check for updates:

• https://opentelemetry.io/docs/specs/semconv/general/naming/
• https://opentelemetry.io/docs/specs/semconv/general/trace/
• https://opentelemetry.io/blog/2025/how-to-name-your-spans/

If the fetched content contradicts any rule in this skill, follow the fetched content and flag the discrepancy.

Core Principle

Span names MUST have low cardinality. The name describes the class of operation, not the specific instance.

General Naming Pattern: {verb} {object}

• Verb: the work being done — process, send, calculate, render, validate
• Object: a noun describing what is acted upon — payment, invoice, order

This naturally produces low-cardinality names suitable for grouping and aggregation.

What Goes Where

Reference Material

Detailed guidance on specific topics is in the references/ directory:

• protocols.md — Protocol-specific span naming patterns (HTTP, DB, messaging, RPC)
• anti-patterns.md — Bad→good naming examples, cardinality red flags, attribute anti-patterns

Attribute Naming

• Pattern: {object}.{property} with dot separators
• Lowercase, snake_case within segments
• Namespace related attributes together: order.id, order.total, order.status
• Keep names stable; let values carry dynamic data: { "user.id": "12345" } not { "user_12345.action": "login" }

System-Specific Attributes

• Pattern: {system_name}.*.{property}
• Examples: cassandra.consistency.level, aws.s3.key
• The system name MUST match the value in *.system.name attribute

Attribute Requirement Levels

• Required: must always be present
• Conditionally Required: required under specified conditions
• Recommended: should be present when available
• Opt-In: included only when explicitly configured

Span Status Mapping (HTTP)

Review Checklist

When reviewing span definitions, verify:

1. Name has low cardinality — no IDs, timestamps, user data, full URLs 2. Follows {verb} {object} or protocol-specific pattern 3. Instance-specific data is in span attributes, not the name 4. Outcome/status uses span status, not the name 5. HTTP spans use route templates, not raw paths 6. DB spans use parameterized queries 7. Messaging spans follow {operation} {destination} pattern 8. Attributes use {object}.{property} dot-delimited snake_case 9. No service name, version, or environment in the span name 10. SpanKind is correct for the operation type

Output

Provide:

• List of spans reviewed with pass/fail per checklist item
• Suggested corrections for any violations
• Attribute placement corrections (name → attribute)
• SpanKind recommendation if missing or incorrect
• Protocol-specific pattern recommendation where applicable

Span Naming Anti-Patterns

Spec sources:

- https://opentelemetry.io/docs/specs/semconv/general/naming/

- https://opentelemetry.io/blog/2025/how-to-name-your-spans/

Bad Span Names

High-Cardinality Red Flags

• Names appearing only once in a trace
• UUIDs, user IDs, or timestamps in the name
• Hundreds of slight variations for the same operation
• Full URL paths instead of route templates

HTTP-Specific Anti-Patterns

Attribute Anti-Patterns

Cross-Cutting Mistakes

1. High-cardinality span names — IDs, user data, timestamps → use span attributes 2. Raw URL paths as span targets — /users/123 → use route templates /users/{id} 3. Service/version in span names — payment_service_process_v2 → use resource attributes 4. Outcome in span name — validation_failed → use span status for outcomes 5. Inconsistent naming across teams — userId vs user_id vs user.id → standardize 6. Missing semantic convention attributes — DB calls without db.system.name, db.statement won't correlate

Protocol-Specific Span Naming Patterns

Spec sources:

- https://opentelemetry.io/docs/specs/semconv/http/http-spans/

- https://opentelemetry.io/docs/specs/semconv/database/database-spans/

- https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/

- https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/

HTTP Spans

• Format: `{method} {route}` or just `{method}` if no low-cardinality route
• {method} = http.request.method value; use HTTP if method is _OTHER
• Server spans: use http.route (e.g., /users/:userID)
• Client spans: use url.template if available
• MUST NOT default to URI path — cardinality explosion

Examples:

• GET /api/users/:id
• POST /orders
• HTTP (unknown method)

Database Spans

• Hierarchy: {db.query.summary} > {db.operation.name} {target} > {target} > {db.system.name}
• {target} preference: db.collection.name > db.stored_procedure.name > db.namespace > server.address:server.port
• Parameterize queries by default; sanitize non-parameterized (replace literals with ?)

Examples:

• SELECT public.users
• INSERT products
• customers
• postgresql

Query Parameterization

• Collect parameterized queries by default
• For non-parameterized queries, sanitize by replacing literals with ?
• Example: SELECT * FROM users WHERE id = 123 → SELECT * FROM users WHERE id = ?

Messaging Spans

• Format: `{messaging.operation.name} {destination}`
• {destination} preference: messaging.destination.template > messaging.destination.name > server.address:server.port

Examples:

• create shop.orders
• send shop.orders
• process shop.orders
• settle shop.orders

RPC Spans

• Format: `{rpc.method}` or {rpc.system.name} as fallback
• Client spans: SpanKind.CLIENT; Server spans: SpanKind.SERVER

Examples:

• com.example.UserService/GetUser
• EchoService/Echo