traceable-agent 2.0.1__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.3.1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+
+]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["test"]
+
+[tool.pylint.messages_control]
+disable = ["trailing-whitespace"]
+

traceable_agent-2.3.1/setup.py

@@ -0,0 +1,101 @@
+# pylint: skip-file
+import os
+from setuptools import setup, find_packages, Extension
+
+exec(open('src/traceableai/version.py').read())
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+# GenAI OpenTelemetry instrumentors ship in harness-sdk (see otel-python-sdk), not this wheel.
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+_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",
+    version=__version__,
+    author="Traceable.ai",
+    description="Traceable.ai Python Agent",
+    url="https://traceable.ai",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent"
+    ],
+    package_dir={"": "src"},
+    packages=find_packages(where="src", include=["traceableai*"]),
+    include_package_data=True,
+    python_requires=">=3.10",
+    ext_modules=[
+        # this option will let wheel builder know to package c extensions when ran from CI. No effect for source tar installs
+        Extension(
+            name='traceableai.filter._libtraceable',
+            sources=[],
+            optional=os.environ.get('CIBUILDWHEEL', '0') != '1'
+        )
+    ],
+    install_requires=[
+        _HARNESS_SDK_DEP,
+        "opentelemetry-api==1.41.1",
+        "opentelemetry-exporter-otlp==1.41.1",
+        "opentelemetry-instrumentation==0.62b1",
+        "opentelemetry-instrumentation-aiohttp-client==0.62b1",
+        "opentelemetry-instrumentation-botocore==0.62b1",
+        "opentelemetry-instrumentation-wsgi==0.62b1",
+        "opentelemetry-instrumentation-fastapi==0.62b1",
+        "opentelemetry-instrumentation-flask==0.62b1",
+        "opentelemetry-instrumentation-mysql==0.62b1",
+        "opentelemetry-instrumentation-psycopg2==0.62b1",
+        "opentelemetry-instrumentation-requests==0.62b1",
+        "opentelemetry-instrumentation-httpx==0.62b1",
+        "opentelemetry-instrumentation-grpc==0.62b1",
+        "opentelemetry-instrumentation-django==0.62b1",
+        "opentelemetry-instrumentation-mcp==0.60.0",
+        "opentelemetry-semantic-conventions-ai>=0.5.1,<0.6.0",
+        "opentelemetry-propagator-b3==1.41.1",
+        "opentelemetry-proto==1.41.1",
+        "opentelemetry-sdk==1.41.1",
+        "opentelemetry-util-http==0.62b1",
+        "google>=3.0.0",
+        "pyyaml",
+        "protobuf",
+        "psutil",
+        "distro",
+        "cffi",
+        "setuptools",
+        "jaraco.text",
+        "platformdirs"
+    ],
+    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',
+        ],
+        'openai': [
+            'openai>=1.40.0',
+        ],
+        'litellm': [
+            'litellm>=1.60.0',
+        ],
+    },
+)