opentelemetry-semantic-conventions

Standardized attribute and resource names for OpenTelemetry

opentelemetry-semantic-conventions

Version: 0.31.0

The opentelemetry-semantic-conventions crate provides standardized naming patterns for attributes, metrics, and resources in OpenTelemetry, ensuring consistency and interoperability across telemetry data.

Installation

[dependencies]
opentelemetry-semantic-conventions = "0.31"

Feature Flags

• semconv_experimental: Include experimental semantic conventions (not yet stable)

What are Semantic Conventions?

Semantic conventions are agreed-upon naming standards for telemetry attributes, helping:

• Interoperability: Different tools understand the same attribute names
• Consistency: Uniform naming across services and languages
• Automation: Backends can provide better visualizations and insights
• Discovery: Easier to search and correlate telemetry data

Schema Version

This crate implements semantic conventions version 1.36.0.

use opentelemetry_semantic_conventions::SCHEMA_URL;

println!("Schema URL: {}", SCHEMA_URL);
// https://opentelemetry.io/schemas/1.36.0

Modules

The crate is organized into several modules:

attribute · module

Common attribute names for spans, logs, and metrics

resource · module

Resource attribute names (service, host, container, etc.)

metric · module

Standard metric names and units

trace · module

Trace-specific semantic conventions

Common Usage

Resource Attributes

use opentelemetry::KeyValue;
use opentelemetry_sdk::Resource;
use opentelemetry_semantic_conventions::resource::{
    SERVICE_NAME,
    SERVICE_VERSION,
    DEPLOYMENT_ENVIRONMENT,
};

let resource = Resource::new(vec![
    KeyValue::new(SERVICE_NAME, "my-service"),
    KeyValue::new(SERVICE_VERSION, "1.2.3"),
    KeyValue::new(DEPLOYMENT_ENVIRONMENT, "production"),
]);

Span Attributes

use opentelemetry::{trace::Tracer, KeyValue};
use opentelemetry_semantic_conventions::attribute::{
    HTTP_REQUEST_METHOD,
    HTTP_RESPONSE_STATUS_CODE,
    URL_FULL,
    SERVER_ADDRESS,
    SERVER_PORT,
};

let tracer = /* get tracer */;
let mut span = tracer.start("HTTP GET");

span.set_attribute(KeyValue::new(HTTP_REQUEST_METHOD, "GET"));
span.set_attribute(KeyValue::new(URL_FULL, "https://api.example.com/users"));
span.set_attribute(KeyValue::new(SERVER_ADDRESS, "api.example.com"));
span.set_attribute(KeyValue::new(SERVER_PORT, 443));
span.set_attribute(KeyValue::new(HTTP_RESPONSE_STATUS_CODE, 200));

Metric Attributes

use opentelemetry::{global, KeyValue};
use opentelemetry_semantic_conventions::attribute::{
    HTTP_REQUEST_METHOD,
    HTTP_ROUTE,
    HTTP_RESPONSE_STATUS_CODE,
};

let meter = global::meter("my-service");
let counter = meter.u64_counter("http.server.requests").build();

counter.add(1, &[
    KeyValue::new(HTTP_REQUEST_METHOD, "GET"),
    KeyValue::new(HTTP_ROUTE, "/api/users"),
    KeyValue::new(HTTP_RESPONSE_STATUS_CODE, 200),
]);

Common Attribute Names

HTTP

use opentelemetry_semantic_conventions::attribute::{
    // Request
    HTTP_REQUEST_METHOD,          // "GET", "POST", etc.
    HTTP_REQUEST_BODY_SIZE,       // Request body size in bytes
    HTTP_ROUTE,                   // Route pattern: "/users/{id}"
    
    // Response
    HTTP_RESPONSE_STATUS_CODE,    // 200, 404, 500, etc.
    HTTP_RESPONSE_BODY_SIZE,      // Response body size in bytes
    
    // URL
    URL_FULL,                     // Complete URL
    URL_SCHEME,                   // "http", "https"
    URL_PATH,                     // "/api/users"
    URL_QUERY,                    // "?page=1&limit=10"
    
    // Server
    SERVER_ADDRESS,               // "api.example.com"
    SERVER_PORT,                  // 443
};

Database

use opentelemetry_semantic_conventions::attribute::{
    DB_SYSTEM,                    // "postgresql", "mysql", "mongodb"
    DB_NAME,                      // Database name
    DB_OPERATION,                 // "SELECT", "INSERT", "UPDATE"
    DB_STATEMENT,                 // SQL query or command
    DB_USER,                      // Database user
};

Network

use opentelemetry_semantic_conventions::attribute::{
    NETWORK_PROTOCOL_NAME,        // "http", "grpc", "amqp"
    NETWORK_PROTOCOL_VERSION,     // "1.1", "2", "3"
    NETWORK_PEER_ADDRESS,         // Peer IP address
    NETWORK_PEER_PORT,            // Peer port number
};

