Struct Dial9Handle 

pub struct Dial9Handle { /* private fields */ }

Available on crate feature dial9 only.

Cheap, cloneable handle for recording events and controlling telemetry.

A handle may be in one of two modes:

• Enabled — backed by a live recorder; methods record events and control recording.
• Disabled — an inert sentinel returned by Dial9Handle::disabled, and by Dial9Handle::current when neither the calling thread nor the process has a handle installed. All methods are no-ops.

Use is_enabled to distinguish the two modes.

Implementations

impl Dial9Handle

pub fn disabled() -> Dial9Handle

Return an inert handle that is not connected to any recorder. All methods are no-ops.

pub fn is_enabled(&self) -> bool

Whether recording through this handle currently does anything: the handle is connected to a live recorder AND recording is enabled (not paused via disable).

Returns false for handles obtained via Dial9Handle::disabled, for any handle Dial9Handle::current could not resolve, and while a connected recorder is paused.

Check this before doing per-event work that would be wasted while recording is off, such as work leading up to with_encoder. The check can race a concurrent enable/disable, which is benign since the event either lands or is skipped anyway.

To ask only whether the handle is connected at all, regardless of pause state, use is_connected.

pub fn dump_trigger(&self) -> Option<DumpTrigger>

Available on crate feature pipeline only.

On-demand dump trigger for this runtime’s recorder.

Returns None on a disabled handle (see disabled) and when the runtime was built without a dump trigger (with_dump_trigger). The returned DumpTrigger is cheap to clone and every clone shares the configured debounce gate.

pub fn current() -> Dial9Handle

Return the Dial9Handle to record through, resolved in order:

1. The handle installed on this thread with set_tl_handle, which runtime integrations do for the threads they own.
2. The process-global handle, if Recorder::install_global_handle has been called.
3. An inert disabled handle, where recording is a no-op.

Use is_enabled to branch on whether telemetry is live here.

pub fn try_current_thread() -> Option<Dial9Handle>

Return the Dial9Handle installed on this thread with set_tl_handle, or None if there is none.

Unlike current, never falls back to the process-global handle. To record an event, use current.

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 track_current_thread(&self) -> Result<ThreadTrackingGuard, Error>

Profile the calling thread.

Per-thread sources, such as the scheduler-event profiler, only sample threads that opt in. Tokio workers opt in on their own, call this from any other thread you want profiled. Profiling lasts until the returned guard drops.

Returns an error if a source could not start on this thread. No-op on a disabled handle.

use dial9_core::buffer::MemoryBuffer;
use dial9_core::recorder::recorder;

let rec = recorder(MemoryBuffer::new(1 << 20)?).build();
let handle = rec.handle().clone();

std::thread::spawn(move || -> std::io::Result<()> {
    let _tracking = handle.track_current_thread()?;
    // work here is sampled by the recorder's per-thread sources
    Ok(())
});

pub fn is_connected(&self) -> bool

Whether this handle is wired to a recorder at all, regardless of whether recording is currently paused.

is_enabled answers the narrower question of whether a record right now would land.

pub fn is_stopped(&self) -> bool

Whether the recorder behind this handle has shut down.

Terminal: a stopped recorder never records again. Returns false for a handle that is merely paused (see disable) and for a disabled handle, neither of which is stopped.

pub fn with_source<T, R>(&self, f: impl FnOnce(&mut T) -> R) -> Option<R>

where T: Source,

Run f against this recorder’s source of type T.

None when the handle is disabled, no T is registered, or the source lock is poisoned.

pub fn with_source_or_insert<T, R>( &self, make: impl FnOnce() -> T, f: impl FnOnce(&mut T) -> R, ) -> Option<R>

where T: Source,

Run f against this recorder’s source of type T, registering the one make builds if there is not one yet.

None when the handle is disabled, the recorder has shut down, or the source lock is poisoned.

pub fn record_event(&self, event: impl Encodable)

Record a custom event into the trace.

Any type implementing dial9_trace_format::TraceEvent (typically via #[derive(TraceEvent)]) works directly. No-op on a disabled handle or when recording is paused.

pub fn record_event_with<E>(&self, make: impl FnOnce() -> E)

where E: Encodable,

Record an event that is only built when recording is on.

Reach for this over record_event when building the event costs something you would rather not pay while recording is paused, such as a clock read or a lookup. make runs only if the event will be recorded.

Trait Implementations

impl Clone for Dial9Handle

fn clone(&self) -> Dial9Handle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Dial9Handle

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

Formats the value using the given formatter.

impl Dial9HandleTokioExt for Dial9Handle

fn attach_tokio_runtime( &self, builder: Builder, options: TokioAttachOptions, ) -> Result<Runtime, Error>

Instrument a builder you configured, build it, and return the runtime.