get_usage_metadata_callback() — langchain Function Reference

Architecture documentation for the get_usage_metadata_callback() function in usage.py from the langchain codebase.

Function python Observability CallbackManager

Entity Profile

Observability→ CallbackManager→ get_usage_metadata_callback() — langchain Function Reference

Dependency Diagram

graph TD
  156d1099_9009_986f_9932_b62a09521c5e["get_usage_metadata_callback()"]
  6ccf6f55_5d54_3232_1de5_34ece235aaf1["usage.py"]
  156d1099_9009_986f_9932_b62a09521c5e -->|defined in| 6ccf6f55_5d54_3232_1de5_34ece235aaf1
  style 156d1099_9009_986f_9932_b62a09521c5e fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/core/langchain_core/callbacks/usage.py lines 93–149

def get_usage_metadata_callback(
    name: str = "usage_metadata_callback",
) -> Generator[UsageMetadataCallbackHandler, None, None]:
    """Get usage metadata callback.

    Get context manager for tracking usage metadata across chat model calls using
    [`AIMessage.usage_metadata`][langchain.messages.AIMessage.usage_metadata].

    Args:
        name: The name of the context variable.

    Yields:
        The usage metadata callback.

    Example:
        ```python
        from langchain.chat_models import init_chat_model
        from langchain_core.callbacks import get_usage_metadata_callback

        llm_1 = init_chat_model(model="openai:gpt-4o-mini")
        llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-20241022")

        with get_usage_metadata_callback() as cb:
            llm_1.invoke("Hello")
            llm_2.invoke("Hello")
            print(cb.usage_metadata)
        ```

        ```txt
        {
            "gpt-4o-mini-2024-07-18": {
                "input_tokens": 8,
                "output_tokens": 10,
                "total_tokens": 18,
                "input_token_details": {"audio": 0, "cache_read": 0},
                "output_token_details": {"audio": 0, "reasoning": 0},
            },
            "claude-3-5-haiku-20241022": {
                "input_tokens": 8,
                "output_tokens": 21,
                "total_tokens": 29,
                "input_token_details": {"cache_read": 0, "cache_creation": 0},
            },
        }
        ```

    !!! version-added "Added in `langchain-core` 0.3.49"

    """
    usage_metadata_callback_var: ContextVar[UsageMetadataCallbackHandler | None] = (
        ContextVar(name, default=None)
    )
    register_configure_hook(usage_metadata_callback_var, inheritable=True)
    cb = UsageMetadataCallbackHandler()
    usage_metadata_callback_var.set(cb)
    yield cb
    usage_metadata_callback_var.set(None)