Crate logfire

Expand description

§Rust SDK for Pydantic Logfire

This goal of this SDK is to provide a first-class experience instrumenting Rust code for the Pydantic Logfire platform.

The most important API is logfire::configure(), which is used to set up integrations with tracing and log, as well as exporters for opentelemetry. Code instrumented using tracing and log will just work once this configuration is in place.

This SDK also offers opinionated functions to instrument code following Logfire’s design principles:

logfire::info!(), logfire::debug!() and similar macros to log messages with structured data.
logfire::span!() to create a span with structured data.
logfire::u64_counter() and similar functions to create metrics.

§Getting Started

To use Logfire in your Rust project, add the following to your Cargo.toml:

[dependencies]
logfire = "0.5.0"

Then, in your Rust code, add a call to logfire::configure() at the beginning of your program:

//! A basic example of using Logfire to instrument Rust code.

use std::sync::LazyLock;

use opentelemetry::{KeyValue, metrics::Counter};

static BASIC_COUNTER: LazyLock<Counter<u64>> = LazyLock::new(|| {
    logfire::u64_counter("basic_counter")
        .with_description("Just an example")
        .with_unit("s")
        .build()
});

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let shutdown_handler = logfire::configure()
        .install_panic_handler()
        .with_console(None)
        .finish()?;

    logfire::info!("Hello, world!");

    {
        let _span = logfire::span!("Asking the user their {question}", question = "age").entered();

        println!("When were you born [YYYY-mm-dd]?");
        let mut dob = String::new();
        std::io::stdin().read_line(&mut dob)?;

        logfire::debug!("dob={dob}", dob = dob.trim().to_owned());
    }

    BASIC_COUNTER.add(1, &[KeyValue::new("process", "abc123")]);

    shutdown_handler.shutdown()?;
    Ok(())
}

§Configuration

After adding basic setup as per above, the most two important environment variables are:

LOGFIRE_TOKEN - (required) the token to send data to the Logfire platform
RUST_LOG - (optional) the level of verbosity to send to the Logfire platform. By default logs are captured at TRACE level so that all data is available for you to analyze in the Logfire platform.

All environment variables supported by the Rust Opentelemetry SDK are also supported by the Logfire SDK.

§Integrations

The following sections describe briefly the interaction which this SDK has with other libraries.

§With `tracing`

This SDK is built upon tracing (and tracing-opentelemtry) for the span! macro. This means that any code instrumented with tracing will automatically be captured by Logfire, and also that span! produces a tracing::Span which is fully compatible with the tracing ecosystem.

If you are an existing tracing user, it is fine to continue to use the tracing APIs directly and ignore logfire::span!. The upside of span! is that it will show the fields directly in the logfire UI.

There are many great APIs in tracing which we do not yet provide equivalents for, such as the #[tracing::instrument] proc macro, so even if using logfire::span! you will likely use tracing APIs directly too.

§With `opentelemetry`

This SDK is built upon the opentelemetry Rust SDK and will configure the global opentelemetry state as part of a call to logfire::configure().

All calls to logfire::info! and similar macros are directly forwarded to opentelemetry machinery without going through tracing, for performance.

The metrics helpers exported by this SDK, such as logfire::u64_counter(), are very thin wrappers around the opentelemetry SDK.

§With `log`

This SDK configures the global log state to use an exporter which forwards logs to opentelemetry.

All code instrumented with log will therefore automatically be captured by Logfire.

Modules§

config: Configuration options for the Logfire SDK.
exporters: Helper functions to configure mo

Macros§

debug: Emit a log at the DEBUG level.
error: Emit a log at the ERROR level.
info: Emit a log at the INFO level.
log: Export a log message at the specified level.
span: Create a new Span. This macro is a simplified version of tracing::span! which accepts a smaller set of possible arguments and syntaxes.
warn: Emit a log at the WARN level.

Structs§

LogfireConfigBuilder: Builder for logfire configuration, returned from logfire::configure().
ShutdownHandler: A handler to shutdown the Logfire configuration.

Enums§

ConfigureError: An error which may arise when configuring Logfire.

Functions§

configure: Main entry point to configure logfire.
f64_counter: Wrapper for Meter::f64_counter using logfire’s global meter.
f64_gauge: Wrapper for Meter::f64_gauge using logfire’s global meter.
f64_histogram: Wrapper for Meter::f64_histogram using logfire’s global meter.
f64_observable_counter: Wrapper for Meter::f64_observable_counter using logfire’s global meter.
f64_observable_gauge: Wrapper for Meter::f64_observable_gauge using logfire’s global meter.
f64_observable_up_down_counter: Wrapper for Meter::f64_observable_up_down_counter using logfire’s global meter.
f64_up_down_counter: Wrapper for Meter::f64_up_down_counter using logfire’s global meter.
i64_gauge: Wrapper for Meter::i64_gauge using logfire’s global meter.
i64_observable_gauge: Wrapper for Meter::i64_observable_gauge using logfire’s global meter.
i64_observable_up_down_counter: Wrapper for Meter::i64_observable_up_down_counter using logfire’s global meter.
i64_up_down_counter: Wrapper for Meter::i64_up_down_counter using logfire’s global meter.
u64_counter: Wrapper for Meter::u64_counter using logfire’s global meter.
u64_gauge: Wrapper for Meter::u64_gauge using logfire’s global meter.
u64_histogram: Wrapper for Meter::u64_histogram using logfire’s global meter.
u64_observable_counter: Wrapper for Meter::u64_observable_counter using logfire’s global meter.
u64_observable_gauge: Wrapper for Meter::u64_observable_gauge using logfire’s global meter.

Crate logfireCopy item path