Struct Tracing

pub struct Tracing { /* private fields */ }

Easily initialize a set of pre-configured Subscriber layers.

Usage

Tracing Guard

The configured subscribers are active as long as the tracing guard returned by Tracing::init is in scope and not dropped. Dropping it results in subscribers being shut down, which can lead to loss of telemetry data when done before exiting the application. This is why it is important to hold onto the guard as long as required.

Name the guard variable appropriately, do not just use let _ = ..., as that will drop immediately.

#[tokio::main]
async fn main() -> Result<(), Error> {
    let _tracing_guard = Tracing::builder() // < Scope starts here
        .service_name("test")               // |
        .build()                            // |
        .init()?;                           // |
                                            // |
    tracing::info!("log a message");        // |
    Ok(())                                  // < Scope ends here, guard is dropped
}

Pre-configured Tracing Instance

There are two different styles to configure a Tracing instance: Using an opinionated pre- configured instance or a fully customizable builder. The first option should be suited for pretty much all operators by using sane defaults and applying best practices out-of-the-box. Tracing::pre_configured lists details about environment variables, filter levels and defaults used.

use stackable_telemetry::tracing::{Tracing, TelemetryOptions, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let options = TelemetryOptions {
         console_log_disabled: false,
         console_log_format: Default::default(),
         file_log_directory: None,
         file_log_rotation_period: None,
         file_log_max_files: Some(6),
         otel_trace_exporter_enabled: true,
         otel_log_exporter_enabled: true,
     };

    let _tracing_guard = Tracing::pre_configured("test", options).init()?;

    tracing::info!("log a message");

    Ok(())
}

Also see the documentation for TelemetryOptions which details how it can be used as CLI arguments via [clap]. Additionally see this section in the docs for a full list of environment variables and CLI arguments used by the pre-configured instance.

Builders

When choosing the builder, there are two different styles to configure individual subscribers: Using the sophisticated SettingsBuilder or the simplified tuple style for basic configuration. Currently, three different subscribers are supported: console output, OTLP log export, and OTLP trace export.

Basic Configuration

A basic configuration of subscribers can be done by using 2-tuples or 3-tuples, also called doubles and triples. Using tuples, the subscriber can be enabled/disabled and it’s environment variable and default level can be set.

use stackable_telemetry::tracing::{Tracing, Error, settings::Settings};
use tracing_subscriber::filter::LevelFilter;

#[tokio::main]
async fn main() -> Result<(), Error> {
    // This can come from a Clap argument for example. The enabled builder
    // function below allows enabling/disabling certain subscribers during
    // runtime.
    let otlp_log_flag = false;

    let _tracing_guard = Tracing::builder()
        .service_name("test")
        .with_console_output(("TEST_CONSOLE", LevelFilter::INFO))
        .with_otlp_log_exporter(("TEST_OTLP_LOG", LevelFilter::DEBUG, otlp_log_flag))
        .build()
        .init()?;

    tracing::info!("log a message");

    Ok(())
}

Advanced Configuration

More advanced configurations can be done via the Settings::builder function. Each subscriber provides specific settings based on a common set of options. These options can be customized via the following methods:

• SettingsBuilder::console_log_settings_builder
• SettingsBuilder::otlp_log_settings_builder
• SettingsBuilder::otlp_trace_settings_builder

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Control the otlp_log subscriber at runtime
    let otlp_log_flag = false;

    let _tracing_guard = Tracing::builder()
        .service_name("test")
        .with_console_output(
            Settings::builder()
                .with_environment_variable("CONSOLE_LOG")
                .with_default_level(LevelFilter::INFO)
                .build()
        )
        .with_file_output(
            Settings::builder()
                .with_environment_variable("FILE_LOG")
                .with_default_level(LevelFilter::INFO)
                .file_log_settings_builder("/tmp/logs", "operator.log")
                .build()
        )
        .with_otlp_log_exporter(otlp_log_flag.then(|| {
            Settings::builder()
                .with_environment_variable("OTLP_LOG")
                .with_default_level(LevelFilter::DEBUG)
                .build()
        }))
        .with_otlp_trace_exporter(
            Settings::builder()
                .with_environment_variable("OTLP_TRACE")
                .with_default_level(LevelFilter::TRACE)
                .build()
        )
        .build()
        .init()?;

    tracing::info!("log a message");

    Ok(())
}

Environment Variables and CLI Arguments

It should be noted that the CLI arguments (listed in parentheses) are only available when the clap feature is enabled.

Console logs

• CONSOLE_LOG_DISABLED (--console-log-disabled): Disables console logs when set to true.
• CONSOLE_LOG_FORMAT (--console-log-format): Set the format for the console logs.
• CONSOLE_LOG_LEVEL: Set the log level for the console logs.

