refactor(otel): share OTLP trace provider setup

AGENTS.md

@@ -37,6 +37,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `crates/openshell-bootstrap/` | Gateway metadata | Gateway registration metadata, auth token storage, mTLS bundle storage |
 | `crates/openshell-gateway-interceptors/` | Gateway interceptors | Intercepts and transforms configured gRPC requests at the gateway routing boundary |
 | `crates/openshell-ocsf/` | OCSF logging | OCSF v1.7.0 event types, builders, shorthand/JSONL formatters, tracing layers |
+| `crates/openshell-otel/` | OpenTelemetry support | Shared OTLP trace provider, resource, and tracing-layer construction |
 | `crates/openshell-core/` | Shared core | Common types, configuration, error handling |
 | `crates/openshell-sdk/` | Shared client SDK | Async Rust gateway client (gRPC transport, TLS, OIDC refresh, edge tunnel); consumed by CLI, TUI, and `@openshell/sdk` |
 | `crates/openshell-providers/` | Provider management | Credential provider backends |

architecture/gateway.md

@@ -615,7 +615,8 @@ replace the existing logging paths.
 export: the table's presence is the on-switch, and `OTEL_EXPORTER_OTLP_ENDPOINT`
 is ignored so enablement has a single source. TOML decides whether and where
 to export; the SDK's `OTEL_*` variables tune how. Transport is OTLP over gRPC
-only.
+only. Shared provider, resource, and tracing-layer construction lives in
+`openshell-otel`.
 
 Span emission requires no per-handler instrumentation. The `tower_http`
 `TraceLayer` in `multiplex.rs` opens a span per inbound request, and that span

crates/openshell-otel/Cargo.toml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "openshell-otel"
+description = "Shared OpenTelemetry trace export support for OpenShell services"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+http = { workspace = true }
+opentelemetry = { workspace = true }
+opentelemetry_sdk = { workspace = true }
+opentelemetry-otlp = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+tracing-opentelemetry = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true }
+
+[lints]
+workspace = true

crates/openshell-otel/src/lib.rs

