feat: Add OpenTelemetrySpanExt methods for direct span event creation

Adds `add_otel_span_event` and `add_otel_span_event_with_timestamp`
methods to the `OpenTelemetrySpanExt` trait.

These methods allow users to add OpenTelemetry span events directly
to a `tracing::Span`, including events with dynamic attribute keys,
bypassing the limitations of the `tracing::event!` macro for such
use cases.

The signatures align with the upstream OpenTelemetry Span trait,
using `T: Into<Cow<'static, str>>` for the event name.

Includes:
- Trait method definitions and implementations.
- Corresponding test cases.
- Updates to README.md.
- New example `examples/opentelemetry-span-event.rs`.
- Changelog entries.

Author: alessandrobologna

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Unreleased
 
+### Added
+
+- Add `OpenTelemetrySpanExt::add_otel_span_event` function to allow adding OpenTelemetry
+  events directly to a `tracing::Span`, enabling the use of dynamic attribute keys.
+- Add `OpenTelemetrySpanExt::add_otel_span_event_with_timestamp` function, similar to
+  `add_otel_span_event`, but allowing a specific `SystemTime` to be provided for the event.
+- Add `examples/opentelemetry-span-event.rs` demonstrating the usage of the new span event methods.
+
 # 0.30.0 (March 23, 2025)
 
 ### Breaking Changes

README.md

@@ -42,7 +42,10 @@ The crate provides the following types:
 
 * [`OpenTelemetryLayer`] adds OpenTelemetry context to all `tracing` [span]s.
 * [`OpenTelemetrySpanExt`] allows OpenTelemetry parent trace information to be
-  injected and extracted from a `tracing` [span].
+  injected and extracted from a `tracing` [span]. It also provides methods
+  to directly set span attributes (`set_attribute`), span status (`set_status`),
+  and add OpenTelemetry events with dynamic attributes using the current time
+  (`add_otel_span_event`) or a specific timestamp (`add_otel_span_event_with_timestamp`).
 
 [`OpenTelemetryLayer`]: https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/struct.OpenTelemetryLayer.html
 [`OpenTelemetrySpanExt`]: https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/trait.OpenTelemetrySpanExt.html

examples/opentelemetry-span-event.rs

@@ -0,0 +1,65 @@
+use opentelemetry::trace::TracerProvider as _;
+use opentelemetry::KeyValue;
+use opentelemetry_sdk::trace::SdkTracerProvider;
+use opentelemetry_stdout as stdout;
+use std::time::SystemTime;
+use tracing::{error, span};
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+use tracing_subscriber::layer::SubscriberExt;
+use tracing_subscriber::Registry;
+
+fn main() {
+    // Create a new OpenTelemetry trace pipeline that prints to stdout
+    let provider = SdkTracerProvider::builder()
+        .with_simple_exporter(stdout::SpanExporter::default())
+        .build();
+    let tracer = provider.tracer("otel_span_event_example");
+
+    // Create a tracing layer with the configured tracer
+    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);
+
+    // Use the tracing subscriber `Registry`, or any other subscriber
+    // that impls `LookupSpan`
+    let subscriber = Registry::default().with(telemetry);
+
+    // Trace executed code
+    tracing::subscriber::with_default(subscriber, || {
+        // Spans will be sent to the configured OpenTelemetry exporter
+        let root = span!(tracing::Level::INFO, "app_start", work_units = 2);
+        let _enter = root.enter();
+
+        error!("This event will be logged in the root span via tracing::event!");
+
+        // --- Add custom OpenTelemetry Span Events ---
+        let current_span = tracing::Span::current();
+
+        // Generate a dynamic request ID using the current time
+        let request_id_from_time = SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0)
+            .to_string();
+
+        // Let's assume that this is coming from a request from a user
+        let dynamic_attributes = vec![
+            KeyValue::new("user.id", "example-user-456"),
+            KeyValue::new("request.id", request_id_from_time), // Use timestamp-based ID
+        ];
+
+        // Add event with current timestamp using the extension trait
+        current_span.add_otel_span_event(
+            "Processing dynamic request data",
+            dynamic_attributes.clone(),
+        );
+        println!("Added span event: 'Processing dynamic request data'");
+
+        // Add event with a specific, past timestamp
+        let past_timestamp = SystemTime::now() - std::time::Duration::from_secs(1);
+        current_span.add_otel_span_event_with_timestamp(
+            "Historical data point processed",
+            past_timestamp,
+            vec![KeyValue::new("historical.record.id", 99)],
+        );
+        println!("Added span event: 'Historical data point processed' with past timestamp");
+    });
+}

