Semantic Conventions and Standard Attributes
What you'll learn: How OpenTelemetry's semantic conventions ensure your trace data speaks the same language across all services and tools.
The Problem of Inconsistent Naming
Imagine if one developer tagged HTTP status codes as http.status, another as status_code, and a third as response.code. When you try to analyze traces across these services, you'd need custom logic for every variation. Semantic conventions solve this chaos.
What Are Semantic Conventions?
Semantic conventions are OpenTelemetry's standardized naming rules for span attributes, metrics, and resource information. They define exactly what to call things and how to structure values, ensuring consistency across different:
- Programming languages
- Instrumentation libraries
- Backend systems
- Organizations
Think of it like agreed-upon metric units in science: everyone uses "meters" instead of inventing their own measurement names.
Common Convention Categories
HTTP Conventions:
http.method(GET, POST, etc.)http.status_code(200, 404, 500)http.urlorhttp.target
Database Conventions:
db.system(postgresql, mongodb, redis)db.statement(the query itself)db.operation(SELECT, INSERT)
Messaging Conventions:
messaging.system(kafka, rabbitmq)messaging.destination(queue/topic name)messaging.operation(publish, receive)
Why This Matters
When everyone follows these conventions, your observability tools can automatically:
- Group similar spans across services
- Build accurate service maps
- Create meaningful aggregations
- Enable cross-platform trace analysis without custom configuration
Key Takeaway: OpenTelemetry semantic conventions are the shared vocabulary that makes telemetry data portable and queryable across your entire distributed system—use them instead of inventing your own attribute names.