File logs

• FILE_LOG_DIRECTORY (--file-log-directory): Enable the file logs and set the file log directory.
• FILE_LOG_ROTATION_PERIOD (--file-log-rotation-period): Set the rotation period of log files.
• FILE_LOG_MAX_FILES (--file-log-max-files): Set the maximum number of log files to keep.
• FILE_LOG_LEVEL: Set the log level for file logs.

OTEL logs

• OTEL_LOG_EXPORTER_ENABLED (--otel-log-exporter-enabled): Enable exporting OTEL logs.
• OTEL_LOG_EXPORTER_LEVEL: Set the log level for OTEL logs.

OTEL traces

• OTEL_TRACE_EXPORTER_ENABLED (--otel-trace-exporter-enabled): Enable exporting OTEL traces.
• OTEL_TRACE_EXPORTER_LEVEL: Set the log level for OTEL traces.

Additional Configuration

You can configure the OTLP trace and log exports through the variables defined in the opentelemetry crates:

• OTEL_EXPORTER_OTLP_COMPRESSION (defaults to none, but can be set to gzip).
• OTEL_EXPORTER_OTLP_ENDPOINT (defaults to http://localhost:4317, with the grpc-tonic feature (default)).
• OTEL_EXPORTER_OTLP_TIMEOUT
• OTEL_EXPORTER_OTLP_HEADERS

See the defaults in the opentelemetry-otlp crate.

Tracing exporter overrides

OTLP Exporter settings:

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
• OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
• OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
• OTEL_EXPORTER_OTLP_TRACES_HEADERS

General Span and Trace settings:

• OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
• OTEL_SPAN_EVENT_COUNT_LIMIT
• OTEL_SPAN_LINK_COUNT_LIMIT
• OTEL_TRACES_SAMPLER (Defaults to parentbased_always_on. If “traceidratio” or “parentbased_traceidratio”, then OTEL_TRACES_SAMPLER_ARG)

Batch Span Processor settings:

• OTEL_BSP_MAX_QUEUE_SIZE
• OTEL_BSP_SCHEDULE_DELAY
• OTEL_BSP_MAX_EXPORT_BATCH_SIZE
• OTEL_BSP_EXPORT_TIMEOUT
• OTEL_BSP_MAX_CONCURRENT_EXPORTS

See defaults in the opentelemetry_sdk crate under trace::config and trace::span_processor.

Log exporter overrides

OTLP exporter settings:

• OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
• OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
• OTEL_EXPORTER_OTLP_LOGS_HEADERS

Batch Log Record Processor settings:

• OTEL_BLRP_MAX_QUEUE_SIZE
• OTEL_BLRP_SCHEDULE_DELAY
• OTEL_BLRP_MAX_EXPORT_BATCH_SIZE
• OTEL_BLRP_EXPORT_TIMEOUT

See defaults in the opentelemetry_sdk crate under log::log_processor.

Implementations

impl Tracing

pub const CONSOLE_LOG_LEVEL_ENV: &str = "CONSOLE_LOG_LEVEL"

The environment variable used to set the console log level filter.

pub const FILE_LOG_LEVEL_ENV: &str = "FILE_LOG_LEVEL"

The environment variable used to set the rolling file log level filter.

pub const FILE_LOG_SUFFIX: &str = "tracing-rs.json"

The filename used for the rolling file logs.

pub const OTEL_LOG_EXPORTER_LEVEL_ENV: &str = "OTEL_LOG_EXPORTER_LEVEL"

The environment variable used to set the OTEL log level filter.

pub const OTEL_TRACE_EXPORTER_LEVEL_ENV: &str = "OTEL_TRACE_EXPORTER_LEVEL"

The environment variable used to set the OTEL trace level filter.

pub fn builder() -> TracingBuilder<PreServiceName>

Creates and returns a TracingBuilder.

pub fn pre_configured( service_name: &'static str, options: TelemetryOptions, ) -> Self

Creates an returns a pre-configured Tracing instance which can be initialized by calling Tracing::init().

Also see this section in the docs for all full list of environment variables and CLI arguments used by the pre-configured instance.

Default Levels

• Console logs: INFO
• File logs: INFO
• OTEL logs: INFO
• OTEL traces: INFO

Default Values

• If rolling_logs_period is None, this function will use a default value of RotationPeriod::Never.

pub fn init(self) -> Result<Tracing, Error>

Initialize the configured tracing subscribers, returning a guard that will shutdown the subscribers when dropped.

Name the guard variable appropriately, do not just use let _ =, as that will drop immediately.

Trait Implementations

impl Drop for Tracing

fn drop(&mut self)

Executes the destructor for this type.