Struct TelemetryHandle 

pub struct TelemetryHandle { /* private fields */ }

Available on crate feature dial9 only.

Cheap, cloneable handle for controlling telemetry from anywhere.

A handle may be in one of two modes:

• Enabled — backed by a real telemetry session; methods record events, control recording, and wrap spawned futures with wake tracking.
• Disabled — an inert sentinel returned by TelemetryHandle::disabled and by TelemetryHandle::current when called from a thread that is not owned by a dial9 runtime. All methods are no-ops; spawn falls back to [tokio::spawn] without wake tracking.

Use is_enabled to distinguish the two modes.

Implementations

impl TelemetryHandle

pub fn disabled() -> TelemetryHandle

Return an inert handle that is not connected to any telemetry session. All methods are no-ops; spawn falls back to [tokio::spawn] without wake tracking.

pub fn is_enabled(&self) -> bool

Whether this handle is connected to a live telemetry session.

Returns false for handles obtained via TelemetryHandle::disabled, and for handles returned by TelemetryHandle::current when called from a thread that is not owned by a dial9 runtime.

pub fn current() -> TelemetryHandle

Return the TelemetryHandle for the current thread.

On threads owned by a dial9 runtime (workers and blocking threads — installed via the runtime’s on_thread_start hook, cleared on on_thread_stop) this returns the live handle for that runtime.

On any other thread (including the caller of runtime.block_on(...) on a current_thread runtime, threads outside any tokio context, and threads owned by a runtime built with telemetry disabled) this returns an inert handle whose methods are all no-ops — see TelemetryHandle::disabled.

Use is_enabled when you need to branch on whether telemetry is actually live on the current thread.

pub fn try_current() -> Option<TelemetryHandle>

Return the TelemetryHandle installed for the current thread, or None if no dial9 runtime has claimed this thread.

Prefer current instead.

pub fn enable(&self)

Enable telemetry recording. No-op on a disabled handle.

pub fn disable(&self)

Disable telemetry recording. No-op on a disabled handle.

pub fn spawn<F>(&self, future: F) -> JoinHandle<<F as Future>::Output>

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

Spawn a future on the ambient tokio runtime.

On an enabled handle, the future is wrapped with wake-event tracking. On a disabled handle, this is a passthrough to [tokio::spawn].

Panics

Panics if called from outside a tokio runtime context (same as [tokio::spawn]).

pub fn spawn_with<F, S>( &self, future: F, spawn_fn: impl FnOnce(TracedFuture<F>) -> S, ) -> S

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

Spawn an instrumented future through a user-supplied spawn function.

spawn_fn must synchronously perform a real Tokio spawn (or an equivalent operation) before returning; do not defer the future or run it with block_on. To record the resulting task as instrumented, spawn on a dial9-traced runtime with task tracking enabled. The closure’s return value is forwarded back to the caller, so you can keep the [tokio::task::JoinHandle], [tokio::task::AbortHandle], or whatever the spawn function returns.

Examples

Spawn into a [tokio::task::JoinSet]:

let handle = TelemetryHandle::current();
let mut set: JoinSet<()> = JoinSet::new();
handle.spawn_with(work(), |f| set.spawn(f));

Spawn into a [tokio::task::JoinSet] on a specific runtime:

let handle = TelemetryHandle::current();
let mut set: JoinSet<()> = JoinSet::new();
handle.spawn_with(work(), |f| set.spawn_on(f, runtime.handle()));

Trait Implementations

impl Clone for TelemetryHandle

fn clone(&self) -> TelemetryHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TelemetryHandle

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

Formats the value using the given formatter.