Metadata-Version: 2.4
Name: traceable-agent
Version: 2.3.0
Summary: Traceable.ai Python Agent
Home-page: https://traceable.ai
Author: Traceable.ai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: harness-sdk>=0.1.0
Requires-Dist: opentelemetry-api==1.41.1
Requires-Dist: opentelemetry-exporter-otlp==1.41.1
Requires-Dist: opentelemetry-instrumentation==0.62b1
Requires-Dist: opentelemetry-instrumentation-aiohttp-client==0.62b1
Requires-Dist: opentelemetry-instrumentation-botocore==0.62b1
Requires-Dist: opentelemetry-instrumentation-wsgi==0.62b1
Requires-Dist: opentelemetry-instrumentation-fastapi==0.62b1
Requires-Dist: opentelemetry-instrumentation-flask==0.62b1
Requires-Dist: opentelemetry-instrumentation-mysql==0.62b1
Requires-Dist: opentelemetry-instrumentation-psycopg2==0.62b1
Requires-Dist: opentelemetry-instrumentation-requests==0.62b1
Requires-Dist: opentelemetry-instrumentation-httpx==0.62b1
Requires-Dist: opentelemetry-instrumentation-grpc==0.62b1
Requires-Dist: opentelemetry-instrumentation-django==0.62b1
Requires-Dist: opentelemetry-instrumentation-mcp==0.60.0
Requires-Dist: opentelemetry-semantic-conventions-ai<0.6.0,>=0.5.1
Requires-Dist: opentelemetry-propagator-b3==1.41.1
Requires-Dist: opentelemetry-proto==1.41.1
Requires-Dist: opentelemetry-sdk==1.41.1
Requires-Dist: opentelemetry-util-http==0.62b1
Requires-Dist: google>=3.0.0
Requires-Dist: pyyaml
Requires-Dist: protobuf
Requires-Dist: psutil
Requires-Dist: distro
Requires-Dist: cffi
Requires-Dist: setuptools
Requires-Dist: jaraco.text
Requires-Dist: platformdirs
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.40.0; extra == "openai"
Provides-Extra: litellm
Requires-Dist: litellm>=1.60.0; extra == "litellm"
Dynamic: author
Dynamic: classifier
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Python Agent

This repository ships two related packages:

| Package | PyPI name | Import | Role |
|---------|-----------|--------|------|
| **otel-python-sdk** | `harness-sdk` | `harness_sdk` | Generic OpenTelemetry-based instrumentation SDK (HTTP, gRPC, DB, GenAI, plugins). |
| **Traceable agent** | `traceable-agent` | `traceableai` | Extends the SDK with Traceable blocking (`libtraceable`), remote config, and sampling. Depends on `harness-sdk`. |

The SDK lives in [`otel-python-sdk/`](otel-python-sdk/). The Traceable wrapper and native filter are under [`src/traceableai/`](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)

```bash
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:

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

If `grpc` fails to compile, prepend: `GRPC_PYTHON_BUILD_SYSTEM_ZLIB=true`

### Production install

```bash
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.

| Setting | Config file env | Prefix | Examples |
|---------|-----------------|--------|----------|
| SDK (instrumentation, reporting, GenAI, plugins) | `HA_CONFIG_FILE` | `HA_*` | `HA_SERVICE_NAME`, `HA_REPORTING_ENDPOINT`, `HA_CONTROL_PLUGINS` |
| Traceable (blocking, remote config, sampling) | `TA_CONFIG_FILE` | `TA_*` | `TA_BLOCKING_CONFIG_ENABLED`, `TA_REMOTE_CONFIG_ENABLED` |

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

### SDK config (`HA_CONFIG_FILE`)

Example `agent-config.yaml`:

```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:

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

Common environment overrides:

```bash
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`:

```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
```

```bash
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`](test/traceableai/agent/integration-agent-config.yaml) and [`test/traceableai/agent/traceable-integration-config.yaml`](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**

```python
from harness_sdk.agent import Agent

app = Flask(__name__)

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

**Auto-instrumentation**

```bash
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**

```python
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()`:

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

**Auto-instrumentation**

```bash
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

```bash
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”):

```bash
./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):

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

Integration services (optional):

```bash
cd test/externalServices && docker compose up -d
```

### Building

```bash
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):

```bash
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

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