opentelemetry_sdk/trace/
export.rs

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

opentelemetry_sdk/trace/
export.rs
