feat: stabilization of opentelemetry-etw-logs

Cargo.toml

@@ -29,6 +29,7 @@ debug = 1
 
 [workspace.dependencies]
 opentelemetry = "0.29"
+opentelemetry-appender-log = "0.29"
 opentelemetry-appender-tracing = "0.29"
 opentelemetry-http = "0.29"
 opentelemetry-proto = { version = "0.29", default-features = false }

opentelemetry-etw-logs/CHANGELOG.md

@@ -2,8 +2,18 @@
 
 ## vNext
 
-- Added validation to provider name
+- Added validation to provider name.
 - Added optional feature `serde_json` to serialize List and Maps.
+- Added `etw_log_processor()` method that returns an `impl LogProcessor`.
+- Added `ExporterOptions` which uses a builder pattern to configure the exporter.
+- The `with_etw_exporter` trait method now accepts an `ExporterOptions` instance:
+
+  ```rust
+  let options = ExporterOptions::builder("provider-name").build().unwrap();
+  let logger_provider = SdkLoggerProvider::builder()
+    .with_etw_exporter(options)
+    .build();
+  ```
 
 ## v0.8.0
 

opentelemetry-etw-logs/Cargo.toml

@@ -11,15 +11,21 @@ keywords = ["opentelemetry", "log", "trace", "etw"]
 license = "Apache-2.0"
 
 [dependencies]
-tracelogging_dynamic = "1.2.1"
+chrono = { version = "0.4.40", default-features = false, features = [
+    "alloc",
+    "std",
+] }
+futures-executor = "0.3.31"
 opentelemetry = { workspace = true, features = ["logs"] }
 opentelemetry_sdk = { workspace = true, features = ["logs"] }
-tracing = { version = "0.1", optional = true }
 serde_json = { version = "1.0.113", optional = true }
-futures-executor = "0.3.31"
-chrono = { version = "0.4.40", default-features = false, features = ["alloc", "std"] }
+thiserror = { version = "2", default-features = false }
+tracelogging_dynamic = "1.2.1"
+tracing = { version = "0.1", optional = true }
 
 [dev-dependencies]
+log = { version = "0.4.21", features = ["kv_serde"] }
+opentelemetry-appender-log = { workspace = true }
 opentelemetry-appender-tracing = { workspace = true }
 opentelemetry_sdk = { workspace = true, features = ["logs", "trace"] }
 tokio = { version = "1.0", features = ["full"] }

opentelemetry-etw-logs/README.md

@@ -16,7 +16,7 @@ ETW events can be consumed in real-time or from a log file.
 
 ETW events created with this crate can be generated and collected on Windows Vista or later.
 
