BAML Advanced

Collector

This feature was added in 0.79.0

The Collector allows you to inspect the internal state of BAML function calls, including raw HTTP requests, responses, usage metrics, and timing information, so you can always see the raw data, without any abstraction layers.

Quick Start

1from baml_client import b
2from baml_py import Collector
3
4# Create a collector with optional name
5collector = Collector(name="my-collector")
6
7# Use it with a function call
8result = b.ExtractResume("...", baml_options={"collector": collector})
9
10# Access logging information
11print(collector.last.usage)  # Print usage metrics
12print(collector.last.raw_llm_response)  # Print final response as string
13# since there may be retries, print the last http response received
14print(collector.last.calls[-1].http_response)

Common Use Cases

Basic Logging

1from baml_client import b
2from baml_py import Collector  # Import the Collector class
3
4def run():
5    # Create a collector instance with an optional name
6    collector = Collector(name="my-collector")
7    # collector will be modified by the function to include all internal state
8    res = b.ExtractResume("...", baml_options={"collector": collector})
9    # This will print the return type of the function
10    print(res)
11
12    # This is guaranteed to be set by the function
13    assert collector.last is not None
14
15    # This will print the id of the last request
16    print(collector.last.id)
17
18    # This will print the usage of the last request
19    # (This aggregates usage from all retries if there was usage emitted)
20    print(collector.last.usage)
21
22    # This will print the raw response of the last request
23    print(collector.last.calls[-1].http_response)
24
25    # This will print the raw text we used to run the parser.
26    print(collector.last.raw_llm_response)

Managing Collector State

1from baml_client import b
2from baml_py import Collector
3
4def run():
5    collector = Collector(name="reusable-collector")
6    res = b.ExtractResume("...", baml_options={"collector": collector})
7    # Remove all logs and free up memory
8    collector.clear()
9
10    # Reuse the same collector
11    res = b.TestOpenAIGPT4oMini("Second call", baml_options={"collector": collector})

Using Multiple Collectors

You can use multiple collectors to track different aspects of your application:

1from baml_client import b
2from baml_py import Collector
3
4def run():
5    # Create separate collectors for different parts of your application
6    collector_a = Collector(name="collector-a")
7    collector_b = Collector(name="collector-b")
8    
9    # Use both collectors for the same function call
10    res = b.ExtractResume("...", baml_options={"collector": [collector_a, collector_b]})
11    
12    # Both collectors will have the same logs
13    assert collector_a.last.usage.input_tokens == collector_b.last.usage.input_tokens
14    
15    # Use only collector_a for another call
16    res2 = b.TestOpenAIGPT4oMini("another call", baml_options={"collector": collector_a})
17    
18    # collector_a will have 2 logs, collector_b will still have 1
19    assert len(collector_a.logs) == 2
20    assert len(collector_b.logs) == 1

Usage Tracking

1from baml_client import b
2from baml_py import Collector
3
4def run():
5    collector_a = Collector(name="collector-a")
6    res = b.ExtractResume("...", baml_options={"collector": collector_a})
7
8    collector_b = Collector(name="collector-b")
9    res = b.ExtractResume("...", baml_options={"collector": collector_b})
10
11    # The total usage of both logs is now available
12    print(collector_a.usage)
13    print(collector_b.usage)

API Reference

Collector Class

The Collector class provides properties to introspect the internal state of BAML function calls.

PropertyTypeDescription
logsList[FunctionLog]A list of all function calls (ordered from oldest to newest)
lastFunctionLog | nullThe most recent function log.
usageUsageThe cumulative total usage of all requests this collector has tracked. This includes all retries and fallbacks, if those did use any tokens.

The Collector class provides the following methods:

MethodTypeDescription
id(id: string)FunctionLog | nullGet the function log by id.
clear()voidClears all logs.

FunctionLog Class

The FunctionLog class has the following properties:

PropertyTypeDescription
idstringThe id of the request.
function_namestringThe name of the function.
log_type"call" | "stream"The manner in which the function was called.
timingTimingThe timing of the request.
usageUsageThe usage of the request (aggregated from all calls).
calls(LLMCall | LLMStreamCall)[]Every call made to the LLM (including fallbacks and retries). Sorted from oldest to newest.
raw_llm_responsestring | nullThe raw text from the best matching LLM.
tagsMap[str, any]Any user provided metadata.

Timing Class

The Timing class has the following properties:

PropertyTypeDescription
start_time_utc_msintThe start time of the request in milliseconds since epoch.
duration_msint | nullThe duration of the request in milliseconds.

StreamTiming Class (extends Timing)

PropertyTypeDescription
time_to_first_token_msint | nullThe time to first token in milliseconds.

Usage Class

The Usage class has the following properties:

PropertyTypeDescription
input_tokensint | nullThe cumulative number of tokens used in the inputs.
output_tokensint | nullThe cumulative number of tokens used in the outputs.

Note: Usage may not include all things like “thinking_tokens” or “cached_tokens”. For that you may need to look at the raw HTTP response and build your own adapters.

LLMCall Class

The LLMCall class has the following properties:

PropertyTypeDescription
client_namestrThe name of the client used.
providerstrThe provider of the client used.
timingTimingThe timing of the request.
http_requestHttpRequestThe raw HTTP request sent to the client.
http_responseHttpResponse | nullThe raw HTTP response from the client (null for streaming).
usageUsage | nullThe usage of the request (if available).
selectedboolWhether this call was selected and used for parsing.

LLMStreamCall Class (extends LLMCall)

The LLMStreamCall includes the same properties as LLMCall plus the following:

PropertyTypeDescription
timingStreamTimingThe timing of the request.
chunksstring[]The chunks of the response (API coming soon).

HttpRequest Class

The HttpRequest class has the following properties:

PropertyTypeDescription
urlstrThe URL of the request.
methodstrThe HTTP method of the request.
headersobjectThe request headers.
bodyobjectThe request body.

HttpResponse Class

The HttpResponse class has the following properties:

PropertyTypeDescription
statusintThe HTTP status code.
headersobjectThe response headers.
bodyobjectThe response body.

Best Practices

  1. Use a single collector instance when tracking related function calls in a chain.
  2. Clear the collector when reusing it for unrelated operations.
  3. Consider using multiple collectors to track different parts of your application.
  4. Use function IDs when tracking specific calls in parallel operations.
  5. For streaming calls, be aware that http_response will be null, but you can still access usage information.