@@ -0,0 +1,198 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Shared OpenTelemetry trace export support for `OpenShell` services.
+
+use opentelemetry::KeyValue;
+use opentelemetry::trace::TracerProvider as _;
+use opentelemetry_otlp::{SpanExporter, WithExportConfig};
+use opentelemetry_sdk::Resource;
+use opentelemetry_sdk::trace::SdkTracer;
+pub use opentelemetry_sdk::trace::SdkTracerProvider;
+use tracing::Subscriber;
+use tracing_opentelemetry::OpenTelemetryLayer;
+use tracing_subscriber::Layer as _;
+use tracing_subscriber::registry::LookupSpan;
+
+const SDK_UNKNOWN_SERVICE_PREFIX: &str = "unknown_service";
+
+/// How a process chooses its OpenTelemetry `service.name`.
+#[derive(Debug, Clone, Copy)]
+pub enum ServiceName<'a> {
+    /// Always use this name, overriding `OTEL_SERVICE_NAME`.
+    Fixed(&'a str),
+    /// Use `OTEL_SERVICE_NAME` when set, otherwise use this default.
+    EnvironmentOr(&'a str),
+}
+
+/// Inputs for an OTLP/gRPC trace provider.
+#[derive(Debug, Clone)]
+pub struct OtlpTraceConfig<'a> {
+    pub endpoint: &'a str,
+    pub service_name: ServiceName<'a>,
+    pub service_version: Option<&'a str>,
+    pub resource_attributes: Vec<KeyValue>,
+}
+
+/// Failure to construct an OTLP trace provider.
+#[derive(Debug, thiserror::Error)]
+pub enum SetupError {
+    #[error("OTLP endpoint is empty")]
+    EmptyEndpoint,
+
+    #[error("invalid OTLP endpoint {endpoint:?}: {source}")]
+    InvalidEndpoint {
+        endpoint: String,
+        source: http::uri::InvalidUri,
+    },
+
+    #[error("failed to build the OTLP span exporter: {0}")]
+    Exporter(#[from] opentelemetry_otlp::ExporterBuildError),
+}
+
+fn resource_attributes(config: &OtlpTraceConfig<'_>) -> Vec<KeyValue> {
+    let mut attributes = config.resource_attributes.clone();
+    if let Some(version) = config
+        .service_version
+        .map(str::trim)
+        .filter(|version| !version.is_empty())
+    {
+        attributes.push(KeyValue::new("service.version", version.to_string()));
+    }
+    attributes
+}
+
+/// Build the OpenTelemetry resource for a trace provider configuration.
+#[must_use]
+pub fn resource_for(config: &OtlpTraceConfig<'_>) -> Resource {
+    let attributes = resource_attributes(config);
+    match config.service_name {
+        ServiceName::Fixed(name) => Resource::builder()
+            .with_service_name(name.trim().to_string())
+            .with_attributes(attributes)
+            .build(),
+        ServiceName::EnvironmentOr(default) => {
+            let detected = Resource::builder()
+                .with_attributes(attributes.clone())
+                .build();
+            if detected
+                .get(&opentelemetry::Key::from_static_str("service.name"))
+                .is_some_and(|value| !value.to_string().starts_with(SDK_UNKNOWN_SERVICE_PREFIX))
+            {
+                detected
+            } else {
+                Resource::builder()
+                    .with_service_name(default.trim().to_string())
+                    .with_attributes(attributes)
+                    .build()
+            }
+        }
+    }
+}
+
+/// Build an OTLP/gRPC trace provider.
+pub fn build_provider(config: &OtlpTraceConfig<'_>) -> Result<SdkTracerProvider, SetupError> {
+    let endpoint = config.endpoint.trim();
+    if endpoint.is_empty() {
+        return Err(SetupError::EmptyEndpoint);
+    }
+    endpoint
+        .parse::<http::Uri>()
+        .map_err(|source| SetupError::InvalidEndpoint {
+            endpoint: endpoint.to_string(),
+            source,
+        })?;
+
+    let exporter = SpanExporter::builder()
+        .with_tonic()
+        .with_endpoint(endpoint)
+        .build()?;
+
+    Ok(SdkTracerProvider::builder()
+        .with_batch_exporter(exporter)
+        .with_resource(resource_for(config))
+        .build())
+}
+
+/// Build the provider for an optional OTLP configuration.
+///
+/// Telemetry setup failures disable export and remain available for the caller
+/// to report after its tracing subscriber is installed.
+#[must_use]
+pub fn provider_for(
+    config: Option<OtlpTraceConfig<'_>>,
+) -> (Option<SdkTracerProvider>, Option<SetupError>) {
+    match config.as_ref().map(build_provider) {
+        None => (None, None),
+        Some(Ok(provider)) => (Some(provider), None),
+        Some(Err(error)) => (None, Some(error)),
+    }
+}
+
+/// Filtered OpenTelemetry layer returned by [`layer`].
+pub type OtlpLayer<S> = tracing_subscriber::filter::Filtered<
+    OpenTelemetryLayer<S, SdkTracer>,
+    tracing_subscriber::filter::FilterFn,
+    S,
+>;
+
+/// Build a tracing layer that exports spans and excludes exporter callsites.
+pub fn layer<S>(provider: &SdkTracerProvider, instrumentation_scope: &'static str) -> OtlpLayer<S>
+where
+    S: Subscriber + for<'span> LookupSpan<'span>,
+{
+    tracing_opentelemetry::layer()
+        .with_tracer(provider.tracer(instrumentation_scope))
+        .with_filter(tracing_subscriber::filter::filter_fn(|metadata| {
+            metadata.is_span() && !metadata.target().starts_with("opentelemetry")
+        }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resource_uses_fixed_service_identity_and_custom_attributes() {
+        let resource = resource_for(&OtlpTraceConfig {
+            endpoint: "http://127.0.0.1:4317",
+            service_name: ServiceName::Fixed("openshell-driver-vm"),
+            service_version: Some("1.2.3"),
+            resource_attributes: vec![KeyValue::new("openshell.gateway.name", "vm-dev")],
+        });
+
+        assert_eq!(
+            resource
+                .get(&opentelemetry::Key::from_static_str("service.name"))
+                .map(|value| value.to_string()),
+            Some("openshell-driver-vm".to_string())
+        );
+        assert_eq!(
+            resource
+                .get(&opentelemetry::Key::from_static_str("service.version"))
+                .map(|value| value.to_string()),
+            Some("1.2.3".to_string())
+        );
+        assert_eq!(
+            resource
+                .get(&opentelemetry::Key::from_static_str(
+                    "openshell.gateway.name",
+                ))
+                .map(|value| value.to_string()),
+            Some("vm-dev".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn malformed_endpoint_disables_export_with_a_reportable_error() {
+        let (provider, error) = provider_for(Some(OtlpTraceConfig {
+            endpoint: "definitely not a url",
+            service_name: ServiceName::Fixed("test-service"),
+            service_version: None,
+            resource_attributes: Vec::new(),
+        }));
+
+        assert!(provider.is_none());
+        assert!(matches!(error, Some(SetupError::InvalidEndpoint { .. })));
+    }
+}

crates/openshell-server/Cargo.toml

@@ -22,6 +22,7 @@ openshell-driver-kubernetes = { path = "../openshell-driver-kubernetes" }
 openshell-driver-podman = { path = "../openshell-driver-podman" }
 openshell-gateway-interceptors = { path = "../openshell-gateway-interceptors" }
 openshell-ocsf = { path = "../openshell-ocsf" }
+openshell-otel = { path = "../openshell-otel" }
 openshell-policy = { path = "../openshell-policy" }
 openshell-prover = { path = "../openshell-prover" }
 openshell-providers = { path = "../openshell-providers" }
@@ -72,7 +73,6 @@ tracing-subscriber = { workspace = true }
 # OpenTelemetry (OTLP trace export, opt-in via [openshell.gateway.otlp])
 opentelemetry = { workspace = true }
 opentelemetry_sdk = { workspace = true }
-opentelemetry-otlp = { workspace = true }
 tracing-opentelemetry = { workspace = true }
 
 # Metrics