OpenTelemetry Semantic Conventions: A Shared Vocabulary

WHY IT EXISTS In a distributed system, a single user request can touch dozens of services written in different languages. If each service reports its status using different naming conventions (e.g., http_status, response.code, statusCode), creating a unified view of the request's journey is impossible. Semantic conventions solve this chaos by creating a single, shared standard.

THE MENTAL MODEL Semantic Conventions are a shared vocabulary for observability. They are a standardized set of names and meanings for attributes attached to traces, metrics, and logs. It's like an international agreement on what to call a stop sign, ensuring every tool understands the signal regardless of its origin. This allows platforms to understand and correlate data from any source that follows the rules.

HOW IT WORKS The OpenTelemetry project defines and maintains a registry of these conventions. For a given operation, like an HTTP request, the conventions specify standard attribute names (http.request.method, http.response.status_code), their data types (string, integer), and their meaning. Instrumentation libraries for frameworks like Express.js or Spring automatically apply these conventions, so you get standardized data out of the box.

WHEN TO USE IT Always use semantic conventions when instrumenting your code with OpenTelemetry. They are essential for any system with more than one service, especially in polyglot environments. They are the key to unlocking powerful features in observability platforms, like automatically generated service maps and correlated traces across different technologies like databases, message queues, and FaaS.

WHEN NOT TO USE IT You don't "not use" them, but you might need to extend them. If a standard convention doesn't exist for your specific domain (e.g., a custom business metric like shopping_cart.value), you should define your own custom attributes. The footgun is to override a standard attribute instead of adding your own; always namespace your custom attributes (e.g., app.user.tier) to avoid collisions with future standard attributes.

ONE CANONICAL EXAMPLE An outbound HTTP POST request to https://api.example.com/users would be instrumented with a span. Semantic conventions dictate this span should have attributes like: http.request.method="POST", server.address="api.example.com", and url.full="https://api.example.com/users". After the request completes with a 201 status, the attribute http.response.status_code=201 is added. Every OTel-compliant tool understands this structure.