Struct AsyncTraceDispatcher 

pub struct AsyncTraceDispatcher { /* private fields */ }

Asynchronous trace dispatcher for RocketMQ message tracing.

Collects trace contexts from producers and consumers, batches them according to configured thresholds, and asynchronously sends them to a trace topic. The dispatcher uses a bounded channel for non-blocking appends and spawns background tasks for batch processing.

Trace contexts are grouped by topic before being encoded and sent. Messages exceeding the configured size limit are split into multiple trace messages.

Implementation

Uses a tokio::mpsc::channel with a capacity of 2048 for queuing trace contexts and flush commands. A single worker task periodically flushes batches based on count, time thresholds, or explicit flush requests. The worker is submitted through the client runtime helper, which uses the explicitly injected client runtime.

Discard Policy

When the internal queue is full, new trace contexts are discarded and the discard counter is incremented. This prevents blocking the caller.

Implementations

impl AsyncTraceDispatcher

pub fn new( client_runtime: Arc<ClientRuntime>, group: &str, type_: Type, batch_num: usize, trace_topic_name: &str, rpc_hook: Option<Arc<dyn RPCHook>>, ) -> Self

Creates a new async trace dispatcher.

The dispatcher is created in a stopped state and must be started via start before it can process trace contexts.

Arguments

• group - Producer or consumer group name used for trace producer identification
• type_ - Trace type, either Type::Produce or Type::Consume
• batch_num - Maximum number of contexts per batch (capped at 20)
• trace_topic_name - Destination topic for trace messages (uses system default if empty)
• rpc_hook - Optional RPC hook applied to the internal trace producer

pub fn get_discard_count(&self) -> u64

Returns the number of trace contexts discarded due to queue overflow.

pub fn queue_size(&self) -> usize

Returns the approximate number of trace contexts queued for the worker.

pub fn is_started(&self) -> bool

Returns whether the dispatcher has been started.

pub fn is_stopped(&self) -> bool

Returns whether the dispatcher has been stopped.

pub fn batch_num(&self) -> usize

Returns the configured maximum number of trace contexts per batch.

pub fn set_client_host(&self, client_host: Option<CheetahString>)

Sets the resolved client identifier used to enrich generated trace records.

pub fn set_namespace_v2(&self, namespace_v2: Option<CheetahString>)

Sets the namespace v2 configuration for the dispatcher.

pub fn set_use_tls(&self, use_tls: bool)

Sets whether the internal trace producer should use TLS.

pub fn is_use_tls(&self) -> bool

pub fn get_trace_producer(&self) -> Option<Arc<Mutex<DefaultMQProducer>>>

Returns a reference to the internal trace producer.

The producer is available only after the dispatcher has been started.

pub fn trace_topic_name(&self) -> &str

pub async fn flush_async(&self) -> ClientResult<()>

Asynchronously flushes pending trace contexts without blocking a Tokio worker thread.

pub async fn shutdown_async(&self)

Asynchronously shuts down the dispatcher without blocking the current Tokio worker.

Concurrent callers await the same shutdown sequence, so pending traces are flushed and the worker is joined at most once.

pub fn register_shutdown_hook(&self)

pub fn register_shut_down_hook(&self)

pub fn remove_shutdown_hook(&self)

Trait Implementations

impl Drop for AsyncTraceDispatcher

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl TraceDispatcher for AsyncTraceDispatcher

fn start( &self, name_srv_addr: &str, access_channel: AccessChannel, ) -> ClientResult<()>

Starts the trace dispatcher and its background worker task.

Initializes the internal trace producer, spawns the worker task for batch processing, and marks the dispatcher as started. This method can be called only once; subsequent calls are ignored.

Errors

Returns an error if the dispatcher has already been started or if internal state initialization fails.

fn append(&self, ctx: &dyn Any) -> bool

Appends a trace context to the dispatcher queue.

This method does not block the calling thread. If the internal queue is full, the trace context is discarded and the discard counter is incremented.

Arguments

• ctx - Trace context, must be a TraceContext instance

Returns

Returns true if the context was successfully queued, false if it was discarded due to queue overflow or type mismatch.

fn flush(&self) -> ClientResult<()>

Flushes pending trace contexts by requesting an acknowledgement from the worker task.

Blocks the calling thread until the worker processes the flush command or the flush timeout elapses.

Errors

Returns an error if the dispatcher has not been started.

fn shutdown(&self)

Shuts down the dispatcher and stops the background worker task.

Attempts to flush remaining trace contexts before stopping. This method blocks briefly to allow pending data to be processed. The dispatcher cannot be restarted after shutdown.

fn as_any(&self) -> &dyn Any

Returns a reference to this dispatcher as an Any trait object.

fn as_mut_any(&mut self) -> &mut dyn Any

Returns a mutable reference to this dispatcher as an Any trait object.

fn trace_topic_name(&self) -> Option<&str>

fn trace_client_host(&self) -> Option<CheetahString>