Crate tracing_kickstart 

tracing-kickstart

Rust module used to bootstrap tracing and reduce code duplication across projects.

Intended for personal use only.

Example

This example loads the TracingConfig from a .env file by deserializing through a nested config struct.

Example .env file:

APP__TRACE__LOG_FILE_PATH="/tmp/tracing-kickstart-example.log"
APP__TRACE__COLLECTOR_URL="https://otel.example.com:4318"
APP__TRACE__COLLECTOR_AUTH_HEADER="Basic aHVudGVyMg=="
APP__TRACE__ANSI_OUTPUT=true

Implementation example

use config::{Config, Environment};
use dotenvy::dotenv;
use serde::Deserialize;
use tracing_kickstart::{TracingConfig, TracingConfigOverride};

#[derive(Debug, Clone, Deserialize)]
pub struct Conf {
    // pulled in automatically from env vars
    trace: TracingConfigOverride,
}

fn main() {
    // load config
    dotenv().ok(); // load vars from .env file
    let settings = Config::builder()
        .add_source(Environment::with_prefix("APP").separator("__").try_parsing(true))
        .build()
        .unwrap();
    let conf = settings.try_deserialize::<Conf>().unwrap(); // deserialize into Conf struct

    // collect attributes for this crate
    let attrs = tracing_kickstart::build_attrs!();
    attrs.dump(); // log attributes to stdout

    // set an optional env filter to replace the default set by tracing_kickstart: `info,{crate}=debug`
    // if set, this will override any filters set using `RUST_LOG`, but can be completely rewritten at runtime
    // using the `TracingConfigOverride::filter` var.
    //
    // or, to retain this base filter but make adjustments at runtime, use `TracingConfigOverride::filter` to
    // avoid having to copy and paste your base filter into your env vars / .env file.
    let custom_base_filter = Some(format!("info,{}=trace", attrs.crate_name)); // default: `info,{crate}=debug`

    // optionally add custom resource attributes
    let custom_resource_attrs = Some(vec![("region".into(), "canada".into())]);

    // add your 'base' configuration here. Most options can be overriden once again at runtime
    // via `TracingConfigOverride`, which is the type of the required parameter passed in
    //
    // the call to `build()` will ensure that any present override values are applied
    let tracing_config = TracingConfig::builder(&conf.trace)
        .filter(custom_base_filter) // optionally add a base filter
        .ansi_output(true)
        .ansi_sanitization(false) // retain ansi escape codes in `tracing` output
                                  // (NOTE: do not disable if logs contain untrusted content)
        .custom_resource_attrs(custom_resource_attrs) // (NOTE: cannot be set with .env override)
        .build();

    // to experiment with the override resolution, you can print the tracing config to view the output
    println!("Resolved tracing config:\n{tracing_config:#?}");

    // init tracing, receive a handle for the tracing providers
    let tracing_providers = tracing_kickstart::init(attrs, tracing_config).unwrap();
    tracing_providers.register_globally(); // optionally register all configured providers globally
    tracing::info!("Tracing initialized");

    // graceful shutdown of various tracing providers (logs, metrics, traces) using the provided handle
    tracing::debug!("Shutting down tracing providers: {tracing_providers:?}");
    tracing_providers.shutdown();
}

Feature flags

Default: none

tokio_console - Enables tokio’s console feature

• Pulls console-subscriber into dependency tree and handles required env filter updates

detector_hostresource - enables the HostResourceDetector

• Added attributes: host.id, host.arch

detector_os - enables the OsResourceDetector

• Added attributes: os_type

detector_process

• Enables the ProcessResourceDetector
• Added attributes: process.command_args, process.pid, process.runtime.version, process.runtime.name, process.runtime.description

detector_telemetry - enables the TelemetryResourceDetector

• Added attributes: telemetry.sdk.name, telemetry.sdk.language, telemetry.sdk.version

attrs_crate_name

• Adds an additional attribute (service.crate_name) for the crate name.
• This will only differ from service_name for crates/packages which contain hyphen’s in their package name.
• E.g. for this library:
  • service.name: tracing-kickstart
  • service.crate_name: tracing_kickstart

attrs_origin

• Adds attributes for info regarding the tracing-kickstart package, e.g. the version, crate name, etc

attrs_version_expanded

• Adds attributes for each version part: service.version.major, service.version.minor, service.version.patch

exponential_histograms

• Adds support for exporting exponential histograms
  • Exponential histograms can be collected and exported to prometheus native histograms

otel_span_attributes

• Enables the opentelemetry-appender-tracing
  • Exponential histograms can be collected and exported to prometheus native histograms

Re-exports

pub use opentelemetry;

pub use opentelemetry_otlp;

pub use opentelemetry_resource_detectors;detector_hostresource or detector_os or detector_process

pub use opentelemetry_sdk;

pub use opentelemetry_semantic_conventions;

pub use opentelemetry as otel;

pub use opentelemetry_otlp as otel_otlp;

pub use opentelemetry_resource_detectors as otel_resource_detectors;detector_hostresource or detector_os or detector_process

pub use opentelemetry_sdk as otel_sdk;

pub use opentelemetry_semantic_conventions as otel_semantic_conventions;

pub use opentelemetry_appender_tracing;

pub use tracing_opentelemetry;

pub use tracing_subscriber;

pub use opentelemetry_appender_tracing as otel_appender_tracing;

pub use tracing_opentelemetry as tracing_otel;

Macros

build_attrs

Generates service attributes using env! calls.

Structs

ServiceAttributeStore

Compile-time attributes to be provided by the owning application/service.

TraceProviders

TracingConfig

TracingConfigBuilder

TracingConfigOverride

Runtime overrides for config

TracingOtelConfig

Enums

ExporterBuildError

Errors that can occur while building an exporter.

Functions

init

Initialize tracing