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

Parameter	Type	Required	Default	Description
application_id	str	✓	-	The unique identifier (UUID4) for the application. Must be a valid UUID4 (e.g. 550e8400-e29b-41d4-a716-446655440000). Copy this from the GenAI Applications page in the Fiddler UI. Required in all modes — even when otlp_enabled=False — because the S3 connector uses it to route traces to the correct application.
api_key	str	✗	''	The API key for authenticating with the Fiddler backend. Required when otlp_enabled=True (the default). Can be omitted or left empty when otlp_enabled=False (offline / S3 routing mode).
url	str	✗	''	The base URL for your Fiddler instance (e.g. https://your-instance.fiddler.ai). Required when otlp_enabled=True (the default). Can be omitted or left empty when otlp_enabled=False (offline / S3 routing mode). Must use http or https scheme.
otlp_enabled	bool	✗	True	Controls whether traces are exported directly to the Fiddler OTLP endpoint. Set to False to disable all direct export to Fiddler — useful when traces must first be written to local files for S3 upload (offline / S3 routing mode). When False, api_key and url are not required. Note: console_tracer, jsonl_capture_enabled, and otlp_json_capture_enabled are all independent of this flag and can be used in any combination.
console_tracer	bool	✗	False	If True, span data is also printed to the console (stdout). This is additive — traces are still exported to Fiddler via OTLP (unless otlp_enabled=False). Setting this to True does not suppress or replace the OTLP export. Useful for local debugging to confirm spans are being created.
span_limits	SpanLimits | None	✗	None	Configuration for span limits, such as the maximum number of attributes or events. When None (default), OpenTelemetry automatically applies its standard defaults: max_attributes: 128 (or OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT env var); max_events: 128 (or OTEL_SPAN_EVENT_COUNT_LIMIT env var); max_links: 128 (or OTEL_SPAN_LINK_COUNT_LIMIT env var); max_event_attributes: 128 (or OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT env var); max_link_attributes: 128 (or OTEL_LINK_ATTRIBUTE_COUNT_LIMIT env var); max_span_attribute_length: None/unlimited (or OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT env var). Override these by passing a custom SpanLimits object (see example below) or by setting the environment variables.
sampler	sampling.Sampler | None	✗	None	The sampler for deciding which spans to record. Defaults to the parent-based always-on OpenTelemetry sampler (100% sampling).
compression	Compression	✗	Compression.Gzip	The compression algorithm for exporting traces. Can be Compression.Gzip, Compression.Deflate, or Compression.NoCompression. Only used when otlp_enabled=True.
jsonl_capture_enabled	bool	✗	False	If True, span data is also saved to a local JSONL file in a custom Fiddler format. This is additive — OTLP export to Fiddler continues as normal (unless otlp_enabled=False). Setting this to True does not suppress the OTLP export. Useful for keeping a local copy of trace data. Note: This JSONL format is not compatible with the Fiddler S3 connector. For S3 ingestion use otlp_json_capture_enabled=True instead.
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=True. Override with the FIDDLER_JSONL_FILE environment variable.
otlp_json_capture_enabled	bool	✗	False	If True, traces are written to local .json files in standard OTLP JSON format (ExportTraceServiceRequest envelope). Files are written to otlp_json_output_dir. This format is directly compatible with the Fiddler S3 connector — upload the generated files to S3 and the connector ingests them without any reformatting. This is additive relative to OTLP export; combine with otlp_enabled=False to write to files only (offline / S3 routing mode).
otlp_json_output_dir	str	✗	fiddler_traces	Directory path where OTLP JSON files are written when otlp_json_capture_enabled=True. The directory is created automatically if it does not exist. Each batch of spans is written to a separate timestamped .json file.

Raises

• ValueError — If application_id is not a valid UUID4.

• ValueError — If otlp_enabled=True and api_key is empty or not provided.

• ValueError — If otlp_enabled=True and url is empty, missing a scheme, or uses a scheme other than http/https.

Examples

Basic connection to your Fiddler instance:

client = FiddlerClient(
    application_id='YOUR_APPLICATION_ID',  # UUID4, required in all modes
    api_key='YOUR_API_KEY',
    url='https://your-instance.fiddler.ai',
)

High-volume applications with custom configuration:

from opentelemetry.sdk.trace import SpanLimits, sampling
from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression

client = FiddlerClient(
    application_id='YOUR_APPLICATION_ID',
    api_key='YOUR_API_KEY',
    url='https://your-instance.fiddler.ai',
    span_limits=SpanLimits(
        max_span_attributes=64,           # Reduce from default 128
        max_span_attribute_length=2048,   # Limit from default None (unlimited)
    ),
    sampler=sampling.TraceIdRatioBased(0.1),  # Sample 10% of traces
    compression=Compression.Gzip,
)

Local development with console output (traces still sent to Fiddler):

# console_tracer=True prints spans to stdout AND continues to export to Fiddler.
# It does NOT suppress OTLP export. Use it to confirm spans are being created locally.
client = FiddlerClient(
    application_id='00000000-0000-0000-0000-000000000000',
    api_key='dev-key',
    url='http://localhost:4318',
    console_tracer=True,
)

Offline / S3 routing mode (no data sent directly to Fiddler):

# Use this when traces must be routed through an intermediate store (e.g. S3)
# before reaching Fiddler, rather than being sent directly.
#
# - otlp_enabled=False     → disables direct OTLP export; api_key and url are not needed
# - otlp_json_capture_enabled=True → writes traces to local .json files in standard
#                                     OTLP JSON format (ExportTraceServiceRequest envelope)
# - application_id is still required so the S3 connector knows which Fiddler
#   application to route the traces to after upload
#
# Upload the generated .json files from otlp_json_output_dir to your S3 bucket.
# The Fiddler S3 connector reads them directly with no reformatting required.
client = FiddlerClient(
    application_id='YOUR_APPLICATION_ID',
    otlp_enabled=False,
    otlp_json_capture_enabled=True,
    otlp_json_output_dir='./fiddler_traces',  # default: 'fiddler_traces'
)

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

Parameter	Type	Required	Default	Description
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

Parameter	Type	Required	Default	Description
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

from fiddler_langgraph import FiddlerClient
client = FiddlerClient(application_id='...', api_key='...', url='https://your-instance.fiddler.ai')
client.update_resource({'service.version': '1.2.3'})

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

from fiddler_langgraph import FiddlerClient
client = FiddlerClient(application_id='...', api_key='...', url='https://your-instance.fiddler.ai')
tracer = client.get_tracer()
with tracer.start_as_current_span('my-operation'):
    print('Doing some work...')

start_as_current_span()

Create a span using context manager (automatic lifecycle).

Parameters

Parameter	Type	Required	Default	Description
name	str	✓	-	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

Parameter	Type	Required	Default	Description
name	str	✓	-	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