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

In Span Name	In Span Attributes
Operation type	User IDs
Resource category	Invoice numbers
	Campaign names, zip codes
	Parameter values
	Status/outcome (use span status)

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)

Status Code	Server Span	Client Span
1xx, 2xx, 3xx	Unset (OK)	Unset (OK)
4xx	Unset (client error)	Error
5xx	Error	Error

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