src/span_ext.rs

@@ -1,5 +1,10 @@
 use crate::layer::WithContext;
-use opentelemetry::{trace::SpanContext, trace::Status, Context, Key, KeyValue, Value};
+use opentelemetry::{
+    time,
+    trace::{SpanContext, Status},
+    Context, Key, KeyValue, Value,
+};
+use std::{borrow::Cow, time::SystemTime};
 
 /// Utility functions to allow tracing [`Span`]s to accept and return
 /// [OpenTelemetry] [`Context`]s.
@@ -152,6 +157,63 @@ pub trait OpenTelemetrySpanExt {
     /// app_root.set_status(Status::Ok);
     /// ```            
     fn set_status(&self, status: Status);
+
+    /// Adds an OpenTelemetry event directly to this span, bypassing `tracing::event!`.
+    /// This allows for adding events with dynamic attribute keys, similar to `set_attribute` for span attributes.
+    /// Events are added with the current timestamp.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use opentelemetry::{KeyValue};
+    /// use tracing_opentelemetry::OpenTelemetrySpanExt;
+    /// use tracing::Span;
+    ///
+    /// let app_root = tracing::span!(tracing::Level::INFO, "processing_request");
+    ///
+    /// let dynamic_attrs = vec![
+    ///     KeyValue::new("job_id", "job-123"),
+    ///     KeyValue::new("user.id", "user-xyz"),
+    /// ];
+    ///
+    /// // Add event using the extension method
+    /// app_root.add_otel_span_event("job_started".to_string(), dynamic_attrs);
+    ///
+    /// // ... perform work ...
+    ///
+    /// app_root.add_otel_span_event("job_completed", vec![KeyValue::new("status", "success")]);
+    /// ```
+    fn add_otel_span_event<T>(&self, name: T, attributes: Vec<KeyValue>)
+    where
+        T: Into<Cow<'static, str>>;
+
+    /// Adds an OpenTelemetry event with a specific timestamp directly to this span.
+    /// Similar to `add_otel_span_event`, but allows overriding the event timestamp.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use opentelemetry::{KeyValue};
+    /// use tracing_opentelemetry::OpenTelemetrySpanExt;
+    /// use tracing::Span;
+    /// use std::time::{Duration, SystemTime};
+    /// use std::borrow::Cow;
+    ///
+    /// let app_root = tracing::span!(tracing::Level::INFO, "historical_event_processing");
+    ///
+    /// let event_time = SystemTime::now() - Duration::from_secs(60);
+    /// let event_attrs = vec![KeyValue::new("record_id", "rec-456")];
+    /// let event_name: Cow<'static, str> = "event_from_past".into();
+    ///
+    /// app_root.add_otel_span_event_with_timestamp(event_name, event_time, event_attrs);
+    /// ```
+    fn add_otel_span_event_with_timestamp<T>(
+        &self,
+        name: T,
+        timestamp: SystemTime,
+        attributes: Vec<KeyValue>,
+    ) where
+        T: Into<Cow<'static, str>>;
 }
 
 impl OpenTelemetrySpanExt for tracing::Span {
@@ -237,4 +299,33 @@ impl OpenTelemetrySpanExt for tracing::Span {
             }
         });
     }
