chore: Switch SpanExporter to use ShutdownResult

Author: scottgerring

opentelemetry-otlp/src/exporter/http/trace.rs

@@ -4,7 +4,7 @@ use futures_core::future::BoxFuture;
 use http::{header::CONTENT_TYPE, Method};
 use opentelemetry::otel_debug;
 use opentelemetry::trace::{TraceError, TraceResult};
-use opentelemetry_sdk::export::trace::{ExportResult, SpanData, SpanExporter};
+use opentelemetry_sdk::export::trace::{ExportResult, ShutdownResult, SpanData, SpanExporter};
 
 use super::OtlpHttpClient;
 
@@ -65,7 +65,7 @@ impl SpanExporter for OtlpHttpClient {
         })
     }
 
-    fn shutdown(&mut self) -> TraceResult<()> {
+    fn shutdown(&mut self) -> ShutdownResult {
         let _ = self.client.lock()?.take();
         Ok(())
     }

opentelemetry-otlp/src/exporter/tonic/trace.rs

@@ -7,7 +7,7 @@ use opentelemetry_proto::tonic::collector::trace::v1::{
     trace_service_client::TraceServiceClient, ExportTraceServiceRequest,
 };
 use opentelemetry_proto::transform::trace::tonic::group_spans_by_resource_and_scope;
-use opentelemetry_sdk::export::trace::{ExportResult, SpanData, SpanExporter};
+use opentelemetry_sdk::export::trace::{ExportResult, ShutdownResult, SpanData, SpanExporter};
 use tonic::{codegen::CompressionEncoding, service::Interceptor, transport::Channel, Request};
 
 use super::BoxInterceptor;
@@ -92,7 +92,7 @@ impl SpanExporter for TonicTracesClient {
         })
     }
 
