> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-telemetry/opentelemetry-rust/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```toml theme={null}
[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**.

```rust theme={null}
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:

<ParamField path="attribute" type="module">
  Common attribute names for spans, logs, and metrics
</ParamField>

<ParamField path="resource" type="module">
  Resource attribute names (service, host, container, etc.)
</ParamField>

<ParamField path="metric" type="module">
  Standard metric names and units
</ParamField>

<ParamField path="trace" type="module">
  Trace-specific semantic conventions
</ParamField>

## Common Usage

### Resource Attributes

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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

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

### Host

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

### Container

```rust theme={null}
use opentelemetry_semantic_conventions::resource::{
    CONTAINER_NAME,               // Container name
    CONTAINER_ID,                 // Container ID
    CONTAINER_IMAGE_NAME,         // Image name
    CONTAINER_IMAGE_TAG,          // Image tag
};
```

### Kubernetes

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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

```rust theme={null}
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:

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

<Warning>
  Experimental conventions may change in future versions. Use with caution in production.
</Warning>

## Benefits

<CardGroup cols={2}>
  <Card title="Vendor Interoperability" icon="handshake">
    Works across different observability backends
  </Card>

  <Card title="Automated Insights" icon="lightbulb">
    Backends provide better dashboards and alerts
  </Card>

  <Card title="Consistent Naming" icon="spell-check">
    Avoid "method" vs "http.method" vs "httpMethod" confusion
  </Card>

  <Card title="Discovery" icon="magnifying-glass">
    Easier to search and correlate across services
  </Card>
</CardGroup>

## Related Crates

* **[opentelemetry](/api/opentelemetry)** - Core API
* **[opentelemetry-sdk](/api/opentelemetry-sdk)** - SDK with Resource support

## Documentation

<Card title="Full API Documentation" icon="book" href="https://docs.rs/opentelemetry-semantic-conventions/0.31.0">
  View complete API reference on docs.rs
</Card>

<Card title="Semantic Conventions Specification" icon="arrow-up-right-from-square" href="https://opentelemetry.io/docs/specs/semconv/">
  Official OpenTelemetry semantic conventions
</Card>

## Minimum Rust Version

**MSRV:** 1.75.0