log Appender

Overview

The opentelemetry-appender-log crate provides a bridge between the log crate and OpenTelemetry. It implements the log::Log trait to capture logs emitted through the log crate’s macros (error!, warn!, info!, debug!, trace!) and forwards them to OpenTelemetry exporters.

Installation

Add the following to your Cargo.toml:

[dependencies]
log = "0.4"
opentelemetry = { version = "0.27", features = ["logs"] }
opentelemetry-appender-log = "0.27"
opentelemetry-sdk = { version = "0.27", features = ["logs"] }
opentelemetry-stdout = { version = "0.27", features = ["logs"] }

Quick Start

Create a LoggerProvider

Set up the OpenTelemetry logger provider with an exporter:

use opentelemetry_sdk::logs::SdkLoggerProvider;
use opentelemetry_stdout::LogExporter;

let exporter = LogExporter::default();
let provider = SdkLoggerProvider::builder()
    .with_simple_exporter(exporter)
    .build();

Install the log appender

Create and register the OpenTelemetry log bridge:

use opentelemetry_appender_log::OpenTelemetryLogBridge;
use log::Level;

let appender = OpenTelemetryLogBridge::new(&provider);
log::set_boxed_logger(Box::new(appender)).unwrap();
log::set_max_level(Level::Info.to_level_filter());

Emit logs

Use standard log macros:

use log::{error, warn, info};

error!("Application error occurred");
warn!("Warning message");
info!("Application started successfully");

Shutdown

Flush remaining logs before exit:

provider.shutdown().unwrap();

Complete Example

use log::{error, info, warn, Level};
use opentelemetry_appender_log::OpenTelemetryLogBridge;
use opentelemetry_sdk::{logs::SdkLoggerProvider, Resource};
use opentelemetry_stdout::LogExporter;

#[tokio::main]
async fn main() {
    // Create an exporter that writes to stdout
    let exporter = LogExporter::default();

    // Create a LoggerProvider with resource attributes
    let provider = SdkLoggerProvider::builder()
        .with_resource(
            Resource::builder()
                .with_service_name("my-service")
                .build(),
        )
        .with_simple_exporter(exporter)
        .build();

    // Set up the log appender
    let appender = OpenTelemetryLogBridge::new(&provider);
    log::set_boxed_logger(Box::new(appender)).unwrap();
    log::set_max_level(Level::Info.to_level_filter());

    // Emit logs with structured key-values
    let fruit = "apple";
    let price = 2.99;

    error!(fruit, price; "hello from {fruit}. My price is {price}");
    warn!("Warning message");
    info!("Application started");

    // Shutdown to ensure all logs are flushed
    provider.shutdown().unwrap();
}

Field Mapping

The appender maps log::Record fields to OpenTelemetry LogRecord fields:

Basic Fields

log Field	OpenTelemetry Field	Notes
`args()`	`body`	The formatted log message
`level()`	`severity_number`	Mapped using severity table below
`level()`	`severity_text`	String representation (“ERROR”, “INFO”)
`target()`	`target`	Module/component identifier
`key_values()`	`attributes`	Structured key-value pairs

Severity Mapping

log::Level	Severity Text	Severity Number
`Error`	ERROR	17
`Warn`	WARN	13
`Info`	INFO	9
`Debug`	DEBUG	5
`Trace`	TRACE	1

Metadata Attributes (Experimental)

With the experimental_metadata_attributes feature, source code metadata is captured:

[dependencies]
opentelemetry-appender-log = { version = "0.27", features = ["experimental_metadata_attributes"] }

This adds attributes:

log Field	Attribute Key	Example Value
`file()`	`code.filepath`	`src/main.rs`
`line()`	`code.lineno`	`42`
`module_path()`	`code.namespace`	`my_app::module`

Key-Value Attributes

The log crate supports structured logging with key-value pairs:

use log::info;

info!(
    user_id = 12345,
    action = "login",
    duration_ms = 150;
    "User logged in successfully"
);

These are converted to OpenTelemetry attributes based on their type:

Type Mapping

Rust Type	AnyValue Type	Notes
`i8`-`i64`	`Int`
`u8`-`u64`	`Int`	Converted to `i64` if possible, else `String`
`i128`, `u128`	`Int` or `String`	Uses `Int` if fits in `i64`, else stringified
`f32`, `f64`	`Double`
`bool`	`Boolean`
`&str`, `String`	`String`
Other types	`String`	Formatted using `Debug`

With Serde Support

Enable the with-serde feature for complex types:

[dependencies]
opentelemetry-appender-log = { version = "0.27", features = ["with-serde"] }

With this feature enabled: | Type | Result | Notes | |-------------------|---------------|------------------------------------|| | Sequences | ListAny | Vectors, arrays, etc. | | Maps | Map | HashMaps, BTreeMaps, etc. | | Structs | Map | Serialized as key-value maps | | Enums | Various | Depends on variant type | | Bytes | Bytes | Raw byte arrays | | Option::None | — | Discarded | | Option::Some(T) | T | Uses inner value | | () | — | Discarded | Example:

use log::info;
use serde::Serialize;

#[derive(Serialize)]
struct UserInfo {
    id: u64,
    name: String,
    roles: Vec<String>,
}

let user = UserInfo {
    id: 12345,
    name: "alice".to_string(),
    roles: vec!["admin".to_string(), "user".to_string()],
};

