Principle:BerriAI Litellm Callback Registration
| Knowledge Sources | Domains | Last Updated |
|---|---|---|
| [[1]] | Observability, Event-Driven Architecture | 2026-02-15 |
Overview
Callback registration is the mechanism by which observer functions or objects are enrolled to receive notifications at specific points in an LLM API call lifecycle.
Description
In any system that routes requests to external services, there is a need to observe what happens at each stage: before the call, after a successful response, and after a failure. The callback registration pattern provides a centralized facility for adding, deduplicating, and managing these observer functions.
Key problems this pattern solves:
- Duplicate prevention -- Without deduplication, hot-reloading configuration or re-initializing routers can cause the same callback to be registered multiple times, leading to redundant logging and wasted CPU.
- Resource bounds -- An unbounded callback list can grow out of control if registration occurs in a loop or during repeated configuration refreshes. A maximum callback limit prevents resource exhaustion.
- Heterogeneous callback types -- Callbacks may be plain strings (resolved to built-in integrations at dispatch time), callable functions, or full custom logger objects. The registration system must handle all three uniformly.
- Lifecycle targeting -- Different callbacks need to fire at different lifecycle points: input preprocessing, synchronous success, asynchronous success, failure, or service-level events. The registration API must route each callback to the correct list.
Usage
Apply callback registration when:
- Configuring which observability integrations are active for a deployment.
- Programmatically adding or removing callbacks at runtime (e.g., when a router is destroyed and rebuilt).
- Implementing per-request dynamic callbacks that supplement the global callback lists.
- Enforcing an upper bound on the number of registered callbacks to prevent performance degradation.
Theoretical Basis
Observer Pattern
Callback registration is a concrete application of the Observer pattern. The LLM call lifecycle acts as the subject, and each registered callback is an observer. The subject notifies all registered observers at the appropriate lifecycle point.
LIFECYCLE_POINTS := {
input_callback,
success_callback,
failure_callback,
async_success_callback,
async_failure_callback,
service_callback,
callbacks -- fires on both success and failure
}
Deduplication Strategy (Pseudocode)
function register_callback(callback, target_list):
if length(target_list) >= MAX_CALLBACKS:
log_warning("Callback limit reached")
return
if callback is string:
if callback in target_list:
return -- exact string match
target_list.append(callback)
else if callback is CustomLogger:
key = compute_logger_key(callback)
for existing in target_list:
if existing is CustomLogger and compute_logger_key(existing) == key:
return -- same class + same config
target_list.append(callback)
else if callback is callable:
if callback in target_list:
return -- function identity match
target_list.append(callback)
function compute_logger_key(logger):
parts = [class_name(logger)]
for attr_name, attr_value in instance_vars(logger):
if not starts_with(attr_name, "_"):
if is_primitive(attr_value):
parts.append(attr_name + "=" + str(attr_value))
return join(parts, "-")
Removal Patterns
Removal is as important as registration. When a router is destroyed, all callbacks bound to that router instance must be cleaned up to prevent dangling references:
function remove_callbacks_for_object(callback_list, owner_object):
for callback in callback_list:
if callback is a bound method of owner_object:
callback_list.remove(callback)
A type-based removal variant removes all callbacks of a given class, useful when swapping one integration implementation for another.