opentelemetry_sdk/trace/
export.rs

1//! Trace exporters
2use crate::error::OTelSdkResult;
3use crate::Resource;
4use opentelemetry::trace::{SpanContext, SpanId, SpanKind, Status};
5use opentelemetry::{InstrumentationScope, KeyValue};
6use std::borrow::Cow;
7use std::fmt::Debug;
8use std::time::{Duration, SystemTime};
9
10/// `SpanExporter` defines the interface that protocol-specific exporters must
11/// implement so that they can be plugged into OpenTelemetry SDK and support
12/// sending of telemetry data.
13///
14/// The goal of the interface is to minimize burden of implementation for
15/// protocol-dependent telemetry exporters. The protocol exporter is expected to
16/// be primarily a simple telemetry data encoder and transmitter.
17pub trait SpanExporter: Send + Sync + Debug {
18    /// Exports a batch of readable spans. Protocol exporters that will
19    /// implement this function are typically expected to serialize and transmit
20    /// the data to the destination.
21    ///
22    /// This function will never be called concurrently for the same exporter
23    /// instance. It can be called again only after the current call returns.
24    ///
25    /// This function must not block indefinitely, there must be a reasonable
26    /// upper limit after which the call must time out with an error result.
27    ///
28    /// Any retry logic that is required by the exporter is the responsibility
29    /// of the exporter.
30    fn export(
31        &self,
32        batch: Vec<SpanData>,
33    ) -> impl std::future::Future<Output = OTelSdkResult> + Send;
34
35    /// Shuts down the exporter. Called when SDK is shut down. This is an
36    /// opportunity for exporter to do any cleanup required.
37    ///
38    /// This function should be called only once for each `SpanExporter`
39    /// instance. After the call to `shutdown`, subsequent calls to `export` are
40    /// not allowed and should return an error.
41    ///
42    /// This function should not block indefinitely (e.g. if it attempts to
43    /// flush the data and the destination is unavailable). SDK authors
44    /// can decide if they want to make the shutdown timeout
45    /// configurable.
46    fn shutdown_with_timeout(&mut self, _timeout: Duration) -> OTelSdkResult {
47        Ok(())
48    }
49    /// Shuts down the exporter with default timeout.
50    fn shutdown(&mut self) -> OTelSdkResult {
51        self.shutdown_with_timeout(Duration::from_nanos(5))
52    }
53
54    /// This is a hint to ensure that the export of any Spans the exporter
55    /// has received prior to the call to this function SHOULD be completed
56    /// as soon as possible, preferably before returning from this method.
57    ///
58    /// This function SHOULD provide a way to let the caller know
59    /// whether it succeeded, failed or timed out.
60    ///
61    /// This function SHOULD only be called in cases where it is absolutely necessary,
62    /// such as when using some FaaS providers that may suspend the process after
63    /// an invocation, but before the exporter exports the completed spans.
64    ///
65    /// This function SHOULD complete or abort within some timeout. This function can be
66    /// implemented as a blocking API or an asynchronous API which notifies the caller via
67    /// a callback or an event. OpenTelemetry client authors can decide if they want to
68    /// make the flush timeout configurable.
69    fn force_flush(&mut self) -> OTelSdkResult {
70        Ok(())
71    }
72
73    /// Set the resource for the exporter.
74    fn set_resource(&mut self, _resource: &Resource) {}
75}
76
77/// `SpanData` contains all the information collected by a `Span` and can be used
78/// by exporters as a standard input.
79#[derive(Clone, Debug, PartialEq)]
80pub struct SpanData {
81    /// Exportable `SpanContext`
82    pub span_context: SpanContext,
83    /// Span parent id
84    pub parent_span_id: SpanId,
85    /// Parent span is remote flag (for span flags)
86    pub parent_span_is_remote: bool,
87    /// Span kind
88    pub span_kind: SpanKind,
89    /// Span name
90    pub name: Cow<'static, str>,
91    /// Span start time
92    pub start_time: SystemTime,
93    /// Span end time
94    pub end_time: SystemTime,
95    /// Span attributes
96    pub attributes: Vec<KeyValue>,
97    /// The number of attributes that were above the configured limit, and thus
98    /// dropped.
99    pub dropped_attributes_count: u32,
100    /// Span events
101    pub events: crate::trace::SpanEvents,
102    /// Span Links
103    pub links: crate::trace::SpanLinks,
104    /// Span status
105    pub status: Status,
106    /// Instrumentation scope that produced this span
107    pub instrumentation_scope: InstrumentationScope,
108}
opentelemetry_sdk/trace/export.rs

opentelemetry_sdk/trace/
export.rs
