Skip to main content

kindred-tracer

Kindred Tracer SDK for Python - Auto-instrumentation for AI agents.

This package uses OpenTelemetry HTTP client auto-instrumentation (httpx, requests) to capture outbound calls, categorizes them as LLM calls or tool executions, and exports logs to the Kindred log-search system (POST /api/logs/ingest).

Installation

pip install kindred-tracer

Or with optional dependencies:

pip install kindred-tracer[all]  # Includes requests support

Usage

Basic Usage

Just call kindred_tracer() once at startup, and all HTTP requests will be automatically intercepted and logged:

from kindred_tracer import kindred_tracer
import openai

# At startup - initialize the tracer
kindred_tracer()

# Your agent code here - no wrapping needed!
# All HTTP requests will be automatically logged
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Async Usage

Works the same way with async code:

import asyncio
from kindred_tracer import kindred_tracer
from openai import AsyncOpenAI

# Initialize once at startup
kindred_tracer()

async def main():
    # No wrapping needed - all requests are automatically logged
    client = AsyncOpenAI()
    response = await client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )

asyncio.run(main())

Configuration

Set the following environment variables:

  • KINDRED_API_KEY (required) - Your Kindred API key for authentication
  • KINDRED_API_URL (optional) - Base URL for Kindred API, defaults to https://api.usekindred.dev
  • KINDRED_SESSION_ID (optional) - Session identifier. If not set, a UUID will be auto-generated
  • KINDRED_AGENT_ID (optional) - Agent identifier
  • KINDRED_RUN_ID (optional) - Run identifier

You can also pass these values directly to kindred_tracer():

from kindred_tracer import kindred_tracer

# Initialize with explicit values
kindred_tracer(session_id='session-123', agent_id='agent-456', run_id='run-789')

How It Works

  1. Simple Initialization: Call kindred_tracer() once at startup to set session context and ensure instrumentation is active.

  2. Auto-instrumentation: OpenTelemetry instruments httpx and requests outbound calls (sync and async). This covers OpenAI SDK v1+ (uses httpx internally).

  3. Context: session_id, agent_id, and run_id are stored in contextvars and attached to HTTP spans so concurrent tasks stay isolated.

  4. Request Detection:

    • LLM Calls: Detected by hostname (e.g., api.openai.com, api.anthropic.com) → logged as role: "agent"
    • Tool Calls: Any other hostname → logged as role: "tool"
  5. Batch export: Spans are exported via OpenTelemetry BatchSpanProcessor (batched, non-blocking relative to your app code).

Log Format

Logs are automatically formatted and sent to ${KINDRED_API_URL}/api/logs/ingest with the following structure:

{
    "session_id": str,
    "timestamp": str,  # ISO 8601
    "role": "user" | "agent" | "tool" | "system",
    "content": str,
    "agent_id": str | None,
    "run_id": str | None,
    "meta": {
        "type": "llm_generation" | "tool_execution",
        "request_id": str,
        "host": str,
        "method": str,
        "path": str,
        "request_headers": dict,
        "request_body": str | None,
        "response_status": int | None,
        "response_headers": dict,
        "response_body": str | None,
        "duration_ms": float | None,
        "session_chain_id": str,  # OpenTelemetry trace id (hex)
        "log_id": str,             # OpenTelemetry span id (hex)
        "parent_id": str | None,   # Parent span id when present
        "tool_calls": list | None,  # Extracted from OpenAI JSON responses when safe
    }
}

Flushing Logs

Before shutting down your application, you can flush any pending logs:

from kindred_tracer import flush

# On shutdown
flush()

Security

The tracer automatically sanitizes sensitive headers before logging:

  • Authorization
  • x-api-key
  • api-key
  • x-auth-token
  • cookie

Supported LLM Providers

The tracer automatically detects requests to:

  • OpenAI (api.openai.com)
  • Anthropic (api.anthropic.com)
  • Google Gemini (generativelanguage.googleapis.com)
  • Cohere (api.cohere.com)
  • Mistral (api.mistral.ai)

Example

Here's a complete example:

from kindred_tracer import kindred_tracer, flush
import openai
import os

# Set your API key
os.environ['KINDRED_API_KEY'] = 'your-api-key-here'

# Initialize the tracer (reads session_id from KINDRED_SESSION_ID env var, or auto-generates)
kindred_tracer()

# Your agent code - all HTTP requests are automatically logged
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Before shutdown, flush any pending logs
flush()

Requirements

  • Python 3.10+
  • httpx>=0.24.0 (ingest transport)
  • opentelemetry-api, opentelemetry-sdk
  • opentelemetry-instrumentation-httpx, opentelemetry-instrumentation-requests

License

MIT

Metadata

Release files for kindred-tracer 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kindred-tracer 1.1.0
File Size Uploaded Provenance Actions
kindred_tracer-1.1.0.tar.gz 12.3 kB Without provenance Details for kindred_tracer-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kindred-tracer 1.1.0
File Interpreter ABI Platform Actions
kindred_tracer-1.1.0-py3-none-any.whl Python 3 none any Details for kindred_tracer-1.1.0-py3-none-any.whl

Total release size: 24.8 kB

Release files / kindred_tracer-1.1.0.tar.gz

Download URL kindred_tracer-1.1.0.tar.gz
Size 12.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f223b25c336efdd45ca4c253c68bce7092f6dfef41f46d715768b73db7e5ef3e
BLAKE2b-256 checksum
How to use checksums
a6d784a5fea07d6af21aa0b04e04375c262d1e85cdbf7e3d3532c717adbdc5a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / kindred_tracer-1.1.0-py3-none-any.whl

Download URL kindred_tracer-1.1.0-py3-none-any.whl
Size 12.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
13ae0cf3d65252c131788a0c29ecb7728587089d7b63c9285ac1ce48cc339fb3
BLAKE2b-256 checksum
How to use checksums
1dd61524babf8a045111ad30c220199a3217348eca9f0982367ed0d8df819075
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Security for kindred-tracer 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page