cloptima-llm-observability 0.1.0

LLM usage telemetry SDK for Cloptima reporting, attribution, and analytics

Cloptima LLM Observability Python SDK

Capture LLM usage telemetry from your application and send it to Cloptima for cost reporting, attribution, and analytics.

Use this SDK when you want visibility into LLM usage without replacing your existing provider clients, retry policies, authentication, or application-level security controls.

Install

pip install cloptima-llm-observability

If you want to use the httpx transport helpers, install the optional extra:

pip install "cloptima-llm-observability[httpx]"

Configuration

Required environment variables:

Variable	Required	Purpose
CLOPTIMA_LLM_OBSERVABILITY_INGEST_URL	Yes	HTTPS endpoint for SDK event ingestion
CLOPTIMA_LLM_OBSERVABILITY_API_KEY	Yes	Cloptima API key for telemetry writes
CLOPTIMA_LLM_OBSERVABILITY_APP_ID	Yes	Application or service identifier
CLOPTIMA_LLM_OBSERVABILITY_ENVIRONMENT	Yes	Deployment environment such as dev, staging, or prod
CLOPTIMA_LLM_OBSERVABILITY_TEAM_ID	No	Team or ownership group
CLOPTIMA_LLM_OBSERVABILITY_ENABLED	No	Explicitly enable or disable the SDK
CLOPTIMA_LLM_OBSERVABILITY_DELIVERY_MODE	No	cloptima_http, otlp_http, or dual
CLOPTIMA_LLM_OBSERVABILITY_OTLP_URL	No	Custom OTLP endpoint
CLOPTIMA_LLM_OBSERVABILITY_OTLP_SERVICE_NAME	No	OTLP service name
CLOPTIMA_LLM_OBSERVABILITY_OTLP_SERVICE_VERSION	No	OTLP service version

The SDK sends bearer-authenticated HTTPS requests to the configured Cloptima ingest endpoint.

Quick start

Use observe_call(...) at the point where your application already invokes an LLM provider or an internal AI helper.

from cloptima_llm_observability import (
    extract_openai_usage,
    init_from_env,
)

cloptima = init_from_env()

result = cloptima.observe_call(
    provider="openai",
    model="gpt-4.1-mini",
    call=lambda: summary_service.generate(prompt),
    extract_usage=extract_openai_usage,
    feature_id="summaries",
    workflow_id="support-agent",
    team_id="customer-support",
    fire_and_forget=False,
)

This integration style works well because it:

• keeps your existing provider integration intact
• captures the most accurate model and feature context
• avoids SDK-specific coupling throughout your codebase
• works well with existing wrappers and shared AI services

Async and streaming calls

If your application already uses async calls or streaming responses, use the matching helpers:

result = await cloptima.observe_async_call(
    provider="anthropic",
    model="claude-3-5-sonnet",
    call=lambda: assistant_client.reply(messages),
    feature_id="chat_reply",
)

async for chunk in cloptima.observe_async_stream_call(
    provider="openai",
    model="gpt-4.1-mini",
    call=lambda: stream_client.stream(prompt),
    feature_id="live_answer",
):
    print(chunk)

Shared transport integration

If your application centralizes outbound LLM calls behind a shared httpx transport, instrument that boundary instead:

import httpx

from cloptima_llm_observability import init_from_env, instrument_httpx_transport

cloptima = init_from_env()
transport = instrument_httpx_transport(
    httpx.HTTPTransport(),
    cloptima=cloptima,
    provider="openai",
    model="gpt-4o-mini",
    fire_and_forget=False,
)
client = httpx.Client(transport=transport)

This is useful for broad coverage, but it has less application context than observe_call(...). Prefer the boundary helper when you already know the provider, model, and feature at the call site.

OTLP mode

The SDK supports three delivery modes:

• cloptima_http
• otlp_http
• dual

Use otlp_http or dual when you want OpenTelemetry-compatible output in addition to, or instead of, direct Cloptima delivery.

Attribution fields

The most useful fields for reporting and ownership are:

• app_id
• environment
• team_id
• feature_id
• workflow_id
• cost_center
• business_unit
• tenant_id
• customer_segment
• cloud_account_id
• cluster_id
• repository_id

You can pass them through default_attribution, or directly on observe_call(...) / observe_stream_call(...).

Metadata controls

Use metadata_policy to control what custom metadata is retained:

• metadata_only
• allowlisted_metadata
• strict_finops
• debug_observability

Sensitive-looking keys such as prompts, messages, credentials, and secrets are treated conservatively by default.

Validation helpers

These helpers are useful when you want to inspect payloads locally before sending traffic to Cloptima:

• preview_event_payload(...)
• preview_batch_payload(...)
• preview_otlp_request(...)
• validate_payload(...)

They return payload previews in memory and do not send network traffic.

Examples

See the examples/ directory for:

• OpenAI boundary instrumentation
• Anthropic boundary instrumentation
• Gemini boundary instrumentation
• custom wrapper instrumentation
• httpx transport instrumentation

Public API

Stable core surface:

• CloptimaLLMObservability
• init_from_env
• disabled_client
• observe
• observe_call
• observe_async_call
• observe_stream
• observe_stream_call
• record
• record_batch
• record_async
• provider usage extractors

Additional helper surface:

• instrument_httpx_client
• instrument_httpx_transport
• instrument_openai_compatible_response
• instrument_openai_compatible_stream
• ainstrument_openai_compatible_response
• ainstrument_openai_compatible_stream
• instrument_fastapi_request_context
• instrument_flask_request_context

Troubleshooting

No telemetry arrives:

• verify CLOPTIMA_LLM_OBSERVABILITY_INGEST_URL
• verify the API key is valid for SDK event ingestion
• check client.is_enabled()
• inspect a sample event with validate_payload(preview_event_payload(...))

Configuration behavior:

• init_from_env() returns a disabled pass-through client when configuration is absent
• if you explicitly enable the SDK with incomplete config, initialization stays non-blocking by default unless strict=True

Payload contracts

• single event schema: cloptima.llm.event.v1
• batch schema: cloptima.llm.batch.v1

SDK envelopes also include sdk_delivery_stats for delivery monitoring.

Support

• Issues: https://github.com/cloptima/cloptima-llm-observability-python/issues
• Security: see SECURITY.md
• Product support: [e-mail]