fix: stabilize Go OTLP scope test

Signed-off-by: Will Killian <wkillian@nvidia.com>

Author: willkill07

crates/core/src/api/subscriber.rs

@@ -18,8 +18,18 @@ use tracing::{Event as TracingEvent, Metadata, Subscriber as TracingSubscriber};
 use tracing_subscriber::layer::Context as LayerContext;
 use uuid::Uuid;
 
-pub(crate) const EVENT_TRACE_TARGET: &str = "nemo_relay::events";
-pub(crate) const EVENT_JSON_FIELD: &str = "event.json";
+/// `tracing` target used by NeMo Relay lifecycle event records.
+///
+/// External tracing layers can filter on this target before decoding records
+/// with [`event_from_tracing`].
+pub const EVENT_TRACE_TARGET: &str = "nemo_relay::events";
+
+/// `tracing` field containing the canonical ATOF JSON representation.
+///
+/// The field is part of NeMo Relay's Rust tracing integration contract. Prefer
+/// [`event_from_tracing`] over reading this field directly when a library wants
+/// a canonical [`Event`].
+pub const EVENT_JSON_FIELD: &str = "event.json";
 
 /// Callback-backed NeMo Relay event subscriber.
 ///
@@ -53,19 +63,19 @@ impl Subscriber {
     }
 
     fn observe_tracing_event(&self, event: &TracingEvent<'_>) {
-        if let Some(event) = event_from_tracing_event(event) {
+        if let Some(event) = event_from_tracing(event) {
             (self.callback)(&event);
         }
     }
 }
 
 impl TracingSubscriber for Subscriber {
     fn enabled(&self, metadata: &Metadata<'_>) -> bool {
-        is_nemo_event_metadata(metadata)
+        is_nemo_relay_event(metadata)
     }
 
     fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest {
-        if is_nemo_event_metadata(metadata) {
+        if is_nemo_relay_event(metadata) {
             Interest::always()
         } else {
             Interest::never()
@@ -104,12 +114,29 @@ where
     }
 }
 
-pub(crate) fn is_nemo_event_metadata(metadata: &Metadata<'_>) -> bool {
+/// Create a tracing-subscriber layer that consumes NeMo Relay lifecycle events.
+///
+/// This is the canonical Rust integration point for libraries that want to
+/// receive NeMo Relay events through `tracing-subscriber` composition instead
+/// of registering directly in the NeMo Relay subscriber registry.
+pub fn tracing_layer(callback: EventSubscriberFn) -> Subscriber {
+    Subscriber::new(callback)
+}
+
+/// Return `true` when tracing metadata belongs to a NeMo Relay lifecycle event.
+///
+/// External layers can use this as a cheap filter before calling
+/// [`event_from_tracing`].
+pub fn is_nemo_relay_event(metadata: &Metadata<'_>) -> bool {
     metadata.target() == EVENT_TRACE_TARGET
 }
 
-pub(crate) fn event_from_tracing_event(event: &TracingEvent<'_>) -> Option<Event> {
-    if !is_nemo_event_metadata(event.metadata()) {
+/// Decode a canonical NeMo Relay [`Event`] from a `tracing` event record.
+///
+/// Returns `None` when the tracing event is not a NeMo Relay lifecycle record or
+/// when the record does not contain a valid canonical event payload.
+pub fn event_from_tracing(event: &TracingEvent<'_>) -> Option<Event> {
+    if !is_nemo_relay_event(event.metadata()) {
         return None;
     }
 

crates/core/tests/integration/api_surface_tests.rs

@@ -54,8 +54,9 @@ use nemo_relay::api::runtime::{create_scope_stack, current_scope_stack, set_thre
 use nemo_relay::api::scope::ScopeType;
 use nemo_relay::api::scope::{event, pop_scope, push_scope};
 use nemo_relay::api::subscriber::{
-    Subscriber as NemoSubscriber, deregister_subscriber, register_subscriber,
-    scope_deregister_subscriber, scope_register_subscriber, scope_subscribe, subscribe,
+    Subscriber as NemoSubscriber, deregister_subscriber, event_from_tracing, is_nemo_relay_event,
+    register_subscriber, scope_deregister_subscriber, scope_register_subscriber, scope_subscribe,
+    subscribe, tracing_layer,
 };
 use nemo_relay::api::tool::ToolAttributes;
 use nemo_relay::api::tool::{
@@ -423,7 +424,7 @@ fn test_subscriber_adapter_composes_as_tracing_subscriber_layer() {
 
     let events = Arc::new(Mutex::new(Vec::new()));
     let sink = events.clone();
-    let layer = NemoSubscriber::new(Arc::new(move |event| {
+    let layer = tracing_layer(Arc::new(move |event| {
         sink.lock().unwrap().push(event.name().to_owned());
     }));
     let subscriber = tracing_subscriber::registry().with(layer);
@@ -444,6 +445,54 @@ fn test_subscriber_adapter_composes_as_tracing_subscriber_layer() {
     );
 }
 
+#[test]
+fn test_public_tracing_event_decoder_supports_custom_layers() {
+    let _lock = TEST_MUTEX.lock().unwrap();
+    reset_global();
+    setup_isolated_thread();
+
+    struct DecodingLayer {
+        events: Arc<Mutex<Vec<String>>>,
+    }
+
+    impl<S> tracing_subscriber::Layer<S> for DecodingLayer
+    where
+        S: tracing::Subscriber,
+    {
+        fn on_event(
+            &self,
+            event: &tracing::Event<'_>,
+            _ctx: tracing_subscriber::layer::Context<'_, S>,
+        ) {
+            if is_nemo_relay_event(event.metadata())
+                && let Some(event) = event_from_tracing(event)
+            {
+                self.events.lock().unwrap().push(event.name().to_owned());
+            }
+        }
+    }
+
+    let events = Arc::new(Mutex::new(Vec::new()));
+    let subscriber = tracing_subscriber::registry().with(DecodingLayer {
+        events: events.clone(),
+    });
+
+    tracing::subscriber::with_default(subscriber, || {
+        event(
+            nemo_relay::api::scope::EmitMarkEventParams::builder()
+                .name("public-tracing-decoder-mark")
+                .build(),
+        )
+        .unwrap();
+        tracing::info!("external-event");
+    });
+
+    assert_eq!(
+        events.lock().unwrap().as_slice(),
+        ["public-tracing-decoder-mark"]
+    );
+}
+
 #[test]
 fn test_subscriber_adapter_ignores_external_tracing_events() {
     let _lock = TEST_MUTEX.lock().unwrap();

docs/about/concepts/subscribers.md

@@ -61,6 +61,35 @@ adapter that implements both `tracing::Subscriber` and
 tracing subscriber or compose it into an existing `tracing-subscriber` registry
 alongside formatting, filtering, OpenTelemetry, or other host layers.
 
+For Rust libraries that want to consume NeMo Relay events through tracing
+subscriber mechanisms, the canonical path is
+`nemo_relay::api::subscriber::tracing_layer(callback)`. The layer decodes NeMo
+Relay tracing records back into canonical `Event` values and invokes the
+callback. Libraries should return or document this layer for host applications
+to compose; they should not call `tracing::subscriber::set_global_default`.
+
+```rust
+use std::sync::Arc;
+use nemo_relay::api::subscriber;
+use tracing_subscriber::prelude::*;
+
+let nemo_events = subscriber::tracing_layer(Arc::new(|event| {
+    // Consume the canonical NeMo Relay Event.
+}));
+
+let tracing_stack = tracing_subscriber::registry()
+    .with(nemo_events);
+
+// Application code owns installation of the tracing subscriber.
+tracing::subscriber::set_global_default(tracing_stack)?;
+```
+
+Libraries that already implement their own `tracing_subscriber::Layer` can use
+`subscriber::is_nemo_relay_event(metadata)` as a target filter and
+`subscriber::event_from_tracing(event)` to decode the canonical event payload.
+These helpers are the supported way to consume NeMo Relay tracing records
+without depending on the raw tracing field layout.
+
 The Rust named APIs remain available under their original names:
 `register_subscriber(name, callback)`, `deregister_subscriber(name)`,
 `scope_register_subscriber(scope_uuid, name, callback)`, and

go/nemo_relay/otel_test.go

@@ -118,24 +118,32 @@ func TestOpenTelemetrySubscriberExportsScopeLifecycleAndMarks(t *testing.T) {
 	}
 	defer func() { _ = subscriber.Deregister(name) }()
 
-	handle, err := PushScope("otel_scope", ScopeTypeAgent)
+	stack, err := NewScopeStack()
 	if err != nil {
-		t.Fatalf("PushScope failed: %v", err)
-	}
-	if err := EmitEvent(
-		"otel_mark",
-		WithEventParent(handle),
-		WithEventData(json.RawMessage(`{"step":1}`)),
-		WithEventMetadata(json.RawMessage(`{"source":"go"}`)),
-	); err != nil {
-		t.Fatalf("EmitEvent failed: %v", err)
-	}
-	if err := PopScope(handle); err != nil {
-		t.Fatalf("PopScope failed: %v", err)
-	}
-	if err := subscriber.ForceFlush(); err != nil {
-		t.Fatalf("ForceFlush failed: %v", err)
+		t.Fatalf("NewScopeStack failed: %v", err)
 	}
+	defer stack.Close()
+
+	stack.Run(func() {
+		handle, err := PushScope("otel_scope", ScopeTypeAgent)
+		if err != nil {
+			t.Fatalf("PushScope failed: %v", err)
+		}
+		if err := EmitEvent(
+			"otel_mark",
+			WithEventParent(handle),
+			WithEventData(json.RawMessage(`{"step":1}`)),
+			WithEventMetadata(json.RawMessage(`{"source":"go"}`)),
+		); err != nil {
+			t.Fatalf("EmitEvent failed: %v", err)
+		}
+		if err := PopScope(handle); err != nil {
+			t.Fatalf("PopScope failed: %v", err)
+		}
+		if err := subscriber.ForceFlush(); err != nil {
+			t.Fatalf("ForceFlush failed: %v", err)
+		}
+	})
 
 	select {
 	case request := <-requests: