Trubrics Python SDK

Install the trubrics package using pip to begin tracking events and LLM interactions.

pip install trubrics

To use Trubrics, instantiate the Trubrics class with your project API key. Note that the API key obtained from the Trubrics settings is a POST-only key.

from trubrics import Trubrics

client = Trubrics(api_key="your-api-key")

You can tune the performance and frequency of event flushing by passing flush_interval and flush_batch_size to the Trubrics constructor.

• flush_interval: Time in seconds between automatic flushes (default: 10).
• flush_batch_size: Number of events that trigger a flush (default: 20).

from trubrics import Trubrics

client = Trubrics(
    api_key="your-api-key",
    flush_interval=20,
    flush_batch_size=10,
)

The Trubrics client uses an efficient queuing system with background flushing. To ensure all queued events are sent to the Trubrics API before your application exits, call the close() method.

# optional closing method to ensure all events are flushed from the queue before exiting your app
client.close()

Use the track method to record standard user or system events. You can provide a user_id, an event name, and a dictionary of properties to add context to the event.

client.track(
    user_id="user123",
    event="button_click",
    properties={"button_type": "submit"},
)

Use the track_llm method to record detailed Large Language Model interactions. This method captures the prompt, the assistant used, the generated response, and metadata like latency and thread IDs.

Parameters:

• user_id: The ID of the user.
• prompt: The input sent to the LLM.
• assistant_id: The identifier for the model used (e.g., gpt-4).
• generation: The text generated by the LLM.
• properties: A dictionary of additional metadata.
• latency: The time taken for the generation in seconds.
• thread_id: The identifier for the conversation thread.

client.track_llm(
    user_id="user123",
    prompt="What is the capital of France?",
    assistant_id="gpt-4",
    generation="The capital of France is Paris.",
    properties={
        "support_tier": "entreprise",
    },
    latency=1.5,  # seconds
    thread_id="user123_thread_id"
)

The client uses Python's standard logging library. By default, it logs at the ERROR level. You can adjust the verbosity of the internal logger or provide your own logger instance during initialization.

Adjusting verbosity:

import logging
trubrics = Trubrics(api_key="your-api-key")
trubrics.logger.setLevel(logging.DEBUG)

Providing a custom logger:

trubrics = Trubrics(api_key="your-api-key", logger=your_cool_logger)

Because the Trubrics client uses a background thread to batch and flush events, you should call close() when your application exits. This ensures that all remaining events in the queue are flushed to the server before the process terminates.

Calling close() will:

1. Signal the background thread to stop.
2. Wait for the background thread to finish (join).
3. Perform a final flush() of all queued events.

client.close()

To start tracking events, instantiate the Trubrics class with your API key. The client manages a background thread that automatically flushes events to the Trubrics API based on configured intervals or batch sizes.

Configuration Options

• api_key (str): Required. Your Trubrics account API key.
• host (str): The API host URL. Defaults to https://app.trubrics.com/api/ingestion.
• flush_interval (float): Seconds after which events are flushed. Minimum allowed is MIN_FLUSH_INTERVAL.
• flush_batch_size (int): Number of events to flush at once. Maximum allowed is MAX_FLUSH_BATCH_SIZE.
• flush_periodic_check (float): Interval between periodic checks for flushing. Must be $\le$ flush_interval.
• logger (logging.Logger): Custom logger instance.

from trubrics import Trubrics

client = Trubrics(api_key="YOUR_API_KEY")

Use the track() method to record user actions or system events. Events are queued and sent asynchronously.

Arguments

• user_id (str): The unique identifier for the user.
• event (str): The name of the event.
• properties (dict | None): Metadata associated with the event. The SDK automatically adds a source property (e.g., python_sdk_1.8.5).
• timestamp (datetime | None): The event timestamp. If None, the current UTC time is used. Must be a datetime object.

Example

from datetime import datetime, timezone

client.track(
    user_id="user_123",
    event="button_clicked",
    properties={"button_color": "blue"},
    timestamp=datetime.now(timezone.utc)
)

The primary entrypoint for the library is the Trubrics class. You can import it directly from the trubrics package to begin tracking events and LLM interactions. Use this client to manage your event queue and ensure data is flushed to the Trubrics platform.

from trubrics import Trubrics

# Initialize the client
trubs = Trubrics(api_key="YOUR_API_KEY")