+
+    fn add_otel_span_event<T>(&self, name: T, attributes: Vec<KeyValue>)
+    where
+        T: Into<Cow<'static, str>>,
+    {
+        self.add_otel_span_event_with_timestamp(name, time::now(), attributes);
+    }
+
+    fn add_otel_span_event_with_timestamp<T>(
+        &self,
+        name: T,
+        timestamp: SystemTime,
+        attributes: Vec<KeyValue>,
+    ) where
+        T: Into<Cow<'static, str>>,
+    {
+        self.with_subscriber(move |(id, subscriber)| {
+            let mut event = Some(opentelemetry::trace::Event::new(
+                name, timestamp, attributes, 0,
+            ));
+            if let Some(get_context) = subscriber.downcast_ref::<WithContext>() {
+                get_context.with_context(subscriber, id, move |data, _tracer| {
+                    if let Some(event) = event.take() {
+                        data.builder.events.get_or_insert_with(Vec::new).push(event);
+                    }
+                });
+            }
+        });
+    }
 }

tests/span_ext.rs

@@ -71,3 +71,101 @@ fn set_status_helper(status: Status) -> SpanData {
 
     spans.iter().find(|s| s.name == "root").unwrap().clone()
 }
+
+#[test]
+fn test_add_otel_span_event() {
+    let (_tracer, provider, exporter, subscriber) = test_tracer();
+
+    let event_name = "my_event";
+    let event_attrs = vec![
+        opentelemetry::KeyValue::new("event_key_1", "event_value_1"),
+        opentelemetry::KeyValue::new("event_key_2", 123),
+    ];
+
+    tracing::subscriber::with_default(subscriber, || {
+        let root = tracing::debug_span!("root");
+        let _enter = root.enter(); // Enter span to make it current for the event addition
+
+        // Add the event using the new extension method
+        root.add_otel_span_event(event_name, event_attrs.clone());
+    });
+
+    drop(provider); // flush all spans
+    let spans = exporter.0.lock().unwrap();
+
+    assert_eq!(spans.len(), 1, "Should have exported exactly one span.");
+    let root_span_data = spans.first().unwrap();
+
+    assert_eq!(
+        root_span_data.events.len(),
+        1,
+        "Span should have one event."
+    );
+    let event_data = root_span_data.events.first().unwrap();
+
+    assert_eq!(event_data.name, event_name, "Event name mismatch.");
+    assert_eq!(
+        event_data.attributes, event_attrs,
+        "Event attributes mismatch."
+    );
+}
+
+#[test]
+fn test_add_otel_span_event_with_timestamp() {
+    use std::time::{Duration, SystemTime};
+
+    let (_tracer, provider, exporter, subscriber) = test_tracer();
+
+    let event_name = "my_specific_time_event";
+    let event_attrs = vec![opentelemetry::KeyValue::new("event_key_a", "value_a")];
+    // Define a specific timestamp (e.g., 10 seconds ago)
+    let specific_timestamp = SystemTime::now() - Duration::from_secs(10);
+
+    tracing::subscriber::with_default(subscriber, || {
+        let root = tracing::debug_span!("root_with_timestamped_event");
+        let _enter = root.enter();
+
+        // Add the event using the new extension method with the specific timestamp
+        root.add_otel_span_event_with_timestamp(
+            event_name,
+            specific_timestamp,
+            event_attrs.clone(),
+        );
+    });
+
+    drop(provider); // flush all spans
+    let spans = exporter.0.lock().unwrap();
+
+    assert_eq!(spans.len(), 1, "Should have exported exactly one span.");
+    let root_span_data = spans.first().unwrap();
+
+    assert_eq!(
+        root_span_data.events.len(),
+        1,
+        "Span should have one event."
+    );
+    let event_data = root_span_data.events.first().unwrap();
+
+    assert_eq!(event_data.name, event_name, "Event name mismatch.");
+    assert_eq!(
+        event_data.attributes, event_attrs,
+        "Event attributes mismatch."
+    );
+
+    // Assert the timestamp matches the one we provided
+    // Allow for a small tolerance due to potential precision differences during conversion
+    let timestamp_diff = event_data
+        .timestamp
+        .duration_since(specific_timestamp)
+        .unwrap_or_else(|_| {
+            specific_timestamp
+                .duration_since(event_data.timestamp)
+                .unwrap_or_default()
+        });
+    assert!(
+        timestamp_diff < Duration::from_millis(1),
+        "Timestamp mismatch. Expected: {:?}, Got: {:?}",
+        specific_timestamp,
+        event_data.timestamp
+    );
+}