FiddlerClient
FiddlerClient
The main client for instrumenting Generative AI applications with Fiddler observability.
This client configures and manages the OpenTelemetry tracer that sends telemetry data to the Fiddler platform for monitoring, analysis, and debugging of your AI agents and workflows.
Flush on exit: A shutdown handler is registered via atexit() so that pending spans are flushed and the tracer is shut down when the process exits. For short scripts or critical workloads, call force_flush() and shutdown() explicitly (e.g. in a try/finally or signal handler) since atexit may not run in all environments (e.g. SIGKILL, fork).
Asyncio: Tracing works in asyncio (context vars propagate across await). When shutting down from async code, use aflush() and ashutdown() so the event loop is not blocked; the sync force_flush() and shutdown() can block for up to the flush timeout.
Context manager: Use with FiddlerClient(...) as client: to ensure shutdown() is called on exit (flush then shutdown; atexit is unregistered).
Parameters
api_key
str
✓
-
The API key for authenticating with the Fiddler backend.
application_id
str
✓
-
The unique identifier (UUID4) for the application.
url
str
✓
-
The base URL for your Fiddler instance. This is specific to your deployment, whether hosted, VPC-deployed, on-premise, or local development (e.g., https://your-instance.fiddler.ai, http://localhost:4318).
console_tracer
bool
✗
False
If True, traces will be printed to the console instead of being sent to the Fiddler backend. Useful for debugging
span_limits
`SpanLimits
None`
✗
None
sampler
`sampling.Sampler
None`
✗
None
compression
Compression
✗
Compression.Gzip
The compression for exporting traces. Can be Compression.Gzip, Compression.Deflate, or Compression.NoCompression
jsonl_capture_enabled
bool
✗
False
Whether to enable JSONL capture of trace data. When enabled, all span data will be captured and saved to a JSONL file in OpenTelemetry format for offline analysis
jsonl_file_path
str
✗
fiddler_trace_data.jsonl
Path to the JSONL file where trace data will be saved. Only used when jsonl_capture_enabled is True
Raises
ValueError -- If application_id is not a valid UUID4 or if the url is not a valid HTTP/HTTPS URL.
Examples
Basic connection to your Fiddler instance:
High-volume applications with custom configuration:
Local development with console output:
enter()
Context manager entry. Returns this client.
Return type: FiddlerClient
exit(exc_type, exc_val, exc_tb)
Context manager exit. Flushes and shuts down the tracer provider.
Return type: None
force_flush()
Flushes pending spans to the exporter.
Call this before process exit (e.g. in signal handlers or atexit) to reduce intermittent span loss. BatchSpanProcessor buffers spans in memory and exports on a schedule; without flush, buffered spans can be lost on exit.
This method is blocking (up to timeout_millis). From async code, use aflush() to avoid blocking the event loop.
Parameters
timeout_millis
int
✗
30000
Maximum time to wait for flush in milliseconds. Default 30000.
Returns
True if flush completed within the timeout, False otherwise.
Return type: bool
async aflush(timeout_millis=30000)
Async version of force_flush().
Runs the flush in a thread pool so the event loop is not blocked. Use this when shutting down an asyncio application.
Return type: bool
shutdown()
Shuts down the tracer provider after flushing pending spans.
Call this when the application is exiting to ensure all spans are exported. Safe to call multiple times. Registered automatically via atexit when the client is created. The atexit handler is unregistered so it will not run again at process exit.
This method is blocking (flush can take up to 30 seconds). From async code, use ashutdown() to avoid blocking the event loop.
Return type: None
async ashutdown()
Async version of shutdown().
Runs flush and shutdown in a thread pool so the event loop is not blocked. Use this when shutting down an asyncio application, e.g. in an async with cleanup or before closing the event loop.
Return type: None
get_tracer_provider()
Gets the OpenTelemetry TracerProvider instance.
Initializes the provider on the first call.
Returns
The configured OpenTelemetry TracerProvider.
Return type: TracerProvider
Raises
RuntimeError -- If tracer provider initialization fails.
update_resource()
Updates the OpenTelemetry resource with additional attributes.
Use this to add metadata that applies to all spans, such as version numbers or environment names.
Must be called before get_tracer() is invoked.
Parameters
attributes
dict[str, Any]
✓
-
Key-value pairs to add to the resource.
Raises
ValueError -- If the tracer has already been initialized. Return type: None
Examples
get_tracer()
Returns an OpenTelemetry tracer instance for creating spans.
Initializes the tracer on the first call. This is the primary method for developers to get a tracer for custom instrumentation.
Returns
OpenTelemetry tracer instance.
Return type: trace.Tracer
Raises
RuntimeError -- If tracer initialization fails.
Examples
start_as_current_span()
Create a span using context manager (automatic lifecycle).
Parameters
name
str
✗
None
Name for the span.
as_type
Literal['span', 'generation', 'chain', 'tool']
✗
span
Type of span - "span", "generation", "chain", or "tool".
Returns
Wrapper with context manager support.
Return type: FiddlerSpan | FiddlerGeneration | FiddlerChain | FiddlerTool
start_span()
Create a span with manual control. User must call span.end().
Parameters
name
str
✗
None
Name for the span.
as_type
Literal['span', 'generation', 'chain', 'tool']
✗
span
Type of span - "span", "generation", "chain", or "tool".
Returns
Wrapper requiring explicit end() call.
Return type: FiddlerSpan | FiddlerGeneration | FiddlerChain | FiddlerTool
Last updated
Was this helpful?