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 authenticationKINDRED_API_URL(optional) - Base URL for Kindred API, defaults tohttps://api.usekindred.devKINDRED_SESSION_ID(optional) - Session identifier. If not set, a UUID will be auto-generatedKINDRED_AGENT_ID(optional) - Agent identifierKINDRED_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
-
Simple Initialization: Call
kindred_tracer()once at startup to set session context and ensure instrumentation is active. -
Auto-instrumentation: OpenTelemetry instruments
httpxandrequestsoutbound calls (sync and async). This covers OpenAI SDK v1+ (useshttpxinternally). -
Context:
session_id,agent_id, andrun_idare stored incontextvarsand attached to HTTP spans so concurrent tasks stay isolated. -
Request Detection:
- LLM Calls: Detected by hostname (e.g.,
api.openai.com,api.anthropic.com) → logged asrole: "agent" - Tool Calls: Any other hostname → logged as
role: "tool"
- LLM Calls: Detected by hostname (e.g.,
-
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:
Authorizationx-api-keyapi-keyx-auth-tokencookie
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-sdkopentelemetry-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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.