Struct TracedRuntime 

pub struct TracedRuntime { /* private fields */ }

Available on crate feature dial9 only.

A tokio runtime paired with its (optional) dial9 telemetry guard.

The guard, when present, must outlive the runtime so traces are flushed on drop — keeping both inside one struct enforces that ordering at the type level (fields drop top-to-bottom, so runtime drops before guard).

Construct one of two ways:

• High-level: from a crate::Dial9Config via TracedRuntime::new (panicking, used by the #[dial9_tokio_telemetry::main] macro) or TracedRuntime::try_new (fallible).
• Low-level: via TracedRuntime::builder → TracedRuntimeBuilder::build_and_start for direct control over the raw [tokio::runtime::Builder] and crate::telemetry::TraceWriter. This is the path used by example code, benchmarks, and integration tests that want to wire a crate::telemetry::NullWriter or other custom writer.

Implementations

impl TracedRuntime

pub fn builder() -> TracedRuntimeBuilder

Create a new TracedRuntimeBuilder.

pub fn build_disabled( builder: Builder, ) -> Result<(Runtime, TelemetryGuard), Error>

Build a plain runtime with no telemetry installed.

The returned TelemetryGuard is in its disabled mode — see TelemetryGuard::is_enabled.

pub fn build( builder: Builder, writer: impl TraceWriter + 'static, ) -> Result<(Runtime, TelemetryGuard), Error>

Build the traced runtime. Recording starts disabled.

pub fn build_and_start( builder: Builder, writer: impl TraceWriter + 'static, ) -> Result<(Runtime, TelemetryGuard), Error>

Build the traced runtime and immediately enable recording.

impl TracedRuntime

pub fn new<C>(config: C) -> TracedRuntime

where C: TryInto<TracedRuntime>, <C as TryInto<TracedRuntime>>::Error: Display,

Build a TracedRuntime from a config, panicking with the underlying error on failure. Used by the #[dial9_tokio_telemetry::main] macro.

Reach for this directly when the macro doesn’t fit — e.g. when an application owns multiple tokio runtimes, when you need to control runtime lifetime explicitly, or when you want to drive TelemetryGuard::graceful_shutdown before the runtime drops.

Generic over any input that converts into a TracedRuntime: in practice that means either the fluent crate::Dial9Config (returned by Dial9Config::builder) or the deprecated positional crate::config::Dial9Config. The generic shape is what keeps the macro source-compatible across these input types.

Panics

Panics if the underlying conversion fails — i.e. if the tokio runtime cannot be built or the telemetry background worker fails to start. When constructing from the fluent crate::Dial9Config, writer-transport I/O has already been validated by Dial9ConfigBuilder::build, so the only remaining failure modes are tokio-builder and telemetry-core startup I/O.

For fallible construction, use try_new.

use dial9_tokio_telemetry::{Dial9Config, TracedRuntime};
let cfg = Dial9Config::builder()
    .base_path("trace.bin")
    .max_file_size(64 * 1024 * 1024)
    .max_total_size(1024 * 1024 * 1024)
    .build()?;
let rt = TracedRuntime::new(cfg);
rt.block_on(async { /* ... */ });

pub fn try_new<C>( config: C, ) -> Result<TracedRuntime, <C as TryInto<TracedRuntime>>::Error>

where C: TryInto<TracedRuntime>,

Fallible counterpart to new.

Returns the conversion error directly: when constructing from crate::Dial9Config that’s a TelemetryRuntimeError; when constructing from the deprecated crate::config::Dial9Config it’s a std::io::Error. Use this when you want to handle runtime construction failure rather than panic.

use dial9_tokio_telemetry::{Dial9Config, TracedRuntime};
let cfg = Dial9Config::builder()
    .base_path("trace.bin")
    .max_file_size(64 * 1024 * 1024)
    .max_total_size(1024 * 1024 * 1024)
    .build()?;
let rt = TracedRuntime::try_new(cfg)?;
rt.block_on(async { /* ... */ });

pub fn runtime(&self) -> &Runtime

Borrow the underlying tokio runtime.

pub fn guard(&self) -> &TelemetryGuard

Borrow the telemetry guard.

The guard is always present, regardless of whether telemetry was installed. Use TelemetryGuard::is_enabled to distinguish a live telemetry session from an inert (disabled) guard.

pub fn block_on<F>(&self, fut: F) -> <F as Future>::Output

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

Run fut to completion on the runtime.

The future is always spawned through the guard’s TelemetryHandle. On an enabled guard this records poll and wake events; on a disabled guard the handle’s spawn falls through to plain [tokio::spawn].

Trait Implementations

impl Debug for TracedRuntime

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

Formats the value using the given formatter.

impl TryFrom<Dial9Config> for TracedRuntime

type Error = TelemetryRuntimeError

The type returned in the event of a conversion error.

fn try_from( config: Dial9Config, ) -> Result<TracedRuntime, <TracedRuntime as TryFrom<Dial9Config>>::Error>

Performs the conversion.

impl TryFrom<Dial9Config> for TracedRuntime

Bridge for the deprecated positional config API at crate::config::Dial9Config so that it remains compatible with TracedRuntime::new (and therefore the #[dial9_tokio_telemetry::main] macro).

type Error = Error

The type returned in the event of a conversion error.

fn try_from( config: Dial9Config, ) -> Result<TracedRuntime, <TracedRuntime as TryFrom<Dial9Config>>::Error>

Performs the conversion.