diff --git a/examples/README.md b/examples/README.md index eac8a3a779..099b9db6fb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,7 +2,7 @@ This directory contains some examples that should help you get start crates from `opentelemetry-rust`. -## log-basic +## logs-basic This example uses following crates from this repo: @@ -12,6 +12,17 @@ This example uses following crates from this repo: Check this example if you want to understand *how to instrument logs using opentelemetry*. +## logs-advanced + +This example uses following crates from this repo: + +- opentelemetry(log) +- opentelemetry-appender-tracing +- opentelemetry-stdout + +This builds on top of the logs-basic, +and shows how to implement and compose `LogProcessor`s.. + ## metrics-basic This example uses following crates from this repo: diff --git a/examples/logs-advanced/Cargo.toml b/examples/logs-advanced/Cargo.toml new file mode 100644 index 0000000000..335008ce4d --- /dev/null +++ b/examples/logs-advanced/Cargo.toml @@ -0,0 +1,21 @@ +[package] +name = "logs-advanced" +version = "0.1.0" +edition = "2021" +license = "Apache-2.0" +rust-version = "1.75.0" +publish = false +autobenches = false + +[[bin]] +name = "logs-advanced" +path = "src/main.rs" +bench = false + +[dependencies] +opentelemetry_sdk = { workspace = true } +opentelemetry-stdout = { workspace = true, features = ["logs"] } +opentelemetry-appender-tracing = { workspace = true } +tracing = { workspace = true, features = ["std"]} +tracing-subscriber = { workspace = true, features = ["env-filter","registry", "std", "fmt"] } +opentelemetry = { workspace = true } diff --git a/examples/logs-advanced/README.md b/examples/logs-advanced/README.md new file mode 100644 index 0000000000..a0345670be --- /dev/null +++ b/examples/logs-advanced/README.md @@ -0,0 +1,13 @@ +# OpenTelemetry Log Processor Implementation and Composition - Example + +This example builds on top of the `logs-basic`, showing how to implement `LogProcessor`s correctly. + +The `EnrichmentProcessor` simulates a processor adding information +to the log captured by the OpenTelemetry SDK, which correctly ensures that the +downstream processor's filtering is captured, avoiding unnecessary work. + +## Usage + +```shell +cargo run +``` diff --git a/examples/logs-advanced/src/main.rs b/examples/logs-advanced/src/main.rs new file mode 100644 index 0000000000..b51e324fa9 --- /dev/null +++ b/examples/logs-advanced/src/main.rs @@ -0,0 +1,114 @@ +use opentelemetry::logs::{LogRecord, Severity}; +use opentelemetry::InstrumentationScope; +use opentelemetry_appender_tracing::layer; +use opentelemetry_sdk::error::OTelSdkResult; +use opentelemetry_sdk::logs::{LogProcessor, SdkLogRecord, SdkLoggerProvider, SimpleLogProcessor}; +use opentelemetry_sdk::Resource; +use tracing::{error, info}; +use tracing_subscriber::{prelude::*, EnvFilter}; + +fn main() { + let exporter = opentelemetry_stdout::LogExporter::default(); + let enriching_processor = EnrichmentLogProcessor::new(SimpleLogProcessor::new(exporter)); + let provider: SdkLoggerProvider = SdkLoggerProvider::builder() + .with_resource( + Resource::builder() + .with_service_name("log-appender-tracing-example") + .build(), + ) + .with_log_processor(enriching_processor) + .build(); + + // To prevent a telemetry-induced-telemetry loop, OpenTelemetry's own internal + // logging is properly suppressed. However, logs emitted by external components + // (such as reqwest, tonic, etc.) are not suppressed as they do not propagate + // OpenTelemetry context. Until this issue is addressed + // (https://github.com/open-telemetry/opentelemetry-rust/issues/2877), + // filtering like this is the best way to suppress such logs. + // + // The filter levels are set as follows: + // - Allow `info` level and above by default. + // - Completely restrict logs from `hyper`, `tonic`, `h2`, and `reqwest`. + // + // Note: This filtering will also drop logs from these components even when + // they are used outside of the OTLP Exporter. + let filter_otel = EnvFilter::new("info") + .add_directive("hyper=off".parse().unwrap()) + .add_directive("tonic=off".parse().unwrap()) + .add_directive("h2=off".parse().unwrap()) + .add_directive("reqwest=off".parse().unwrap()); + let otel_layer = layer::OpenTelemetryTracingBridge::new(&provider).with_filter(filter_otel); + + // Create a new tracing::Fmt layer to print the logs to stdout. It has a + // default filter of `info` level and above, and `debug` and above for logs + // from OpenTelemetry crates. The filter levels can be customized as needed. + let filter_fmt = EnvFilter::new("error").add_directive("opentelemetry=debug".parse().unwrap()); + let fmt_layer = tracing_subscriber::fmt::layer() + .with_thread_names(true) + .with_filter(filter_fmt); + + tracing_subscriber::registry() + .with(otel_layer) + .with(fmt_layer) + .init(); + + info!(name: "my-event-name", target: "my-system", event_id = 20, user_name = "otel", user_email = "otel@opentelemetry.io", message = "This is an example message"); + error!(name: "my-event-name", target: "my-system", event_id = 50, user_name = "otel", user_email = "otel@opentelemetry.io", message = "This is an example message"); + let _ = provider.shutdown(); +} + +/// A log processor that enriches log records with additional attributes before +/// delegating to an underlying processor. +/// +/// If this were implemented as a standalone processor in a chain (e.g., +/// EnrichmentProcessor -> SimpleLogProcessor), the performance benefits of the +/// `event_enabled` check would be nullified. Here's why: +/// +/// - The `event_enabled` method is crucial for performance - it allows processors +/// to skip expensive operations for logs that will ultimately be filtered out +/// - A standalone EnrichmentProcessor would need to implement `event_enabled`, +/// but it has no knowledge of downstream filtering logic +/// - It would have to return `true` by default, causing unnecessary enrichment +/// work even for logs that the downstream processor will discard +/// +/// Because this processor wraps another, it must delegate all trait methods +/// to the underlying processor. This ensures the underlying processor receives +/// all necessary lifecycle events. +#[derive(Debug)] +pub struct EnrichmentLogProcessor { + /// The wrapped processor that will receive enriched log records + delegate: P, +} + +impl EnrichmentLogProcessor

{ + pub fn new(delegate: P) -> EnrichmentLogProcessor

{ + EnrichmentLogProcessor { delegate } + } +} + +impl LogProcessor for EnrichmentLogProcessor

{ + fn emit(&self, data: &mut SdkLogRecord, instrumentation: &InstrumentationScope) { + data.add_attribute("enriched", true); + self.delegate.emit(data, instrumentation); + } + + fn force_flush(&self) -> OTelSdkResult { + self.delegate.force_flush() + } + + fn shutdown_with_timeout(&self, timeout: std::time::Duration) -> OTelSdkResult { + self.delegate.shutdown_with_timeout(timeout) + } + + fn shutdown(&self) -> OTelSdkResult { + self.delegate.shutdown() + } + + fn set_resource(&mut self, resource: &Resource) { + self.delegate.set_resource(resource); + } + + fn event_enabled(&self, level: Severity, target: &str, name: Option<&str>) -> bool { + self.delegate.event_enabled(level, target, name) + } +}