Struct OffsetTime

pub struct OffsetTime<F> { /* private fields */ }

Available on crate features fmt and std and time only.

Formats the current time using a fixed offset and a formatter from the time crate.

This is typically used as an alternative to LocalTime. LocalTime determines the offset every time it formats a message, which may be unsound or fail. With OffsetTime, the offset is determined once. This makes it possible to do so while the program is still single-threaded and handle any errors. However, this also means the offset cannot change while the program is running (the offset will not change across DST changes).

Implementations

impl OffsetTime<Rfc3339>

pub fn local_rfc_3339() -> Result<Self, IndeterminateOffset>

Returns a formatter that formats the current time using the local time offset in the RFC 3339 format (a subset of the ISO 8601 timestamp format).

Returns an error if the local time offset cannot be determined. This typically occurs in multithreaded programs. To avoid this problem, initialize OffsetTime before forking threads. When using Tokio, this means initializing OffsetTime before the Tokio runtime.

Examples

use tracing_subscriber::fmt::{self, time};

let subscriber = tracing_subscriber::fmt()
    .with_timer(time::OffsetTime::local_rfc_3339().expect("could not get local offset!"));

Using OffsetTime with Tokio:

use tracing_subscriber::fmt::time::OffsetTime;

#[tokio::main]
async fn run() {
    tracing::info!("runtime initialized");

    // At this point the Tokio runtime is initialized, and we can use both Tokio and Tracing
    // normally.
}

fn main() {
    // Because we need to get the local offset before Tokio spawns any threads, our `main`
    // function cannot use `tokio::main`.
    tracing_subscriber::fmt()
        .with_timer(OffsetTime::local_rfc_3339().expect("could not get local time offset"))
        .init();

    // Even though `run` is written as an `async fn`, because we used `tokio::main` on it
    // we can call it as a synchronous function.
    run();
}

impl<F: Formattable> OffsetTime<F>

pub fn new(offset: UtcOffset, format: F) -> Self

Returns a formatter that formats the current time using the time crate with the provided provided format and timezone offset. The format may be any type that implements the Formattable trait.

Typically, the offset will be the local offset, and format will be a format description string, or one of the time crate’s well-known formats.

If the format description is statically known, then the format_description! macro should be used. This is identical to the time::format_description::parse method, but runs at compile-time, throwing an error if the format description is invalid. If the desired format is not known statically (e.g., a user is providing a format string), then the time::format_description::parse method should be used. Note that this method is fallible.

See the time book for details on the format description syntax.

Examples

Using the format_description! macro:

use tracing_subscriber::fmt::{self, time::OffsetTime};
use time::macros::format_description;
use time::UtcOffset;

let offset = UtcOffset::current_local_offset().expect("should get local offset!");
let timer = OffsetTime::new(offset, format_description!("[hour]:[minute]:[second]"));
let subscriber = tracing_subscriber::fmt()
    .with_timer(timer);

Using time::format_description::parse:

use tracing_subscriber::fmt::{self, time::OffsetTime};
use time::UtcOffset;

let offset = UtcOffset::current_local_offset().expect("should get local offset!");
let time_format = time::format_description::parse("[hour]:[minute]:[second]")
    .expect("format string should be valid!");
let timer = OffsetTime::new(offset, time_format);
let subscriber = tracing_subscriber::fmt()
    .with_timer(timer);

Using the format_description! macro requires enabling the time crate’s “macros” feature flag.

Using a well-known format (this is equivalent to OffsetTime::local_rfc_3339):

use tracing_subscriber::fmt::{self, time::OffsetTime};
use time::UtcOffset;

let offset = UtcOffset::current_local_offset().expect("should get local offset!");
let timer = OffsetTime::new(offset, time::format_description::well_known::Rfc3339);
let subscriber = tracing_subscriber::fmt()
    .with_timer(timer);

Trait Implementations

impl<F: Clone> Clone for OffsetTime<F>

fn clone(&self) -> OffsetTime<F>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug> Debug for OffsetTime<F>

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

Formats the value using the given formatter.

impl<F> FormatTime for OffsetTime<F>

where F: Formattable,

fn format_time(&self, w: &mut Writer<'_>) -> Result

Measure and write out the current time.