Struct OtelSdkBuilder 

pub struct OtelSdkBuilder { /* private fields */ }

Builder for configuring and initialising the OpenTelemetry SDK.

Example

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

fn main() -> Result<(), SdkError> {
    // Simple case - uses defaults (localhost:4318 for HTTP)
    let _guard = OtelSdkBuilder::new().build()?;

    // With environment variables
    let _guard = OtelSdkBuilder::new()
        .with_env("OTEL_")
        .build()?;

    // Full configuration
    let _guard = OtelSdkBuilder::new()
        .with_file("/var/task/otel-config.toml")
        .with_env("OTEL_")
        .endpoint("http://collector:4318")
        .service_name("my-lambda")
        .build()?;

    Ok(())
}

Implementations

impl OtelSdkBuilder

pub fn new() -> OtelSdkBuilder

Creates a new builder with default configuration.

Defaults include:

• Protocol: HTTP with protobuf encoding
• Endpoint: http://localhost:4318 (or 4317 for gRPC)
• All signals enabled (traces, metrics, logs)
• Tracing subscriber initialisation enabled
• Lambda resource detection enabled

pub fn from_figment(figment: Figment) -> OtelSdkBuilder

Creates a builder from an existing figment.

This allows power users to construct complex configuration chains before passing them to the SDK builder.

Example

use figment::{Figment, providers::{Env, Format, Toml}};
use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

let figment = Figment::new()
    .merge(Toml::file("/etc/otel-defaults.toml"))
    .merge(Toml::file("/var/task/otel-config.toml"))
    .merge(Env::prefixed("OTEL_").split("_"));

let _guard = OtelSdkBuilder::from_figment(figment)
    .service_name("my-lambda")
    .build()?;

pub fn with_file<P>(self, path: P) -> OtelSdkBuilder

where P: AsRef<Path>,

Merges configuration from a TOML file.

If the file doesn’t exist, it’s silently skipped. This allows optional configuration files that may or may not be present.

Example

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

let _guard = OtelSdkBuilder::new()
    .with_file("/var/task/otel-config.toml")  // Optional
    .with_file("./otel-local.toml")           // For development
    .build()?;

pub fn with_env(self, prefix: &str) -> OtelSdkBuilder

Merges configuration from environment variables with the given prefix.

Environment variables are split on underscores to match nested config. For example, with prefix OTEL_:

• OTEL_ENDPOINT_URL → endpoint.url
• OTEL_ENDPOINT_PROTOCOL → endpoint.protocol
• OTEL_TRACES_ENABLED → traces.enabled
• OTEL_RESOURCE_SERVICE_NAME → resource.service_name

Example

export OTEL_ENDPOINT_URL=http://collector:4318
export OTEL_ENDPOINT_PROTOCOL=grpc
export OTEL_TRACES_ENABLED=true
export OTEL_RESOURCE_SERVICE_NAME=my-lambda

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

let _guard = OtelSdkBuilder::new()
    .with_env("OTEL_")
    .build()?;

pub fn with_standard_env(self) -> OtelSdkBuilder

Merges configuration from standard OpenTelemetry environment variables.

This reads the standard OTEL_* environment variables as defined by the OpenTelemetry specification:

• OTEL_EXPORTER_OTLP_ENDPOINT → endpoint URL
• OTEL_EXPORTER_OTLP_PROTOCOL → protocol (grpc, http/protobuf, http/json)
• OTEL_SERVICE_NAME → service name
• OTEL_TRACES_EXPORTER → traces exporter (otlp, none)
• OTEL_METRICS_EXPORTER → metrics exporter (otlp, none)
• OTEL_LOGS_EXPORTER → logs exporter (otlp, none)

pub fn endpoint(self, url: impl Into<String>) -> OtelSdkBuilder

Sets the OTLP endpoint URL explicitly.

This overrides any configuration from files or environment variables.

For HTTP protocols, signal-specific paths (/v1/traces, /v1/metrics, /v1/logs) are appended automatically.

Example

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

let _guard = OtelSdkBuilder::new()
    .endpoint("http://collector.internal:4318")
    .build()?;

pub fn protocol(self, protocol: Protocol) -> OtelSdkBuilder

Sets the export protocol.

This overrides any configuration from files or environment variables.

The default endpoint changes based on protocol:

• Protocol::Grpc → http://localhost:4317
• Protocol::HttpBinary → http://localhost:4318
• Protocol::HttpJson → http://localhost:4318

pub fn service_name(self, name: impl Into<String>) -> OtelSdkBuilder

Sets the service name resource attribute.

