Python Agent

This repository ships two related packages:

The SDK lives in otel-python-sdk/. The Traceable wrapper and native filter are under src/traceableai/.

Requirements: Python >= 3.10

Supported OS for libtraceable (blocking filter): Ubuntu 18.04+, CentOS 7+, Debian 10+, Amazon Linux 2+

Installation

Local development (both packages)

python3 -m venv venv
source venv/bin/activate

# Vendor GenAI instrumentation (needed for anthropic/openai tests and builds)
bash scripts/fetch-vendor.sh
python3 otel-python-sdk/scripts/bundle_vendor.py

# Editable SDK + Traceable agent
pip install -e "./otel-python-sdk[dev]"
pip install -r requirements.txt -r dev-requirements.txt
pip install -e .

Optional GenAI extras:

pip install -e "./otel-python-sdk[anthropic,openai,litellm]"

If grpc fails to compile, prepend: GRPC_PYTHON_BUILD_SYSTEM_ZLIB=true

Production install

pip install harness-sdk          # SDK only
pip install traceable-agent          # SDK + Traceable (includes libtraceable on supported Linux)

Configuration

Configuration is layered: defaults → YAML file → environment variables. Use separate files for SDK vs Traceable-specific settings.

Legacy aliases AT_CONFIG_FILE / AT_* are still read for SDK settings during migration.

SDK config (HA_CONFIG_FILE)

Example agent-config.yaml:

service_name: my-service
enabled: true

reporting:
  endpoint: http://localhost:4318/v1/traces
  trace_reporter_type: OTLP   # or ZIPKIN
  secure: false
  token: ""

data_capture:
  http_headers:
    request: true
    response: true
  http_body:
    request: true
    response: true
  body_max_size_bytes: 131072

propagation_formats: ["TRACECONTEXT", "B3"]

gen_ai:
  enabled: true
  payload_capture_enabled: true
  payload_evaluation_enabled: true

plugins:
  control: []                # e.g. custom control plugins by name
  observability:
    - builtin_pipeline
    - builtin_span_attributes

Point the agent at the file:

export HA_CONFIG_FILE=/path/to/agent-config.yaml

Common environment overrides:

export HA_SERVICE_NAME=my-service
export HA_REPORTING_ENDPOINT=http://otel-collector:4318/v1/traces
export HA_REPORTING_TRACE_REPORTER_TYPE=OTLP
export HA_ENABLED=true
export HA_GEN_AI_ENABLED=true
export HA_CONTROL_PLUGINS=traceable   # comma-separated control plugin names
export HA_ENABLE_CONSOLE_SPAN_EXPORTER=true   # dev only: print spans to stdout

Traceable config (TA_CONFIG_FILE)

Example traceable-config.yaml:

blocking_config:
  enabled: true
  evaluate_body: true
  max_recursion_depth: 20

remote_config:
  enabled: true
  endpoint: localhost:5442
  poll_period_seconds: 30

sampling:
  enabled: false

export TA_CONFIG_FILE=/path/to/traceable-config.yaml
export TA_REMOTE_CONFIG_ENABLED=false    # disable remote config polling in dev/tests

For integration tests, see test/traceableai/agent/integration-agent-config.yaml and test/traceableai/agent/traceable-integration-config.yaml.

Usage

SDK only (harness_sdk)

Use when you want instrumentation and OTLP/ZIPKIN export without Traceable blocking or remote config.

Code-based instrumentation

from harness_sdk.agent import Agent

app = Flask(__name__)

agent = Agent()
agent.instrument(app)   # Flask + other supported libraries

Auto-instrumentation

export HA_CONFIG_FILE=/path/to/agent-config.yaml
harness-instrument flask run -p 5000

Traceable agent (traceableai)

Use for production Traceable deployments (blocking, remote config, libtraceable).

Code-based instrumentation

from traceableai.agent import Agent

app = Flask(__name__)

agent = Agent()
agent.instrument(app)

# Prefer plugins.control in HA_CONFIG_FILE; this remains for backward compatibility:
agent.add_traceable_filter()

Recommended: enable the Traceable control plugin via config instead of calling add_traceable_filter():

# agent-config.yaml (HA_CONFIG_FILE)
plugins:
  control:
    - traceable

Auto-instrumentation

export HA_CONFIG_FILE=/path/to/agent-config.yaml
export TA_CONFIG_FILE=/path/to/traceable-config.yaml
traceableai-instrument flask run -p 5000

traceableai-instrument loads sitecustomize, starts the agent, auto-instruments supported libraries, and registers the Traceable control plugin (unless deferred for gunicorn post-fork).

Developing

python3 -m venv venv
source venv/bin/activate
bash scripts/fetch-vendor.sh
python3 otel-python-sdk/scripts/bundle_vendor.py
pip install -e "./otel-python-sdk[dev,anthropic,openai,litellm]"
pip install -r requirements.txt -r dev-requirements.txt
pip install -e .

Testing

SDK unit tests (matches CI “SDK Unit Tests”):

./scripts/run-sdk-unit-tests.sh
# Full integration tests (mysql/postgres/docker):
RUN_SDK_INTEGRATION_TESTS=1 ./scripts/run-sdk-unit-tests.sh

Traceable unit tests (from repo root; skips native filter and duplicate instrumentation tree):

python3 -m pytest \
  --ignore=test/traceableai/agent/instrumentation

Integration services (optional):

cd test/externalServices && docker compose up -d

Building

pip install -r requirements.txt
python3 -m build
# Or all wheel variants:
# CIBW_SKIP="*37* *38* ..." ./build_artifacts.sh

Docker-based unit test image (legacy):

docker build -f docker/test_apps/unittest.Dockerfile -t pythonunittest .
docker run --rm pythonunittest

Updating libtraceable

1. Update filter/libtraceable.h if the header changed.
2. Edit ./src/download.py and bump LIBTRACEABLE_VERSION.
3. Verify with a test app under docker/test_apps/.

Updating protos

git submodule update --init --recursive
./scripts/build_proto.sh