Error Attributes

use opentelemetry_semantic_conventions::attribute::{
    ERROR_TYPE,                   // Error type/class
    EXCEPTION_MESSAGE,            // Exception message
    EXCEPTION_TYPE,               // Exception class name
    EXCEPTION_STACKTRACE,         // Stack trace string
};

Resource Attribute Names

Service

use opentelemetry_semantic_conventions::resource::{
    SERVICE_NAME,                 // Service name
    SERVICE_VERSION,              // Service version
    SERVICE_NAMESPACE,            // Service namespace
    SERVICE_INSTANCE_ID,          // Unique instance identifier
};

Host

use opentelemetry_semantic_conventions::resource::{
    HOST_NAME,                    // Hostname
    HOST_ID,                      // Unique host ID
    HOST_TYPE,                    // "physical", "virtual"
    HOST_ARCH,                    // "amd64", "arm64"
};

Container

use opentelemetry_semantic_conventions::resource::{
    CONTAINER_NAME,               // Container name
    CONTAINER_ID,                 // Container ID
    CONTAINER_IMAGE_NAME,         // Image name
    CONTAINER_IMAGE_TAG,          // Image tag
};

Kubernetes

use opentelemetry_semantic_conventions::resource::{
    K8S_CLUSTER_NAME,             // Cluster name
    K8S_NAMESPACE_NAME,           // Namespace
    K8S_POD_NAME,                 // Pod name
    K8S_DEPLOYMENT_NAME,          // Deployment name
    K8S_NODE_NAME,                // Node name
};

Cloud

use opentelemetry_semantic_conventions::resource::{
    CLOUD_PROVIDER,               // "aws", "gcp", "azure"
    CLOUD_PLATFORM,               // "aws_ec2", "gcp_compute_engine"
    CLOUD_REGION,                 // "us-east-1"
    CLOUD_AVAILABILITY_ZONE,      // "us-east-1a"
    CLOUD_ACCOUNT_ID,             // Cloud account ID
};

Metric Names

use opentelemetry_semantic_conventions::metric::{
    // HTTP metrics
    HTTP_SERVER_REQUEST_DURATION,      // "http.server.request.duration"
    HTTP_SERVER_REQUEST_BODY_SIZE,     // "http.server.request.body.size"
    HTTP_SERVER_RESPONSE_BODY_SIZE,    // "http.server.response.body.size"
    
    // System metrics
    SYSTEM_CPU_UTILIZATION,            // "system.cpu.utilization"
    SYSTEM_MEMORY_USAGE,               // "system.memory.usage"
    SYSTEM_NETWORK_IO,                 // "system.network.io"
};

Complete Example

use opentelemetry::{global, trace::Tracer, KeyValue};
use opentelemetry_sdk::{trace::SdkTracerProvider, Resource};
use opentelemetry_semantic_conventions::{
    resource::{
        SERVICE_NAME,
        SERVICE_VERSION,
        DEPLOYMENT_ENVIRONMENT,
    },
    attribute::{
        HTTP_REQUEST_METHOD,
        HTTP_RESPONSE_STATUS_CODE,
        URL_FULL,
        SERVER_ADDRESS,
    },
};

// Configure resource with semantic conventions
let resource = Resource::new(vec![
    KeyValue::new(SERVICE_NAME, "payment-api"),
    KeyValue::new(SERVICE_VERSION, "2.1.0"),
    KeyValue::new(DEPLOYMENT_ENVIRONMENT, "production"),
]);

let provider = SdkTracerProvider::builder()
    .with_resource(resource)
    .build();

global::set_tracer_provider(provider);

// Create span with semantic conventions
let tracer = global::tracer("payment-service");
let mut span = tracer.start("process_payment");

span.set_attribute(KeyValue::new(HTTP_REQUEST_METHOD, "POST"));
span.set_attribute(KeyValue::new(URL_FULL, "https://api.example.com/payments"));
span.set_attribute(KeyValue::new(SERVER_ADDRESS, "api.example.com"));
span.set_attribute(KeyValue::new(HTTP_RESPONSE_STATUS_CODE, 201));

span.end();

Experimental Conventions

With the semconv_experimental feature, you can access conventions that are not yet stable:

[dependencies]
opentelemetry-semantic-conventions = { version = "0.31", features = ["semconv_experimental"] }

Experimental conventions may change in future versions. Use with caution in production.

Benefits

Vendor Interoperability

Works across different observability backends

Automated Insights

Backends provide better dashboards and alerts

Consistent Naming

Avoid “method” vs “http.method” vs “httpMethod” confusion

Discovery

Easier to search and correlate across services

Related Crates

• opentelemetry - Core API
• opentelemetry-sdk - SDK with Resource support

Documentation

Full API Documentation

View complete API reference on docs.rs

Semantic Conventions Specification

Official OpenTelemetry semantic conventions

Minimum Rust Version

MSRV: 1.75.0