fiddler-otel

Core OpenTelemetry instrumentation library for Fiddler GenAI observability. This is the foundation package used by all Fiddler framework integrations (fiddler-langgraph, fiddler-langchain).

Installation

pip install fiddler-otel

Quick Start

Runnable example: see examples/travel_agent.py for a complete, traced travel-booking agent using the @trace decorator.

Using the @trace decorator

The simplest way to instrument any Python function — synchronous or async:

from fiddler_otel import FiddlerClient, trace

client = FiddlerClient(
    application_id='YOUR_APPLICATION_ID',
    api_key='YOUR_API_KEY',
    url='https://your-instance.fiddler.ai',
)


@trace(span_type='generation', name='my_llm_call')
def call_llm(prompt: str) -> str:
    # your LLM call here
    return response


@trace(span_type='chain')
async def run_pipeline(user_input: str) -> str:
    result = call_llm(user_input)
    return result

Using span wrappers manually

For fine-grained control over span attributes:

from fiddler_otel import FiddlerClient, FiddlerGeneration, FiddlerChain, FiddlerTool

client = FiddlerClient(
    application_id='YOUR_APPLICATION_ID',
    api_key='YOUR_API_KEY',
    url='https://your-instance.fiddler.ai',
)

with client.start_span('my_agent', span_type='chain') as chain_span:
    gen = FiddlerGeneration(client.start_span('llm_call'))
    with gen as span:
        span.set_input('What is the capital of France?')
        response = call_llm('What is the capital of France?')
        span.set_output(response)
        span.set_usage(input_tokens=10, output_tokens=5, total_tokens=15)

Multi-turn Conversations

Link multiple agent invocations into a single conversation:

from fiddler_otel import set_conversation_id
import uuid

set_conversation_id(str(uuid.uuid4()))

# All spans created after this call carry the same conversation_id
result = my_agent(user_message)

Local JSONL Capture

Write spans to a local file in addition to sending them directly to Fiddler. Useful for local debugging or auditing.

Note: jsonl_capture_enabled=True is additive — spans are still exported to Fiddler. To stop direct export, set otlp_enabled=False (see Offline / S3 Routing Mode below).

client = FiddlerClient(
    application_id='...',
    api_key='...',
    url='...',
    jsonl_capture_enabled=True,
    jsonl_file_path='trace_data.jsonl',
)

Or via environment variables:

FIDDLER_JSONL_ENABLED=true \
FIDDLER_JSONL_FILE=trace_data.jsonl \
python my_agent.py

Console Tracing (Development)

Print all spans to stdout during development.

Note: console_tracer=True is additive — spans are still exported to Fiddler. It does not suppress direct OTLP export.

client = FiddlerClient(
    application_id='...',
    api_key='...',
    url='...',
    console_tracer=True,
)

AWS SageMaker Partner App

When fiddler-otel runs inside an AWS SageMaker Partner Application, OTLP requests can be signed with AWS SigV4 and routed through the SageMaker partner API proxy. The feature is opt-in via environment variables — no code changes are required.

Install the sagemaker extra (already pre-installed in SageMaker-managed runtimes):

pip install "fiddler-otel[sagemaker]"

Then set:

export AWS_PARTNER_APP_AUTH=true
export AWS_PARTNER_APP_ARN=arn:aws:sagemaker:us-east-1:123456789012:partner-app/Partner/app-xyz
export AWS_PARTNER_APP_URL=https://app-xyz.us-east-1.mlapp.sagemaker.aws

AWS credentials are resolved via the standard boto3 credential chain — IAM role inside a SageMaker runtime, ~/.aws/credentials, instance profile, or environment variables. No additional env vars are required when running inside the partner-app sandbox.

When all three AWS_PARTNER_APP_* variables are present, FiddlerClient attaches a SigV4-signing requests.Session to the OTLP exporter. When AWS_PARTNER_APP_AUTH is unset or false, the client behaves exactly as before — no SageMaker dependency is imported.

Offline / S3 Routing Mode

Use otlp_enabled=False to stop all direct OTLP export to Fiddler. Combined with otlp_json_capture_enabled=True, spans are written to local .json files in standard OTLP JSON format (ExportTraceServiceRequest envelope) that can be ingested by the Fiddler S3 connector.

When otlp_enabled=False, api_key and url are not required.

Why is application_id still required? Even when not connecting to Fiddler directly, application_id is embedded in every trace file as a resource attribute. The Fiddler S3 connector reads this attribute to route ingested traces to the correct application in your Fiddler account. Obtain the UUID4 from your Fiddler application dashboard.

client = FiddlerClient(
    application_id='YOUR_APPLICATION_ID',  # from your Fiddler dashboard — embedded in trace files
    otlp_enabled=False,  # no spans sent directly to Fiddler
    otlp_json_capture_enabled=True,  # write OTLP JSON files locally
    otlp_json_output_dir='./trace_output',  # directory for output files (created if absent)
)

Each export batch produces one file named fiddler_trace_<timestamp>_<hex>.json inside otlp_json_output_dir. The directory is created automatically if it does not exist. These files can be uploaded to object storage and ingested by the Fiddler S3 connector without any reformatting.

Public API

Context Isolation

fiddler-otel uses its own isolated OpenTelemetry context that does not interfere with any existing global tracer in your application. If you already use OpenTelemetry for infrastructure tracing, Fiddler spans will not appear in your infrastructure traces and vice versa.

Framework Integrations

Both integration packages depend on fiddler-otel and re-export its core symbols, so you typically only need to install the integration package for your framework.

Requirements

• Python 3.10+
• opentelemetry-api >= 1.27.0
• opentelemetry-sdk >= 1.27.0
• opentelemetry-exporter-otlp-proto-http >= 1.27.0
• pydantic >= 2.0