Struct AgentPipeline

pub struct AgentPipeline { /* private fields */ }

👎Deprecated since 0.21.0: Please migrate to opentelemetry-otlp exporter.

Deprecation Notice: Ingestion of OTLP is now supported in Jaeger please check crates.io for more details.

AgentPipeline config and build a exporter targeting a jaeger agent using UDP as transport layer protocol.

UDP packet max length

The exporter uses UDP to communicate with the agent. UDP requests may be rejected if it’s too long. See UDP packet size for details.

Users can utilise with_max_packet_size and with_auto_split_batch to avoid spans loss or UDP requests failure.

The default max_packet_size is 65000(why 65000?). If your platform has a smaller limit on UDP packet. You will need to adjust the max_packet_size accordingly.

Set auto_split_batch to true will config the exporter to split the batch based on max_packet_size automatically. Note that it has a performance overhead as every batch could require multiple requests to export.

For example, OSX UDP packet limit is 9216 by default. You can configure the pipeline as following to avoid UDP packet breaches the limit.

    let tracer = opentelemetry_jaeger::new_agent_pipeline()
        .with_endpoint("localhost:6831")
        .with_service_name("my_app")
        .with_max_packet_size(9_216)
        .with_auto_split_batch(true)
        .install_batch(Tokio).unwrap();

Environment variables

The following environment variables are available to configure the agent exporter.

• OTEL_EXPORTER_JAEGER_AGENT_HOST, set the host of the agent. If the OTEL_EXPORTER_JAEGER_AGENT_HOST is not set, the value will be ignored.
• OTEL_EXPORTER_JAEGER_AGENT_PORT, set the port of the agent. If the OTEL_EXPORTER_JAEGER_AGENT_HOST is not set, the exporter will use 127.0.0.1 as the host.

Implementations

impl AgentPipeline

pub fn with_endpoint<T: Into<String>>(self, agent_endpoint: T) -> Self

set the endpoint of the agent.

It usually composed by host ip and the port number. Any valid socket address can be used.

Default to be 127.0.0.1:6831.

pub fn with_max_packet_size(self, max_packet_size: usize) -> Self

Assign the max packet size in bytes.

It should be consistent with the limit of platforms. Otherwise, UDP requests maybe reject with error like thrift agent failed with transport error or thrift agent failed with message too long.

The exporter will cut off spans if the batch is long. To avoid this, set auto_split_batch to true to split a batch into multiple UDP packets.

Default to be 65000.

pub fn with_auto_split_batch(self, should_auto_split: bool) -> Self

Config whether to auto split batches.

When auto split is set to true, the exporter will try to split the batch into smaller ones so that there will be minimal data loss. It will impact the performance.

Note that if the length of one serialized span is longer than the max_packet_size. The exporter will return an error as it cannot export the span. Use jaeger collector instead of jaeger agent may be help in this case as the exporter will use HTTP to communicate with jaeger collector.

Default to be false.

pub fn with_service_name<T: Into<String>>(self, service_name: T) -> Self

Set the service name of the application. It generally is the name of application. Critically, Jaeger backend depends on Span.Process.ServiceName to identify the service that produced the spans.

Opentelemetry allows set the service name using multiple methods. This functions takes priority over all other methods.

If the service name is not set. It will default to be unknown_service.

pub fn with_instrumentation_library_tags(self, should_export: bool) -> Self

Config whether to export information of instrumentation library.

It’s required to report instrumentation library as span tags. However it does have a overhead on performance, performance sensitive applications can use this function to opt out reporting instrumentation library.

Default to be true.

pub fn with_trace_config(self, config: Config) -> Self

Assign the opentelemetry SDK configurations for the exporter pipeline.

For mapping between opentelemetry configurations and Jaeger spans. Please refer the spec.

Examples

Set service name via resource.

use opentelemetry::KeyValue;
use opentelemetry_sdk::{Resource, trace::Config};

let pipeline = opentelemetry_jaeger::new_agent_pipeline()
                .with_trace_config(
                      Config::default()
                        .with_resource(Resource::new(vec![KeyValue::new("service.name", "my-service")]))
                );

pub fn with_batch_processor_config(self, config: BatchConfig) -> Self

Assign the batch span processor for the exporter pipeline.

If a simple span processor is used by install_simple or build_simple, then this config will not be ignored.

Examples

Set max queue size.

use opentelemetry_sdk::trace::BatchConfigBuilder;

let pipeline = opentelemetry_jaeger::new_agent_pipeline()
                .with_batch_processor_config(
                      BatchConfigBuilder::default()
                        .with_max_queue_size(200)
                        .build()
                );

pub fn build_simple(self) -> Result<TracerProvider, TraceError>

Build a TracerProvider using a blocking exporter and configurations from the pipeline.

The exporter will send each span to the agent upon the span ends.

pub fn build_batch<R>(self, runtime: R) -> Result<TracerProvider, TraceError>

where R: JaegerTraceRuntime,

Build a TracerProvider using a async exporter and configurations from the pipeline.

The exporter will collect spans in a batch and send them to the agent.

It’s possible to lose spans up to a batch when the application shuts down. So users should use shut_down_tracer_provider to block the shut down process until all remaining spans have been sent.

Commonly used runtime are provided via rt-tokio, rt-tokio-current-thread, rt-async-std features.

pub fn install_simple(self) -> Result<Tracer, TraceError>

Similar to build_simple but also returns a tracer from the tracer provider.

The tracer name is opentelemetry-jaeger. The tracer version will be the version of this crate.

pub fn install_batch<R>(self, runtime: R) -> Result<Tracer, TraceError>

where R: JaegerTraceRuntime,

Similar to build_batch but also returns a tracer from the tracer provider.

The tracer name is opentelemetry-jaeger. The tracer version will be the version of this crate.

pub fn build_async_agent_exporter<R>( self, runtime: R, ) -> Result<Exporter, TraceError>

where R: JaegerTraceRuntime,

Build an jaeger exporter targeting a jaeger agent and running on the async runtime.

pub fn build_sync_agent_exporter(self) -> Result<Exporter, TraceError>

Build an jaeger exporter targeting a jaeger agent and running on the sync runtime.

Trait Implementations

impl Debug for AgentPipeline

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentPipeline

fn default() -> Self

Returns the “default value” for a type.