watchlog-ai-tracer 1.0.0

Lightweight Python tracer for Watchlog AI monitoring

python-ai-tracer

python-ai-tracer is a Python instrumentation library for tracing AI/LLM calls and exporting spans to a Watchlog agent. It supports batching, persistence, and automatic environment detection (local vs. Kubernetes).

Features

• Lightweight tracer: start and end spans to capture timing, cost, tokens, model, provider, input/output.
• Batching & persistence: automatically buffers spans on disk and flushes in the background or on-demand.
• Kubernetes-friendly: auto-detects K8s environment to select the correct agent URL.
• Configurable: customize batch size, flush intervals, retry behavior, sensitive field redaction, and more.

Installation

pip install python-ai-tracer

Usage

from watchlog_ai_tracer import WatchlogTracer
import time

# Initialize tracer with your app name
tracer = WatchlogTracer(app="myapp")

# Start a new trace
tracer.start_trace()

# Root span
root_id = tracer.start_span("handle_request", metadata={"feature": "ai-summary"})

# Child span: validation
val_id = tracer.child_span(root_id, "validate_input")
# end validation span
tracer.end_span(val_id, {
    "tokens": 0,
    "cost": 0,
    "model": "",
    "provider": "",
    "input": "",
    "output": ""
})

# Child span: LLM call
llm_id = tracer.child_span(root_id, "call_llm")
# simulate work
time.sleep(0.5)
tracer.end_span(llm_id, {
    "tokens": 42,
    "cost": 0.002,
    "model": "gpt-4",
    "provider": "openai",
    "input": "Summarize: Hello world...",
    "output": "Hello world summary."
})

# End root span
tracer.end_span(root_id, {})

# Flush all spans to agent immediately
tracer.send()

API

WatchlogTracer(config)

• app (str, required): your application name.
• agent_url (str, optional): override the default agent endpoint.
• batch_size (int): number of spans per HTTP batch.
• flush_on_span_count (int): completed spans to auto-enqueue.
• auto_flush_interval (int): ms between background flushes.
• max_retries (int): HTTP retry attempts.
• max_queue_size (int): max spans to keep on disk.
• queue_item_ttl (int): TTL (ms) for queued spans.
• ... (see docstrings in __init__).

Methods

• start_trace() -> trace_id: begins a new trace.
• start_span(name, metadata={}) -> span_id: starts a new span.
• child_span(parent_id, name, metadata={}) -> span_id: shorthand for nested span.
• end_span(span_id, data={}): ends a span, records metrics.
• send(): ends any open spans, enqueues, and immediately flushes all spans to the agent.
• flush_queue(): manually trigger a background queue flush (async).

Configuration & Environment

The agent URL is determined in the following priority order:

1. Explicit config parameter: agent_url in WatchlogTracer initialization
2. Environment variable: WATCHLOG_AGENT_URL
3. Auto-detection:
   • Local: defaults to http://127.0.0.1:3774
   • Kubernetes: if running in K8s (service account & DNS check), auto-switches to http://watchlog-node-agent.monitoring.svc.cluster.local:3774

Examples

# Option 1: Pass agent_url directly
tracer = WatchlogTracer(
    app="myapp",
    agent_url="http://my-custom-agent:3774"
)

# Option 2: Use environment variable
# export WATCHLOG_AGENT_URL=http://my-custom-agent:3774
tracer = WatchlogTracer(app="myapp")

Contributing

PRs welcome! Please file issues on GitHub.

---

Documentation generated from version 1.0.0.