-    fn shutdown(&mut self) -> TraceResult<()> {
+    fn shutdown(&mut self) -> ShutdownResult {
         let _ = self.inner.take();
         Ok(())
     }

opentelemetry-sdk/src/export/trace.rs

@@ -5,15 +5,15 @@ use opentelemetry::trace::{SpanContext, SpanId, SpanKind, Status, TraceError};
 use opentelemetry::{InstrumentationScope, KeyValue};
 use std::borrow::Cow;
 use std::fmt::Debug;
-use std::time::SystemTime;
+use std::sync::PoisonError;
+use std::time::{Duration, SystemTime};
+use thiserror::Error;
 
-/// Describes the results of other operations on the trace API.
-pub type TraceResult<T> = Result<T, TraceError>;
+/// Results of an export operation
+pub type ExportResult = Result<(), TraceError>;
 
-/// Describes the results of an export
-/// Note: This is an alias we will remove in the future, favouring
-/// using TraceResult directly.
-pub type ExportResult = TraceResult<()>;
+/// Result of a  shutdown operation
+pub type ShutdownResult = Result<(), ShutdownError>;
 
 /// `SpanExporter` defines the interface that protocol-specific exporters must
 /// implement so that they can be plugged into OpenTelemetry SDK and support
@@ -35,7 +35,7 @@ pub trait SpanExporter: Send + Sync + Debug {
     ///
     /// Any retry logic that is required by the exporter is the responsibility
     /// of the exporter.
-    fn export(&mut self, batch: Vec<SpanData>) -> BoxFuture<'static, TraceResult<()>>;
+    fn export(&mut self, batch: Vec<SpanData>) -> BoxFuture<'static, Result<(), TraceError>>;
 
     /// Shuts down the exporter. Called when SDK is shut down. This is an
     /// opportunity for exporter to do any cleanup required.
@@ -48,7 +48,7 @@ pub trait SpanExporter: Send + Sync + Debug {
     /// flush the data and the destination is unavailable). SDK authors
     /// can decide if they want to make the shutdown timeout
     /// configurable.
-    fn shutdown(&mut self) -> TraceResult<()> {
+    fn shutdown(&mut self) -> ShutdownResult {
         Ok(())
     }
 
@@ -105,3 +105,31 @@ pub struct SpanData {
     /// Instrumentation scope that produced this span
     pub instrumentation_scope: InstrumentationScope,
 }
+
+/// Errors returned by shutdown operations in the Export API.
+#[derive(Error, Debug)]
+#[non_exhaustive]
+pub enum ShutdownError {
+    /// The exporter has already been shut down.
+    #[error("Shutdown already performed")]
+    AlreadyShutdown,
+
+    /// Shutdown timed out before completing.
+    #[error("Shutdown timed out after {0:?}")]
+    Timeout(Duration),
+
+    /// An unexpected error occurred during shutdown.
+    #[error(transparent)]
+    Other(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),
+}
+
+/// Custom error wrapper for string messages.
+#[derive(Error, Debug)]
+#[error("{0}")]
+struct CustomError(String);
+
+impl<T> From<PoisonError<T>> for ShutdownError {
+    fn from(err: PoisonError<T>) -> Self {
+        ShutdownError::Other(Box::new(CustomError(err.to_string())))
+    }
+}

opentelemetry-sdk/src/testing/trace/in_memory_exporter.rs

@@ -1,4 +1,4 @@
-use crate::export::trace::{ExportResult, SpanData, SpanExporter};
+use crate::export::trace::{ExportResult, ShutdownResult, SpanData, SpanExporter};
 use crate::resource::Resource;
 use futures_util::future::BoxFuture;
 use opentelemetry::trace::{TraceError, TraceResult};
@@ -142,7 +142,7 @@ impl SpanExporter for InMemorySpanExporter {
         Box::pin(std::future::ready(Ok(())))
     }
 
-    fn shutdown(&mut self) -> TraceResult<()> {
+    fn shutdown(&mut self) -> ShutdownResult {
         self.reset();
         Ok(())
     }

opentelemetry-sdk/src/testing/trace/span_exporters.rs

@@ -1,5 +1,6 @@
+use crate::export::trace::{ShutdownError, ShutdownResult};
 use crate::{
-    export::trace::{ExportResult, SpanData, SpanExporter, TraceResult},
+    export::trace::{ExportResult, SpanData, SpanExporter},
     trace::{SpanEvents, SpanLinks},
 };
 use futures_util::future::BoxFuture;
@@ -53,10 +54,10 @@ impl SpanExporter for TokioSpanExporter {
         Box::pin(std::future::ready(Ok(())))
     }
 
-    fn shutdown(&mut self) -> TraceResult<()> {
+    fn shutdown(&mut self) -> ShutdownResult {
         self.tx_shutdown
             .send(())
-            .map_err::<TraceError, _>(|err| TraceError::Other(Box::new(err)))?;
+            .map_err::<ShutdownError, _>(|err| ShutdownError::Other(Box::new(err)))?;
         Ok(())
     }
 }

opentelemetry-sdk/src/trace/span_processor.rs

@@ -149,7 +149,10 @@ impl SpanProcessor for SimpleSpanProcessor {
     }
 
     fn shutdown(&self) -> TraceResult<()> {
-        self.exporter.lock()?.shutdown()
+        self.exporter
+            .lock()?
+            .shutdown()
+            .map_err(|e| TraceError::Other(Box::new(e)))
     }
 
     fn set_resource(&mut self, resource: &Resource) {

opentelemetry-stdout/src/trace/exporter.rs

@@ -2,10 +2,10 @@ use chrono::{DateTime, Utc};
 use core::fmt;
 use futures_util::future::BoxFuture;
 use opentelemetry::trace::{TraceError, TraceResult};
+use opentelemetry_sdk::export::trace::ShutdownResult;
 use opentelemetry_sdk::export::{self, trace::ExportResult};
-use std::sync::atomic;
-
 use opentelemetry_sdk::resource::Resource;
+use std::sync::atomic;
 
 /// An OpenTelemetry exporter that writes Spans to stdout on export.
 pub struct SpanExporter {
@@ -59,7 +59,7 @@ impl opentelemetry_sdk::export::trace::SpanExporter for SpanExporter {
         }
     }
 
-    fn shutdown(&mut self) -> TraceResult<()> {
+    fn shutdown(&mut self) -> ShutdownResult {
         self.is_shutdown.store(true, atomic::Ordering::SeqCst);
         Ok(())
     }