info!(user = log::kv::Value::from_serde(&user); "User loaded");

Without with-serde, complex types are formatted using Debug:

// Without with-serde feature
info!(data = vec![1, 2, 3]; "Processing data");
// Attribute value: "[1, 2, 3]" (string)

Usage with Batch Processor

For production use, configure a batch processor:

use opentelemetry_sdk::logs::BatchLogProcessor;
use std::time::Duration;

let exporter = opentelemetry_stdout::LogExporter::default();

let processor = BatchLogProcessor::builder(exporter)
    .with_batch_config(
        opentelemetry_sdk::logs::BatchConfigBuilder::default()
            .with_max_queue_size(2048)
            .with_max_export_batch_size(512)
            .with_scheduled_delay(Duration::from_secs(5))
            .build(),
    )
    .build();

let provider = SdkLoggerProvider::builder()
    .with_log_processor(processor)
    .build();

Integration with Traces

When logs are emitted within an active OpenTelemetry span context, the trace context is automatically attached:

use opentelemetry::trace::{Tracer, TracerProvider};
use opentelemetry_sdk::trace::SdkTracerProvider;
use log::error;

let tracer_provider = SdkTracerProvider::builder().build();
let tracer = tracer_provider.tracer("my-app");

tracer.in_span("process-request", |_cx| {
    // This log will have trace_id and span_id from the active span
    error!("Request processing failed");
});

The emitted log will include:

trace_id: The ID of the distributed trace
span_id: The ID of the current span
trace_flags: Sampling flags

Performance Considerations

Filtering

Set appropriate log levels to avoid overhead:

// Only process Info and above
log::set_max_level(log::Level::Info.to_level_filter());

event_enabled

The appender implements enabled() to check if a log should be processed:

// This check happens before expensive formatting
if log::log_enabled!(log::Level::Debug) {
    let expensive_data = compute_expensive_data();
    log::debug!(data = expensive_data; "Debug information");
}

Batching

Use BatchLogProcessor in production to amortize export costs:

Reduces network overhead
Improves throughput
Adds minimal latency (configurable)

See Log Processors for configuration details.

Comparison with tracing Appender

Feature	log Appender	tracing Appender
Target Crate	`log`	`tracing`
Structured Logging	Key-values	Fields + spans
Span Context	Manual	Automatic
Async-aware	No	Yes
Filtering	Level-based	Target + level-based
Event Names	Not supported	Supported
Best For	Simple applications	Async applications

Choose the log appender if:

You have existing code using the log crate
You need simple, synchronous logging
You don’t need advanced filtering or span correlation

Choose the tracing appender if:

You’re building async applications
You want hierarchical span context
You need advanced filtering capabilities
You want automatic trace correlation

Feature Flags

Feature	Description
`with-serde`	Support complex types via serde serialization
`experimental_metadata_attributes`	Capture source code location as attributes

Troubleshooting

Logs not appearing

Check log level: Ensure set_max_level() is set appropriately
```
log::set_max_level(log::LevelFilter::Debug);
```
Flush on shutdown: Always call provider.shutdown()
```
provider.shutdown().unwrap();
```
Check processor configuration: Verify the exporter is configured correctly

Complex types not serialized

Enable the with-serde feature:

opentelemetry-appender-log = { version = "0.27", features = ["with-serde"] }

Trace context not attached

Ensure logs are emitted within an active span context:

tracer.in_span("my-operation", |_cx| {
    log::info!("This log will have trace context");
});

tracing Appender

Alternative appender for the tracing crate

Log Processors

Configure batch and simple processors

Bridge API

Understanding the underlying API

Overview

Return to logs overview

Get Started

Core Concepts

Traces

Metrics

Logs

Exporters

Advanced

Examples

Overview

Installation

Quick Start

Complete Example

Field Mapping

Basic Fields

Severity Mapping

Metadata Attributes (Experimental)

Key-Value Attributes

Type Mapping

With Serde Support

Usage with Batch Processor

Integration with Traces

Performance Considerations

Filtering

event_enabled

Batching

Comparison with tracing Appender

Feature Flags

Troubleshooting

Logs not appearing

Complex types not serialized

Trace context not attached

See Also

tracing Appender

Log Processors

Bridge API

Overview

Build docs developers (and LLMs) love

Get Started

Core Concepts

Traces

Metrics

Logs

Exporters

Advanced

Examples

​Overview

​Installation

​Quick Start

​Complete Example

​Field Mapping

​Basic Fields

​Severity Mapping

​Metadata Attributes (Experimental)

​Key-Value Attributes

​Type Mapping

​With Serde Support

​Usage with Batch Processor

​Integration with Traces

​Performance Considerations

​Filtering

​event_enabled

​Batching

​Comparison with tracing Appender

​Feature Flags

​Troubleshooting

​Logs not appearing

​Complex types not serialized

​Trace context not attached

​See Also

tracing Appender

Log Processors

Bridge API

Overview

Build docs developers (and LLMs) love

Overview

Installation

Quick Start

Complete Example

Field Mapping

Basic Fields

Severity Mapping

Metadata Attributes (Experimental)

Key-Value Attributes

Type Mapping

With Serde Support

Usage with Batch Processor

Integration with Traces

Performance Considerations

Filtering

event_enabled

Batching

Comparison with tracing Appender

Feature Flags

Troubleshooting

Logs not appearing

Complex types not serialized

Trace context not attached

See Also