What Are Semantic Conventions?

The Standard Dictionary

OpenTelemetry doesn't just define how to send data (the wire protocol); it defines what the data should look like (the schema). Think of it like the difference between defining that letters must be written on paper versus defining a standard form with labeled fields that everyone fills out the same way.

Semantic Conventions are a versioned specification that tells you three things for every attribute:

1. Name: Use http.response.status_code, NOT http_status, status_code, or statusCode.
2. Type: It must be an Integer (not a string like "200").
3. Meaning: It represents the numeric HTTP response status code sent back to the client.

The conventions are organized into namespaces using dot notation. The namespace hierarchy makes attributes self-documenting — http.request.method decomposes into category http, component request, attribute method; db.system names the database vendor; k8s.pod.name names a Kubernetes pod.

By forcing everyone to use the same names, observability backends like Jaeger, Prometheus, Grafana, and Datadog can interpret and display the data automatically — enabling features like "show me all Postgres queries" or "group errors by HTTP status code" without any custom parsing rules.

Stability levels matter. Each convention attribute is marked as one of:
- stable — Safe to use in production. Will not change.
- experimental — Subject to change. Use with awareness.
- deprecated — Being phased out. Migrate away.

Always check the stability level before building dashboards or alerts on a convention attribute. An experimental attribute may be renamed in the next release.