Skip to main content
Re-exported from fiddler_otel.client.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). Initialise the FiddlerClient.

​
Parameters

​
application_id
str
required
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
default:"''"
The API key for authenticating with the Fiddler backend. Required when otlp_enabled=True (the default). Not required when otlp_enabled=False (e.g. S3-routing mode) — omit or pass ''.
​
url
str
default:"''"
The base URL for your Fiddler instance (e.g. https://your-instance.fiddler.ai). Required when otlp_enabled=True (the default). Not required when otlp_enabled=False — omit or pass ''. Must use http or https scheme.
​
otlp_enabled
bool
default:"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 and not validated. Defaults to True.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
default:"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
default:"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 or by setting the corresponding environment variables.
​
sampler
Sampler | None
The sampler for deciding which spans to record. Defaults to the parent-based always-on OpenTelemetry sampler (100% sampling).
​
compression
Compression
default:"Compression.Gzip"
The compression algorithm for exporting traces. Can be Compression.Gzip, Compression.Deflate, or Compression.NoCompression. Only used when otlp_enabled=True. Defaults to Compression.Gzip.
​
jsonl_capture_enabled
bool
default:"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
default:"'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
default:"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
default:"'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.
​
normalize_multimodal
bool
default:"False"
If True, large inline base64 content in span attributes is uploaded to S3 via POST /v3/files/upload and replaced with fiddler-file:// URIs before the span is exported. This prevents trace loss at the 10MB Kafka span limit. Requires otlp_enabled=True (needs url and api_key). Defaults to False.

​
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.
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.
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): 
# otlp_enabled=False     → disables direct OTLP export; api_key and url not needed
# otlp_json_capture_enabled=True → writes traces to local .json files in standard
#                                   OTLP JSON format (ExportTraceServiceRequest)
# application_id is still required so the S3 connector routes traces correctly
#
# Upload 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

FiddlerClient

​
exit()

Context manager exit — flushes and shuts down the tracer provider.

​
force_flush()

Flush pending spans to the exporter.

​
Parameters

​
timeout_millis
int
default:"30000"
Maximum time to wait for flush in milliseconds.

​
Returns

True if flush completed within the timeout, False otherwise.

​
async aflush()

Async version of force_flush(). Runs the flush in a thread pool so the event loop is not blocked.

​
Returns

bool

​
shutdown()

Shut down the tracer provider after flushing pending spans. Safe to call multiple times. The atexit handler is unregistered on first call.

​
async ashutdown()

Async version of shutdown(). Runs flush and shutdown in a thread pool so the event loop is not blocked.

​
get_tracer_provider()

Return the OpenTelemetry TracerProvider, initializing it on first call.

​
Returns

The configured TracerProvider.

​
Raises

RuntimeError – If initialization fails.

​
update_resource()

Update the OTel resource with additional attributes. Must be called before get_tracer() is invoked.

​
Parameters

​
attributes
dict[str, Any]
required
Key-value pairs to merge into the resource.

​
Raises

ValueError – If the tracer has already been initialized.

​
get_tracer()

Return an OTel tracer for creating spans. Initializes the tracer on the first call.

​
Returns

The OTel tracer instance.

​
Raises

RuntimeError – If tracer initialization fails.

​
start_as_current_span()

Create a span using a context manager (automatic lifecycle management).

​
Parameters

​
name
str
required
Name for the span.
​
as_type
Literal['span', 'generation', 'chain', 'tool']
default:"'span'"
Span type — "span", "generation", "chain", or "tool".

​
Returns

Span wrapper with context manager support.

​
start_span()

Create a span with manual lifecycle control. Caller must call span.end().

​
Parameters

​
name
str
required
Name for the span.
​
as_type
Literal['span', 'generation', 'chain', 'tool']
default:"'span'"
Span type — "span", "generation", "chain", or "tool".

​
Returns

Span wrapper requiring an explicit end() call.
See the canonical reference for the full description and examples.