Skip to main content
In this section we cover how to define consistent names and attributes in OpenTelemetry for spans, metrics, logs, and resources. Following the official semantic conventions makes telemetry easier to correlate, query, and analyze across teams, tools, and environments. If an OpenTelemetry semantic convention already defines the attribute you need, reuse it — do not create your own attribute names. Reusing standard conventions improves interoperability and reduces friction when integrating with observability backends.
When possible, prefer the official OpenTelemetry semantic conventions for spans, metrics, logs, and resources. This enables better correlation and interoperability between observability signals and tools.
Do not invent new attribute names when an official OpenTelemetry attribute exists. Custom attributes should be used only for domain- or organization-specific context that has no equivalent in the specification.
Naming patterns used in OpenTelemetry semantic conventions
  • Use lowercase with dot-separated segments to add structure and meaning. Example: domain.entity.attribute.
  • Prefixes indicate the domain or system. Example: http, db, k8s, net.
  • Distinguish resource-level attributes (e.g., service.name) from span- or log-level attributes to enable correlation across signals.
Common attributes and when to use them Examples: resource attributes and span attributes
  • Resource attributes are attached to the process/service and are shared across telemetry signals for that service instance.
  • Span attributes provide contextual detail about a specific operation.
Resource attributes example:
Span attributes example for an HTTP server span:
Best practices and practical guidance
  • Prefer canonical attribute names from the OpenTelemetry semantic conventions to maximize compatibility.
  • Use resource attributes for stable, service-level information (e.g., service.name, service.version).
  • Use span or event attributes for transient, operation-specific context (e.g., http.method, db.statement).
  • When adding custom attributes:
    • Use a clear, dot-separated namespace that prevents collisions (for example, your organization domain or service name).
    • Document the custom attributes so other teams can reuse them consistently.
  • Normalize values where the convention expects a set of canonical values (for example HTTP methods or well-known status codes).
When to consult the specification
  • If you are unsure about an attribute name or where it should live (resource vs span), consult the OpenTelemetry semantic conventions.
  • Before introducing a custom attribute, check the specification for existing attributes that cover the same intent.
Links and references Adhering to these conventions helps teams build telemetry that is consistent, searchable, and easy to correlate across distributed systems. When in doubt, reuse the canonical attribute names from the OpenTelemetry specification.

Watch Video