> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FiddlerClient

> The main client for instrumenting Generative AI applications with Fiddler observability.

<Info>Re-exported from [`fiddler_otel.client.FiddlerClient`](/sdk-api/otel/fiddler-client).</Info>

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()`](#force_flush) and [`shutdown()`](#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()`](#async-aflush) and [`ashutdown()`](#async-ashutdown) so the event
loop is not blocked; the sync [`force_flush()`](#force_flush) and [`shutdown()`](#shutdown) can block for
up to the flush timeout.

Context manager: Use `with FiddlerClient(...) as client:` to ensure
[`shutdown()`](#shutdown) is called on exit (flush then shutdown; atexit is unregistered).

AWS SageMaker Partner App: When running inside a SageMaker Partner Application,
set the following environment variables to enable SigV4-signed OTLP export — no
code changes are required:

* `AWS_PARTNER_APP_AUTH=true` — opt-in trigger
* `AWS_PARTNER_APP_ARN` — ARN of the SageMaker Partner Application resource
* `AWS_PARTNER_APP_URL` — base URL of the partner app endpoint

AWS credentials are resolved via the standard boto3 credential chain (IAM role
inside a SageMaker runtime, `~/.aws/credentials`, instance profile, environment
variables); no additional env vars are needed when running inside the partner-app
sandbox.

Install the `sagemaker` extra to enable this feature:

```python theme={null}
pip install "fiddler-otel[sagemaker]"
```

In a SageMaker-managed runtime the package is pre-installed.

Initialise the FiddlerClient.

## Parameters

<ParamField path="application_id" type="str" required={true}>
  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.
</ParamField>

<ParamField path="api_key" type="str" required={false} 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 `''`.
</ParamField>

<ParamField path="url" type="str" required={false} 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.
</ParamField>

<ParamField path="otlp_enabled" type="bool" required={false} 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.
</ParamField>

<ParamField path="console_tracer" type="bool" required={false} 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.
</ParamField>

<ParamField path="span_limits" type="SpanLimits | None" required={false} 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.
</ParamField>

<ParamField path="sampler" type="Sampler | None" required={false} default="the parent-based always-on OpenTelemetry sampler (100% sampling)">
  The sampler for deciding which spans to record. Defaults to the
  parent-based always-on OpenTelemetry sampler (100% sampling).
</ParamField>

<ParamField path="compression" type="Compression" required={false} 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`.
</ParamField>

<ParamField path="jsonl_capture_enabled" type="bool" required={false} 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.
</ParamField>

<ParamField path="jsonl_file_path" type="str" required={false} 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.
</ParamField>

<ParamField path="otlp_json_capture_enabled" type="bool" required={false} 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).
</ParamField>

<ParamField path="otlp_json_output_dir" type="str" required={false} 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.
</ParamField>

<ParamField path="normalize_multimodal" type="bool" required={false} 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`.
</ParamField>

## 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**:

```python theme={null}
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**:

```python theme={null}
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):

```python theme={null}
# 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):

```python theme={null}
# 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

<ParamField path="timeout_millis" type="int" required={false} default="30000">
  Maximum time to wait for flush in milliseconds.
</ParamField>

### Returns

<ResponseField type="bool">
  True if flush completed within the timeout, False otherwise.
</ResponseField>

## *async* aflush()

Async version of [`force_flush()`](#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()`](#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

<ResponseField type="TracerProvider">
  The configured TracerProvider.
</ResponseField>

### Raises

**RuntimeError** – If initialization fails.

## update\_resource()

Update the OTel resource with additional attributes.

Must be called **before** [`get_tracer()`](#get_tracer) is invoked.

### Parameters

<ParamField path="attributes" type="dict[str, Any]" required={true}>
  Key-value pairs to merge into the resource.
</ParamField>

### 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

<ResponseField type="Tracer">
  The OTel tracer instance.
</ResponseField>

### Raises

**RuntimeError** – If tracer initialization fails.

## start\_as\_current\_span()

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

### Parameters

<ParamField path="name" type="str" required={true}>
  Name for the span.
</ParamField>

<ParamField path="as_type" type="Literal['span', 'generation', 'chain', 'tool']" required={false} default="'span'">
  Span type — `"span"`, `"generation"`, `"chain"`, or `"tool"`.
</ParamField>

### Returns

<ResponseField type="FiddlerSpan | FiddlerGeneration | FiddlerChain | FiddlerTool">
  Span wrapper with context manager support.
</ResponseField>

## start\_span()

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

### Parameters

<ParamField path="name" type="str" required={true}>
  Name for the span.
</ParamField>

<ParamField path="as_type" type="Literal['span', 'generation', 'chain', 'tool']" required={false} default="'span'">
  Span type — `"span"`, `"generation"`, `"chain"`, or `"tool"`.
</ParamField>

### Returns

<ResponseField type="FiddlerSpan | FiddlerGeneration | FiddlerChain | FiddlerTool">
  Span wrapper requiring an explicit `end()` call.
</ResponseField>

<Info>See the [canonical reference](/sdk-api/otel/fiddler-client) for the full description and examples.</Info>