-This ETW exporter enables applications to use OpenTelemetry APIs to capture telemetry events and write to the ETW subsystem. From ETWs, the events can be
+This ETW exporter enables applications to use OpenTelemetry APIs to capture telemetry events and write to the ETW subsystem. From ETW, the events can be
 captured by agents running locally and listening for specific ETW events.
 
 [![Crates.io: opentelemetry-etw-logs](https://img.shields.io/crates/v/opentelemetry-etw-logs.svg)](https://crates.io/crates/opentelemetry-etw-logs)
@@ -28,7 +28,51 @@ captured by agents running locally and listening for specific ETW events.
 ## Viewing ETW Logs
 
 Logs exported to ETW can be viewed using tools like `logman`, `perfview` etc.
-// TODO - add instructions.
+
+### Using `logman`
+
+To view the telemetry emitted to ETW you can use [`logman`](https://learn.microsoft.com/windows-server/administration/windows-commands/logman) along with `perfview`.
+`logman` will listen to ETW events from the given provider (on this example, `provider-name`) and store them in a `.etl` file.
+
+[`perfview`](https://github.com/microsoft/perfview) will allow you to visualize the events.
+
+Instructions using Powershell:
+
+1. Get the ETW Session Guid for the given provider (on this example `provider-name`):
+
+    ```ps
+    $EtwSessionGuid = (new-object System.Diagnostics.Tracing.EventSource("provider-name")).Guid.ToString()`
+    ```
+
+1. Start Logman session:
+
+    ```ps
+    logman create trace OtelETWExampleBasic -o OtelETWExampleBasic.log -p "{$EtwSessionGuid}" -f bincirc -max 1000
+    logman start OtelETWExampleBasic
+    ```
+
+1. Execute this example:
+
+    ```ps
+    cd opentelemetry-etw-logs
+    cargo run --example basic
+    ```
+
+1. Stop and Remove `logman` session:
+
+    ```ps
+    logman stop OtelETWExampleBasic
+    logman delete OtelETWExampleBasic
+    ```
+
+1. View the events with `perfview`:
+
+    - Download PerfView: [Instructions](https://github.com/microsoft/perfview/blob/main/documentation/Downloading.md), [Releases](https://github.com/Microsoft/perfview/releases).
+    - Open PerfView.
+    - Go the location of the `.etl` file: `OtelETWExampleBasic.log_000001.etl` and open it.
+    - Double-click `Events` in the left-panel.
+    - Double-click the `provider-name/event-name` in the left-panel.
+    - You should see the events in the right-panel.
 
 ## OpenTelemetry Overview
 
@@ -47,4 +91,3 @@ of telemetry is intentionally left to other tools.
 
 [Prometheus]: https://prometheus.io
 [Jaeger]: https://www.jaegertracing.io
-

opentelemetry-etw-logs/examples/basic.rs

@@ -39,14 +39,20 @@
 //!
 
 use opentelemetry_appender_tracing::layer;
-use opentelemetry_etw_logs::ETWLoggerProviderBuilderExt;
+use opentelemetry_etw_logs::Processor;
 use opentelemetry_sdk::logs::SdkLoggerProvider;
 use tracing::error;
 use tracing_subscriber::prelude::*;
 
 fn init_logger() -> SdkLoggerProvider {
+    let processor = Processor::builder("provider-name")
+        // Use a constant custom name for all events instead of "Log"
+        .etw_event_name_from_callback(|_| "CustomEvent")
+        .build()
+        .unwrap();
+
     SdkLoggerProvider::builder()
-        .with_etw_exporter("provider-name")
+        .with_log_processor(processor)
         .build()
 }
 

opentelemetry-etw-logs/src/lib.rs

@@ -1,5 +1,5 @@
 //! The ETW exporter will enable applications to use OpenTelemetry API
-//! to capture the telemetry events, and write to ETW subsystem.
+//! to capture the telemetry events, and write them to the ETW subsystem.
 
 #![warn(missing_debug_implementations, missing_docs)]
 

opentelemetry-etw-logs/src/logs/exporter/common.rs

@@ -6,7 +6,7 @@ use opentelemetry::{
 };
 use tracelogging_dynamic as tld;
 
-pub fn add_attribute_to_event(event: &mut tld::EventBuilder, key: &Key, value: &AnyValue) {
+pub(crate) fn add_attribute_to_event(event: &mut tld::EventBuilder, key: &Key, value: &AnyValue) {
     match value {
         AnyValue::Boolean(b) => {
             event.add_bool32(key.as_str(), *b as i32, tld::OutType::Default, 0);
@@ -48,7 +48,7 @@ pub fn add_attribute_to_event(event: &mut tld::EventBuilder, key: &Key, value: &
     }
 }
 
-pub const fn convert_severity_to_level(severity: Severity) -> tld::Level {
+pub(crate) const fn convert_severity_to_level(severity: Severity) -> tld::Level {
     match severity {
         Severity::Debug
         | Severity::Debug2
@@ -75,32 +75,33 @@ pub const fn convert_severity_to_level(severity: Severity) -> tld::Level {
     }
 }
 
-pub fn get_event_name(log_record: &opentelemetry_sdk::logs::SdkLogRecord) -> &str {
-    log_record.event_name().unwrap_or("Log")
-}
-
 #[cfg(test)]
-pub mod test_utils {
+pub(crate) mod test_utils {
     use opentelemetry::logs::Logger;
     use opentelemetry::logs::LoggerProvider;
     use opentelemetry_sdk::logs::SdkLoggerProvider;
 
-    use super::super::ETWExporter;
+    use crate::logs::exporter::options::Options;
+    use crate::logs::exporter::ETWExporter;
 
-    pub fn new_etw_exporter() -> ETWExporter {
-        ETWExporter::new("test-provider-name")
+    pub(crate) fn new_etw_exporter() -> ETWExporter {
+        ETWExporter::new(test_options())
     }
 
-    pub fn new_instrumentation_scope() -> opentelemetry::InstrumentationScope {
+    pub(crate) fn new_instrumentation_scope() -> opentelemetry::InstrumentationScope {
         opentelemetry::InstrumentationScope::default()
     }
 
-    pub fn new_sdk_log_record() -> opentelemetry_sdk::logs::SdkLogRecord {
+    pub(crate) fn new_sdk_log_record() -> opentelemetry_sdk::logs::SdkLogRecord {
         SdkLoggerProvider::builder()
             .build()
             .logger("test")
             .create_log_record()
     }
+
+    pub(crate) fn test_options() -> Options {
+        Options::builder("ContosoProvider").build().unwrap()
+    }
 }
 
 #[test]
@@ -120,17 +121,3 @@ fn test_get_severity_level() {
     let result = convert_severity_to_level(Severity::Warn);
     assert_eq!(result, tld::Level::Warning);
 }
-
-#[test]
-fn test_get_event_name() {
-    use opentelemetry::logs::LogRecord;
-
-    let mut log_record = test_utils::new_sdk_log_record();
-
-    let result = get_event_name(&log_record);
-    assert_eq!(result, "Log");
-
-    log_record.set_event_name("event-name");
-    let result = get_event_name(&log_record);
-    assert_eq!(result, "event-name");
-}

opentelemetry-etw-logs/src/logs/exporter/mod.rs

@@ -7,13 +7,15 @@ use tracelogging_dynamic as tld;
 use opentelemetry::logs::Severity;
 use opentelemetry::Key;
 use opentelemetry_sdk::error::{OTelSdkError, OTelSdkResult};
-use std::str;
 
-mod common;
+pub(crate) mod common;
+pub(crate) mod options;
 mod part_a;
 mod part_b;
 mod part_c;
 
+pub(crate) use options::{Options, OptionsBuilder};
+
 #[derive(Default)]
 struct Resource {
     pub cloud_role: Option<String>,
@@ -23,6 +25,7 @@ struct Resource {
 pub(crate) struct ETWExporter {
     provider: Pin<Arc<tld::Provider>>,
     resource: Resource,
+    options: Options,
 }
 
 fn enabled_callback_noop(
@@ -40,11 +43,14 @@ fn enabled_callback_noop(
 impl ETWExporter {
     const KEYWORD: u64 = 1;
 
-    pub(crate) fn new(provider_name: &str) -> Self {
-        let mut options = tld::Provider::options();
+    pub(crate) fn new(options: Options) -> Self {
+        let mut provider_options = tld::Provider::options();
 
-        options.callback(enabled_callback_noop, 0x0);
-        let provider = Arc::pin(tld::Provider::new(provider_name, &options));
+        provider_options.callback(enabled_callback_noop, 0x0);
+        let provider = Arc::pin(tld::Provider::new(
+            options.provider_name(),
+            &provider_options,
+        ));
         // SAFETY: tracelogging (ETW) enables an ETW callback into the provider when `register()` is called.
         // This might crash if the provider is dropped without calling unregister before.
         // This only affects static providers.
@@ -56,6 +62,7 @@ impl ETWExporter {
         ETWExporter {
             provider,
             resource: Default::default(),
+            options,
         }
     }
 
@@ -86,7 +93,7 @@ impl ETWExporter {
 
         // reset
         event.reset(
-            common::get_event_name(log_record),
+            self.options.get_etw_event_name(log_record),
             level,
             Self::KEYWORD,
             event_tags,
@@ -233,6 +240,21 @@ mod tests {
         assert!(result.await.is_ok());
     }
 
+    #[tokio::test]
+    #[should_panic]
+    async fn test_export_empty_batch_produces_failure() {
+        use opentelemetry_sdk::logs::LogBatch;
+        use opentelemetry_sdk::logs::LogExporter;
+
+        let records = [];
+        let batch = LogBatch::new(&records);
+
+        let exporter = common::test_utils::new_etw_exporter();
+        let result = exporter.export(batch);
+
+        assert!(result.await.is_ok());
+    }
+
     #[test]
     fn test_callback_noop() {
         enabled_callback_noop(