2.1 OpenTelemetry Semantic Conventions & Namespaces

OpenTelemetry Semantic Conventions & Namespaces

In modern distributed cloud-native systems, telemetry data is generated across dozens of microservices written in different programming languages—such as Go, Java, Python, TypeScript, and Rust. Without an overarching standard, individual software teams inevitably invent conflicting names for identical runtime concepts: one service records http_status=200, another reports statusCode=200, a third logs response_code="200", and a fourth uses HTTP.STATUS: 200.

This lack of uniformity creates a telemetry "Tower of Babel". Observability backends cannot correlate requests across service boundaries, engineers must write dozens of custom dashboard queries for every language runtime, and generic alerting rules across an entire fleet become impossible to maintain.

OpenTelemetry Semantic Conventions solve this problem by establishing a rigorous, standardized, vendor-neutral naming schema and attribute vocabulary for all telemetry data types (spans, metrics, logs, and resource entities). Maintained by the OpenTelemetry project (a CNCF project) in its semantic-conventions repository, Semantic Conventions ensure that whether a request originates in an ASP.NET service, transits a Go gateway, or queries a PostgreSQL database via Python, every observation describes identical semantics with identical keys and data types.

---

Why Semantic Conventions Are Essential

Adopting OpenTelemetry Semantic Conventions delivers four foundational operational advantages for site reliability engineers and developers:

1. Uniform Dashboards and Visualization: A single pre-built dashboard can display golden signals (rate, errors, duration) across 500 microservices without requiring custom per-service query logic or field rewriting.
2. Cross-Service Contextual Correlation: Standardized networking and remote procedure keys (such as server.address, server.port, client.address, and network.peer.address) enable APM tools and service meshes to infer system topology and render dynamic distributed service dependency maps automatically.
3. Generic Alerting Rules: Platform teams can author a single alerting rule—such as triggering a P1 notification whenever http.response.status_code >= 500 exceeds a 1% threshold over a 5-minute sliding window—that instantly evaluates telemetry across all services in an organization.
4. Automated Root Cause Analysis (AIOps and Anomaly Detection): Automated root cause engines parse structured attributes to isolate failing dependencies (for example, pinpointing an exhausted database connection pool via db.client.connection.count split by db.client.connection.state, or distinguishing downstream timeout anomalies via error.type).

---

Core Semantic Convention Namespaces

OpenTelemetry organizes attribute keys into a hierarchical dot-notated taxonomy (namespace.subsystem.attribute). Understanding these core namespaces is essential for candidates preparing for the OpenTelemetry Certified Associate examination.

1. HTTP Namespace (The Modernized Standard)

The HTTP renames arrived in semantic conventions v1.21.0 (July 2023), and the HTTP conventions were declared stable in v1.23.0 (November 2023). You will meet both the stable names and the legacy names in real data, so learn the mapping:

Exam Tip: On server spans, never put raw paths that contain IDs (such as /users/123849) into http.route or metric attribute dimensions! Storing arbitrary IDs creates high-cardinality unbounded sets that degrade metric database performance. Always record the route template "/users/:id" in http.route.

2. Database Namespace (db.*)

Database spans represent outbound client calls from an application to a persistent datastore, cache, or search engine. The core database conventions became stable in semantic conventions v1.33.0 (2025) and renamed most of the older keys:

The old db.user attribute is not part of the stable set.

Query Text and Sanitization

Production queries often contain personally identifiable information (PII) or secrets. The stable conventions handle this with SHOULD-level rules rather than a blanket ban:

• Non-parameterized query text SHOULD NOT be collected by default unless the instrumentation sanitizes it (for example, by replacing every literal value with ?).
• Parameterized query text (with placeholders such as ?, $1, or :val) SHOULD be collected by default, because the sensitive values travel separately as parameters.
• The parameter values themselves are opt-in, through db.query.parameter.<key>.

3. RPC & gRPC Namespace (rpc.*)

Remote Procedure Call conventions apply to structured protocol systems such as gRPC, Apache Dubbo, and Connect RPC. They reached Release Candidate status in semantic conventions v1.44.0 (August 2026) after several renames, so expect both forms in the field:

For gRPC, every status code other than OK should be treated as an error.

4. Cloud & Infrastructure Namespace (cloud.* & host.*)

Infrastructure attributes capture where an application runtime or container is hosted:

• cloud.provider: Cloud platform identifier: "aws", "gcp", "azure", "alibaba_cloud".
• cloud.platform: Specific compute platform: "aws_ec2", "aws_ecs", "gcp_compute_engine", "azure.vm" (the Azure values now use dots).
• cloud.region: Logical cloud data center region: "us-east-1", "europe-west3".
• cloud.account.id: Account or tenant ID: "123456789012".
• host.id: Unique machine identifier (e.g., AWS EC2 instance ID "i-0a8b9c1d2e3f").
• host.name: The hostname or FQDN: "worker-node-04.prod.internal".

5. Container & Kubernetes Namespace (container.* & k8s.*)

Containerized workloads in Kubernetes clusters utilize standardized entity coordinates:

• k8s.cluster.name: Name of the Kubernetes cluster: "prod-useast-eks".
• k8s.namespace.name: Kubernetes namespace: "payments-prod".
• k8s.pod.name: Specific pod replica name: "payment-processor-78db6c49bc-h9z4m".
• k8s.pod.uid: Unique UUID assigned to the pod by the Kubernetes API server.
• k8s.container.name: Specific container within the pod: "payment-worker".
• k8s.deployment.name: High-level deployment workload name: "payment-processor".
• container.id: The container ID assigned by the runtime, without any docker:// or containerd:// prefix: "a3bf90e006b2".

---

Stability Guarantees and Schema Evolution

Semantic conventions are published as part of the OpenTelemetry specification repository and evolve through formalized stability levels:

[ Development ] ---> [ Release Candidate ] ---> [ Stable ]
        (any convention can later be marked Deprecated)

1. Development (older documents call it Experimental): Conventions under active design. Keys may be renamed or replaced in a later release without backwards-compatibility guarantees.
2. Release Candidate: The design is expected to become stable; only limited changes are still possible.
3. Stable: Stable attributes guarantee backwards compatibility. An attribute's name, type, and meaning cannot change; a stable attribute that is superseded is deprecated rather than silently removed.
4. Deprecated: When an attribute is superseded (e.g., http.method replaced by http.request.method), it is marked deprecated with a pointer to its replacement. During the HTTP migration, instrumentations offered OTEL_SEMCONV_STABILITY_OPT_IN=http/dup to emit old and new names side by side, and http to emit only the new names.
5. Schema URLs (schema_url): Telemetry payloads include an explicit schema URL (such as https://opentelemetry.io/schemas/1.24.0) that documents which version of the semantic conventions was used when the data was produced. Observability collectors and backends can parse this schema URL to map legacy attributes to modern conventions automatically.

---

Top 15 Most Tested Semantic Convention Attributes

Review this reference table of 15 attributes you will meet constantly in real telemetry: