Study guide
2.1 OpenTelemetry Semantic Conventions & Namespaces
OpenTelemetry Certified Associate OTCA
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Exam Overview & Observability Foundations
1.1 OTCA Exam Structure & Observability Paradigms 1.2 Core Telemetry Signals: Traces, Metrics, Logs & Baggage 1.3 Telemetry Analysis, SLOs & High Cardinality
2 Chapter 2: Semantic Conventions & Instrumentation Strategy
2.1 OpenTelemetry Semantic Conventions & Namespaces 2.2 Resource Attributes & Entity Modeling 2.3 Zero-Code vs Code-Based Instrumentation
3 Chapter 3: OpenTelemetry Architecture & The Data Model
3.1 Architectural Separation of API and SDK 3.2 The Core Trace Model: Spans, SpanContext & Links 3.3 Span Events, Attributes & Status Codes 3.4 Composability & Extension: Plugin Interfaces, Distributions & Contrib
4 Chapter 4: Distributed Tracing & Context Propagation
4.1 In-Process & Cross-Process Context Propagation 4.2 W3C Trace Context Specification 4.3 W3C Baggage & Alternative Propagators
5 Chapter 5: OpenTelemetry Metrics API & Instruments
5.1 Synchronous Metric Instruments 5.2 Asynchronous (Observable) Metric Instruments 5.3 Metric Aggregations & Temporality
6 Chapter 6: Logs Data Model & Logging Bridge API
6.1 OpenTelemetry Logs Data Model & Architecture 6.2 The Logging Bridge API & Log Appenders
7 Chapter 7: SDK Pipelines, Processors & Exporters
7.1 Span Processors & Exporters 7.2 Metric Readers & Log Processors 7.3 Standard Exporters & OTLP Wire Protocols
8 Chapter 8: Sampling Strategies, SDK Configuration & Agents
8.1 Head-Based Sampling & Built-in Samplers 8.2 Tail-Based Sampling vs Head-Based Sampling 8.3 OpenTelemetry SDK Configuration & Environment Variables 8.4 Zero-Code Agents: Configuration, Kubernetes Injection & Troubleshooting
9 Chapter 9: OpenTelemetry Collector Architecture & Pipelines
9.1 Collector Core Architecture & Component Lifecycle 9.2 Collector Configuration Structure & Pipelines 9.3 Essential Collector Extensions
10 Chapter 10: Collector Components: Receivers, Processors & Exporters
10.1 Standard Receivers & Ingestion Protocols 10.2 Core Processors & Execution Order 10.3 Standard Exporters & Delivery Guarantees
11 Chapter 11: Data Transformation & The OpenTelemetry Transformation Language (OTTL)
11.1 OTTL Concepts & Syntax Grammar 11.2 Transform Processor In Action 11.3 Advanced Connectors
12 Chapter 12: Collector Deployment, Scaling & Resilience
12.1 Agent vs Gateway Deployment Topologies 12.2 Scaling, Load Balancing & High Availability 12.3 Resilience: Backpressure, Buffering & Persistent Queues
13 Chapter 13: Maintaining, Debugging & Schema Evolution
13.1 Debugging Collector Pipelines & Telemetry Health 13.2 Troubleshooting Broken Traces & Context Loss 13.3 Schema Management & Telemetry Evolution
2.1 OpenTelemetry Semantic Conventions & Namespaces
Key Takeaways Explain This Topic AI
Semantic Conventions define a shared vendor-neutral taxonomy of attribute names and types across all telemetry signals
The HTTP semantic conventions (stable since v1.23.0) replaced legacy keys like http.method and http.status_code with http.request.method, http.response.status_code, and url.full
Stable database conventions (v1.33.0) rename db.statement to db.query.text; non-parameterized query text should not be captured by default unless its literal values are sanitized
Semantic conventions move through stability levels: Development conventions may change with breaking renames, whereas Stable conventions guarantee backwards compatibility
Consistent semantic naming enables uniform Grafana/APM dashboards, generic alerting rules, and automated root cause analysis across heterogeneous polyglot architectures
Last updated: September 2026
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:
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.
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.
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.
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:
Modern Stabilized Attribute Legacy (Deprecated) Attribute Type Description & Example
http.request.method http.method string HTTP request method normalized to uppercase: "GET" , "POST" , "PUT" , "DELETE" . Non-standard methods use "_OTHER" .
http.response.status_code http.status_code int Numerical HTTP response status code: 200 , 404 , 500 .
url.full http.url string Full absolute URL for client spans: "https://api.example.com/v1/orders?item=42" .
url.path http.target string Path component for HTTP requests: "/v1/orders" .
url.query http.target (query part) string The URI query component: "item=42" . Instrumentations should redact sensitive query values.
http.route http.route string The parameterized route template for server spans: "/users/:userId" or "/orders/{orderId}" . Prevents metric cardinality explosions.
server.address net.peer.name (client side) / net.host.name (server side) string Server domain or IP address: "api.example.com" .
server.port net.peer.port (client side) / net.host.port (server side) int Server port number: 443 , 8080 .
client.address http.client_ip string Client address as reported by the server (it may come from a forwarding header): "192.168.1.100" .
network.protocol.version http.flavor string Network protocol version: "1.1" , "2" , "3" .
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:
- Stable attribute Legacy attribute Example
- db.system.name db.system "postgresql" , "mysql" , "redis" , "mongodb"
- db.namespace db.name "production_users"
- db.query.text db.statement "SELECT customer_id, balance FROM accounts WHERE account_id = ?"
- db.operation.name db.operation "SELECT" , "INSERT" , "HMSET"
- db.collection.name db.sql.table and similar "accounts"
- db.query.summary (new) "SELECT accounts" , a low-cardinality summary suitable for span names
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:
- Current attribute Legacy attribute(s) Example
- rpc.system.name rpc.system "grpc" , "dubbo" , "connectrpc"
- rpc.method (fully qualified) rpc.service + rpc.method "orders.v1.OrderService/SubmitOrder"
rpc.status_code (string) rpc.grpc.status_code (integer) "OK" , "DEADLINE_EXCEEDED" , "UNAVAILABLE" (legacy integers 0 , 4 , 14 )
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)
Development (older documents call it Experimental ): Conventions under active design. Keys may be renamed or replaced in a later release without backwards-compatibility guarantees.
Release Candidate: The design is expected to become stable; only limited changes are still possible.
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.
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.
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:
- # Attribute Key Target Namespace Canonical Type Example Value
- 1 http.request.method HTTP string "POST"
- 2 http.response.status_code HTTP int 200
- 3 http.route HTTP string "/api/v2/items/{id}"
- 4 url.full URL / HTTP string "https://api.shop.com/checkout"
- 5 server.address Server / Network string "auth.internal.net"
- 6 server.port Server / Network int 8443
- 7 db.system.name Database string "postgresql"
- 8 db.namespace Database string "orders_db"
- 9 db.query.text Database string "SELECT * FROM orders WHERE id = ?"
- 10 db.operation.name Database string "SELECT"
- 11 rpc.system.name RPC string "grpc"
- 12 rpc.method RPC string "inventory.v1.WarehouseService/CheckStock"
- 13 error.type General string "timeout" , "500"
- 14 rpc.status_code RPC string "UNAVAILABLE"
- 15 k8s.pod.name Kubernetes string "auth-service-5c678-8v2w1"