traceable-agent 2.1.0b1__tar.gz → 2.3.1__tar.gz

traceable_agent-2.3.1/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: traceable-agent
+Version: 2.3.1
+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
+```

traceable_agent-2.3.1/README.md

@@ -0,0 +1,272 @@
+# 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
+```

{traceable_agent-2.1.0b1 → traceable_agent-2.3.1}/setup.py

@@ -7,35 +7,22 @@ exec(open('src/traceableai/version.py').read())
 with open("README.md", "r", encoding="utf-8") as fh:
     long_description = fh.read()
 
-# Bundle pre-release vendor packages that aren't yet on PyPI.
-# These are fetched by scripts/fetch-vendor.sh before building.
-# We copy them under src/ and list them explicitly (they're namespace packages
-# so find_packages() won't discover them automatically).
-# Once they're published to PyPI, remove this block and add them
-# as versioned dependencies in extras_require['anthropic'] instead.
-import shutil
+# GenAI OpenTelemetry instrumentors ship in harness-sdk (see otel-python-sdk), not this wheel.
 
 _ROOT = os.path.dirname(os.path.abspath(__file__))
-
-_VENDOR_SRC = [
-    os.path.join(_ROOT, 'temporary-vendor', 'opentelemetry-instrumentation-anthropic', 'src', 'opentelemetry'),
-    os.path.join(_ROOT, 'temporary-vendor', 'opentelemetry-instrumentation-openai-v2', 'src', 'opentelemetry'),
-    os.path.join(_ROOT, 'temporary-vendor', 'opentelemetry-util-genai', 'src', 'opentelemetry'),
-]
-_VENDOR_DST = os.path.join(_ROOT, 'src', 'opentelemetry')
-
-for _src in _VENDOR_SRC:
-    if os.path.isdir(_src):
-        shutil.copytree(_src, _VENDOR_DST, dirs_exist_ok=True)
-
-# Collect all sub-packages with __init__.py from the merged destination
-# (namespace package roots like opentelemetry/ have no __init__.py and are excluded)
-_VENDOR_PACKAGES = []
-if os.path.isdir(_VENDOR_DST):
-    for _dirpath, _dirnames, _filenames in os.walk(_VENDOR_DST):
-        if '__init__.py' in _filenames:
-            _rel = os.path.relpath(_dirpath, os.path.join(_ROOT, 'src'))
-            _VENDOR_PACKAGES.append(_rel.replace(os.sep, '.'))
+_OTEL_PYTHON_SDK_PATH = os.path.join(_ROOT, 'otel-python-sdk')
+# Do not bake file:// paths into wheels (cibuildwheel uses /project/... at build time)
+# or into sdists uploaded to PyPI (Harness sets PYTHON_AGENT_RELEASE_BUILD=1).
+_USE_LOCAL_SDK_FOR_INSTALL = (
+    os.path.isdir(_OTEL_PYTHON_SDK_PATH)
+    and os.environ.get('CIBUILDWHEEL', '0') != '1'
+    and os.environ.get('PYTHON_AGENT_RELEASE_BUILD', '0') != '1'
+)
+_HARNESS_SDK_DEP = (
+    f"harness-sdk @ file://{os.path.abspath(_OTEL_PYTHON_SDK_PATH)}"
+    if _USE_LOCAL_SDK_FOR_INSTALL
+    else "harness-sdk>=0.1.0"
+)
 
 setup(
     name="traceable-agent",
@@ -48,7 +35,7 @@ setup(
         "Operating System :: OS Independent"
     ],
     package_dir={"": "src"},
-    packages=find_packages(where="src") + _VENDOR_PACKAGES,
+    packages=find_packages(where="src", include=["traceableai*"]),
     include_package_data=True,
     python_requires=">=3.10",
     ext_modules=[
@@ -60,6 +47,7 @@ setup(
         )
     ],
     install_requires=[
+        _HARNESS_SDK_DEP,
         "opentelemetry-api==1.41.1",
         "opentelemetry-exporter-otlp==1.41.1",
         "opentelemetry-instrumentation==0.62b1",
@@ -74,7 +62,6 @@ setup(
         "opentelemetry-instrumentation-httpx==0.62b1",
         "opentelemetry-instrumentation-grpc==0.62b1",
         "opentelemetry-instrumentation-django==0.62b1",
-        "opentelemetry-instrumentation-aws-lambda==0.62b1",
         "opentelemetry-instrumentation-mcp==0.60.0",
         "opentelemetry-semantic-conventions-ai>=0.5.1,<0.6.0",
         "opentelemetry-propagator-b3==1.41.1",
@@ -94,14 +81,15 @@ setup(
     entry_points={
         'console_scripts': [
             'traceableai-instrument = traceableai.autoinstrumentation.wrapper:run',
+            'harness-instrument = harness_sdk.autoinstrumentation.wrapper:run',
+        ],
+        'harness_sdk_control_plugin': [
+            'traceable = traceableai.plugins.traceable_control:factory',
         ],
     },
     extras_require={
         'anthropic': [
             'anthropic>=0.34.0',
-            # opentelemetry-util-genai and opentelemetry-instrumentation-anthropic
-            # are bundled directly (not yet on PyPI). When they are published,
-            # add them here as versioned deps and remove the bundle logic above.
         ],
         'openai': [
             'openai>=1.40.0',