Struct UsageMetadataCallbackHandler 

pub struct UsageMetadataCallbackHandler { /* private fields */ }

Callback Handler that tracks AIMessage.usage_metadata.

This handler collects token usage metadata from chat model responses, aggregating the usage by model name. It is thread-safe and can be used across multiple concurrent LLM calls.

Example

use agent_chain_core::callbacks::UsageMetadataCallbackHandler;
use std::sync::Arc;

let handler = UsageMetadataCallbackHandler::new();

// Use with a callback manager
let mut manager = CallbackManager::new();
manager.add_handler(Arc::new(handler.clone()), true);

// After LLM calls complete
let usage = handler.usage_metadata();
for (model, metadata) in usage.iter() {
    println!("{}: {} tokens", model, metadata.total_tokens);
}

Implementations

impl UsageMetadataCallbackHandler

pub fn new() -> Self

Create a new UsageMetadataCallbackHandler.

pub fn usage_metadata(&self) -> HashMap<String, UsageMetadata>

Get the collected usage metadata.

Returns a clone of the current usage metadata map, keyed by model name.

Trait Implementations

impl BaseCallbackHandler for UsageMetadataCallbackHandler

fn name(&self) -> &str

Get a unique name for this handler. Note: This is a Rust-specific addition for debugging purposes.

fn raise_error(&self) -> bool

Whether to raise an error if an exception occurs.

fn run_inline(&self) -> bool

Whether to run the callback inline.

fn ignore_llm(&self) -> bool

Whether to ignore LLM callbacks.

fn ignore_retry(&self) -> bool

Whether to ignore retry callbacks.

fn ignore_chain(&self) -> bool

Whether to ignore chain callbacks.

fn ignore_agent(&self) -> bool

Whether to ignore agent callbacks.

fn ignore_retriever(&self) -> bool

Whether to ignore retriever callbacks.

fn ignore_chat_model(&self) -> bool

Whether to ignore chat model callbacks.

fn ignore_custom_event(&self) -> bool

Whether to ignore custom events.

impl CallbackManagerMixin for UsageMetadataCallbackHandler

fn on_llm_start( &mut self, serialized: &HashMap<String, Value>, prompts: &[String], run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when LLM starts running.

fn on_chat_model_start( &mut self, serialized: &HashMap<String, Value>, messages: &[Vec<BaseMessage>], run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when a chat model starts running.

fn on_retriever_start( &mut self, serialized: &HashMap<String, Value>, query: &str, run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when the Retriever starts running.

fn on_chain_start( &mut self, serialized: &HashMap<String, Value>, inputs: &HashMap<String, Value>, run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Run when a chain starts running.

fn on_tool_start( &mut self, serialized: &HashMap<String, Value>, input_str: &str, run_id: Uuid, parent_run_id: Option<Uuid>, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, inputs: Option<&HashMap<String, Value>>, )

Run when the tool starts running.

impl ChainManagerMixin for UsageMetadataCallbackHandler

fn on_chain_end( &mut self, outputs: &HashMap<String, Value>, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when chain ends running.

fn on_chain_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when chain errors.

fn on_agent_action( &mut self, action: &Value, run_id: Uuid, parent_run_id: Option<Uuid>, color: Option<&str>, )

Run on agent action.

fn on_agent_finish( &mut self, finish: &Value, run_id: Uuid, parent_run_id: Option<Uuid>, color: Option<&str>, )

Run on the agent end.

impl Clone for UsageMetadataCallbackHandler

fn clone(&self) -> UsageMetadataCallbackHandler

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UsageMetadataCallbackHandler

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

Formats the value using the given formatter.

impl Default for UsageMetadataCallbackHandler

fn default() -> Self

Returns the “default value” for a type.

impl Display for UsageMetadataCallbackHandler

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

Formats the value using the given formatter.

impl LLMManagerMixin for UsageMetadataCallbackHandler

fn on_llm_end( &mut self, response: &ChatResult, _run_id: Uuid, _parent_run_id: Option<Uuid>, )

Run when LLM ends running.

fn on_llm_new_token( &mut self, token: &str, run_id: Uuid, parent_run_id: Option<Uuid>, chunk: Option<&Value>, )

Run on new output token. Only available when streaming is enabled.

fn on_llm_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when LLM errors.

impl RetrieverManagerMixin for UsageMetadataCallbackHandler

fn on_retriever_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when Retriever errors.

fn on_retriever_end( &mut self, documents: &[Value], run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when Retriever ends running.

impl RunManagerMixin for UsageMetadataCallbackHandler

fn on_text( &mut self, text: &str, run_id: Uuid, parent_run_id: Option<Uuid>, color: Option<&str>, end: &str, )

Run on an arbitrary text.

fn on_retry( &mut self, retry_state: &dyn Any, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run on a retry event.

fn on_custom_event( &mut self, name: &str, data: &dyn Any, run_id: Uuid, tags: Option<&[String]>, metadata: Option<&HashMap<String, Value>>, )

Override to define a handler for a custom event.

impl ToolManagerMixin for UsageMetadataCallbackHandler

fn on_tool_end( &mut self, output: &str, run_id: Uuid, parent_run_id: Option<Uuid>, color: Option<&str>, observation_prefix: Option<&str>, llm_prefix: Option<&str>, )

Run when the tool ends running.

fn on_tool_error( &mut self, error: &dyn Error, run_id: Uuid, parent_run_id: Option<Uuid>, )

Run when tool errors.