Vantage LiteLLM Callback

Required Vantage collector

The callback works with the Vantage LiteLLM collector. To set up the Vantage LiteLLM integration, install both components:

1. Run the collector beside each LiteLLM proxy. The collector stores usage events and uploads compacted batches to Vantage.
2. Install this callback in the LiteLLM Python environment. The callback sends usage events to the local collector over its Unix socket.

The callback cannot upload usage to Vantage by itself. The collector cannot collect LiteLLM usage without the callback. See the collector repository README for deployment and configuration instructions.

Install

Install a released version with:

pip install vantage-litellm-callback

To work from a source checkout, install this directory with pip install .. Configure LiteLLM with:

litellm_settings:
  callbacks:
    - vantage_callback.callback_instance

See the repository README for collector setup and lifecycle billing semantics.

The callback is fail-open: collector outages, acknowledgement failures, malformed responses, queue pressure, and projection errors never block or fail a provider request. Usage events are placed into a bounded in-process queue and delivered by a background worker. When delivery is unhealthy, the worker opens a circuit, aggregates bounded loss information, and periodically probes the collector with a versioned delivery_gap control frame. Normal delivery resumes only after that frame receives a durable acknowledgement.

Configuration:

• VANTAGE_COLLECTOR_DELIVERY_QUEUE_SIZE (default 1024)
• VANTAGE_COLLECTOR_RECOVERY_PROBE_SECONDS (default 5)
• VANTAGE_COLLECTOR_GAP_EVENT_ID_SAMPLE_SIZE (default 32)
• VANTAGE_COLLECTOR_GAP_SUMMARY_INTERVAL_SECONDS (default 60)
• VANTAGE_COLLECTOR_SOCKET_PATH (default /var/run/vantage-collector/collector.sock)
• VANTAGE_COLLECTOR_ACK_TIMEOUT_SECONDS (default 5)
• VANTAGE_COLLECTOR_CONNECTION_POOL_SIZE (default 16)

The queue and gap aggregate are intentionally process-local and bounded. A process exit may therefore lose queued events; the gap frame reports losses observed while the process remains alive.