uptimes-agents (Python)

OpenTelemetry-based observability SDK for AI agents — three-line install, ships to the local uptimes-monitor daemon or direct to api.uptimes.ai.

Install

pip install uptimes-agents
# Add provider extras for auto-instrumentation:
pip install 'uptimes-agents[anthropic]'    # or [openai], or [all]

Quick start

import uptimes_agents
import anthropic

uptimes_agents.init(service_name="rca-agent")

client = anthropic.Anthropic()
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=[{"role": "user", "content": "hi"}],
)
# → one chat span lands in your Uptimes dashboard within ~5s.

Custom spans

For non-LLM work — init() activates auto-instrumentation for known provider SDKs; for everything else, wrap your code in a span:

with uptimes_agents.span("execute_plan", hypothesis="db_slow"):
    ...
    uptimes_agents.current_span().set_attribute("steps_taken", 4)

Configuration

Standard OTel env vars (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) are honored — drop-in for existing OTel-instrumented apps.

Routing modes

Default is via the local monitor: spans go to http://localhost:4318 on the host. uptimes-monitor enriches them with host context, batches, and forwards over a single TLS connection to api.uptimes.ai. No API key needed in your app — the monitor's token stamps org_id.

For containerised environments without a host daemon, point straight at the cloud:

uptimes_agents.init(
    service_name="my-agent",
    endpoint="https://api.uptimes.ai/api/v1/telemetry",
    api_key="<your-org-token>",
)

The SDK appends telemetry-service's ingest path, so spans are POSTed to https://api.uptimes.ai/api/v1/telemetry/v1/traces/otlp. Don't put /v1/traces/otlp directly on the host: api.uptimes.ai is the API gateway, which serves telemetry-service only under /api/v1/telemetry. If an existing config uses a bare https://api.uptimes.ai or https://api.uptimes.ai/v1/traces/otlp, the SDK routes it through /api/v1/telemetry for you. The website domains uptimes.ai and www.uptimes.ai don't accept spans, so an endpoint on either is rewritten to https://api.uptimes.ai/api/v1/telemetry.

Only uptimes.ai / *.uptimes.ai hosts, or an endpoint whose path is telemetry-service's /v1/traces/otlp, count as direct-to-cloud (API key required, sent as X-API-Key). Any other endpoint — the monitor on localhost, a node IP, the in-cluster uptimes-monitor Service, or your own OTel collector — is treated as a plain OTLP/HTTP receiver: no key is needed or sent, and spans go to <endpoint>/v1/traces.

What gets captured

Auto-instrumentation produces OTel-GenAI spans for every Anthropic / OpenAI LLM call:

• Provider, model, token usage, cost
• Latency, time-to-first-chunk, stop reason
• Tool calls (when the provider returns tool_use content)
• Input / output content (governable via OTel content-capture toggles)

Custom span(...) blocks produce regular OTel spans you can group by name in the dashboard.

Versioning

V0.1 — Anthropic + OpenAI auto-instrumentation. Bedrock / Vertex / Gemini land in V0.2.