This is the most commonly configured resource attribute and identifies your service in the telemetry backend.

pub fn service_version(self, version: impl Into<String>) -> OtelSdkBuilder

Sets the service version resource attribute.

pub fn deployment_environment(self, env: impl Into<String>) -> OtelSdkBuilder

Sets the deployment environment resource attribute.

pub fn resource_attribute( self, key: impl Into<String>, value: impl Into<String>, ) -> OtelSdkBuilder

Adds a resource attribute.

pub fn with_resource(self, resource: Resource) -> OtelSdkBuilder

Provides a pre-built OpenTelemetry Resource.

This takes precedence over individual resource configuration. Use this when you need fine-grained control over resource construction.

pub fn resource<F>(self, f: F) -> OtelSdkBuilder

where F: FnOnce(ResourceConfigBuilder) -> ResourceConfigBuilder,

Configures the resource using a builder function.

Example

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

let _guard = OtelSdkBuilder::new()
    .resource(|r| r
        .service_name("my-lambda")
        .service_version(env!("CARGO_PKG_VERSION"))
        .deployment_environment("production"))
    .build()?;

pub fn traces(self, enabled: bool) -> OtelSdkBuilder

Enables or disables trace collection.

Default: enabled

pub fn metrics(self, enabled: bool) -> OtelSdkBuilder

Enables or disables metrics collection.

Default: enabled

pub fn logs(self, enabled: bool) -> OtelSdkBuilder

Enables or disables log collection.

Default: enabled

pub fn without_tracing_subscriber(self) -> OtelSdkBuilder

Disables automatic tracing subscriber initialisation.

By default, the SDK sets up a tracing-subscriber with tracing-opentelemetry and opentelemetry-appender-tracing integration. Disable this if you want to configure the subscriber yourself.

pub fn fallback(self, fallback: ExportFallback) -> OtelSdkBuilder

Sets the fallback strategy for failed exports (planned feature).

Note: The fallback API is defined but not yet wired into the export pipeline. The handler will be stored but not invoked on export failures. Full implementation is planned for a future release.

When implemented, the fallback handler will be called when an export fails after all retry attempts have been exhausted. It will receive the original OTLP request payload, which can be preserved via alternative transport.

Example

use opentelemetry_configuration::{OtelSdkBuilder, ExportFallback, SdkError};

let _guard = OtelSdkBuilder::new()
    .fallback(ExportFallback::Stdout)
    .build()?;

pub fn with_fallback<F>(self, f: F) -> OtelSdkBuilder

where F: Fn(ExportFailure) -> Result<(), Box<dyn Error + Sync + Send>> + Send + Sync + 'static,

Sets a custom fallback handler using a closure (planned feature).

Note: The fallback API is defined but not yet wired into the export pipeline. The handler will be stored but not invoked on export failures. Full implementation is planned for a future release.

When implemented, the closure will receive the full ExportFailure including the original OTLP request payload.

Example

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

let _guard = OtelSdkBuilder::new()
    .with_fallback(|failure| {
        // Write the protobuf payload to S3, a queue, etc.
        let bytes = failure.request.to_protobuf();
        eprintln!(
            "Failed to export {} ({} bytes): {}",
            failure.request.signal_type(),
            bytes.len(),
            failure.error
        );
        Ok(())
    })
    .build()?;

pub fn header( self, key: impl Into<String>, value: impl Into<String>, ) -> OtelSdkBuilder

Adds an HTTP header to all export requests.

Useful for authentication or custom routing.

pub fn extract_config(&self) -> Result<OtelSdkConfig, SdkError>

Extracts the configuration for inspection or debugging.

Errors

Returns an error if configuration extraction fails or if the endpoint URL is invalid.

pub fn build(self) -> Result<OtelGuard, SdkError>

Builds and initialises the OpenTelemetry SDK.

Returns an OtelGuard that manages provider lifecycle. When the guard is dropped, all providers are flushed and shut down.

Errors

Returns an error if:

• Configuration extraction fails
• Provider initialisation fails
• Tracing subscriber initialisation fails

Example

use opentelemetry_configuration::{OtelSdkBuilder, SdkError};

fn main() -> Result<(), SdkError> {
    let _guard = OtelSdkBuilder::new()
        .with_env("OTEL_")
        .service_name("my-lambda")
        .build()?;

    tracing::info!("Application started");

    // Guard automatically shuts down providers on drop
    Ok(())
}

Trait Implementations

impl Default for OtelSdkBuilder

fn default() -> OtelSdkBuilder

Returns the “default value” for a type.