forgesight-datadog 0.1.0__tar.gz

forgesight_datadog-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_datadog-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: forgesight-datadog
+Version: 0.1.0
+Summary: ForgeSight Datadog exporter — DD-native APM spans + cost metric, via DD Agent or OTLP intake.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,apm,datadog,ddtrace,forgesight,observability
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: ddtrace>=2
+Requires-Dist: forgesight-core
+Requires-Dist: forgesight-otel
+Description-Content-Type: text/markdown
+
+# forgesight-datadog
+
+The Datadog exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Surfaces agent telemetry in **Datadog APM** with the unified `service` / `env` / `version`
+tags, LLM / tool / MCP calls as child spans, and the SDK's **computed cost** as the
+monitorable DD metric `forgesight.cost_usd` — the same number every other backend reports.
+
+```bash
+pip install forgesight-datadog
+```
+
+```python
+import forgesight
+from forgesight_datadog import DatadogExporter
+
+forgesight.configure(exporters=[
+    DatadogExporter(api_key="...", site="datadoghq.com",
+                    service="issue-classifier", env="prod"),
+])
+```
+
+Or by name: `exporters: [{name: datadog, config: {api_key: "${DD_API_KEY}", service: ...}}]`.
+
+## Two transports
+
+- **`agent`** (default) — maps each record to a DD APM span via `ddtrace` and writes it to a
+  local DD Agent (`agent_endpoint: http://datadog-agent:8126`), plus emits cost/token DD
+  metrics. Direct intake (no `agent_endpoint`) requires `api_key`.
+- **`otlp`** — sends OTLP/HTTP to the DD Agent's OTLP port (`agent_endpoint: http://datadog-agent:4318`)
+  with the DD unified tags applied as resource attributes. Reuses `forgesight-otel`.
+
+A DD Agent / intake outage makes `export()` return `FAILURE` (counted, never raised — P6);
+it never blocks the agent. Prompt/response content is attached only with
+`capture_content=True` (off by default, P7).
+
+## OTLP-native backends need **no package**
+
+Because the domain model maps cleanly onto the OTel GenAI conventions, anything that ingests
+OTLP works through `forgesight-otel` with **no dedicated package** — point it at the backend
+and you're done:
+
+| Backend | How to send |
+|---|---|
+| Honeycomb | `forgesight-otel` → `api.honeycomb.io:443` + `x-honeycomb-team` header |
+| Jaeger / Tempo / SigNoz | `forgesight-otel` → its OTLP collector |
+| New Relic | `forgesight-otel` → `otlp.nr-data.net:4317` + `api-key` header |
+| AWS X-Ray | `forgesight-otel` → ADOT collector |
+| Arize Phoenix | `forgesight-otel` → Phoenix OTLP endpoint |
+
+Datadog earns a package **only** because its richest path (DD-native APM tagging +
+cost-as-DD-metric) is DD-specific. A team that only wants generic spans in Datadog can use
+the OTLP path and skip this package entirely.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `api_key` | `DD_API_KEY` / `FORGESIGHT_DATADOG_API_KEY` | — (required for direct intake) |
+| `site` | `DD_SITE` / `FORGESIGHT_DATADOG_SITE` | `datadoghq.com` |
+| `service` | `DD_SERVICE` / `FORGESIGHT_DATADOG_SERVICE` | `agentforge` |
+| `env` | `DD_ENV` / `FORGESIGHT_DATADOG_ENV` | — |
+| `version` | `DD_VERSION` / `FORGESIGHT_DATADOG_VERSION` | — |
+| `agent_endpoint` | `FORGESIGHT_DATADOG_AGENT_ENDPOINT` | — |
+| `transport` | `FORGESIGHT_DATADOG_TRANSPORT` | `agent` |
+
+Constructor kwargs win over env (FR-12).
+
+## License
+
+Apache-2.0

forgesight_datadog-0.1.0/README.md

@@ -0,0 +1,70 @@
+# forgesight-datadog
+
+The Datadog exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Surfaces agent telemetry in **Datadog APM** with the unified `service` / `env` / `version`
+tags, LLM / tool / MCP calls as child spans, and the SDK's **computed cost** as the
+monitorable DD metric `forgesight.cost_usd` — the same number every other backend reports.
+
+```bash
+pip install forgesight-datadog
+```
+
+```python
+import forgesight
+from forgesight_datadog import DatadogExporter
+
+forgesight.configure(exporters=[
+    DatadogExporter(api_key="...", site="datadoghq.com",
+                    service="issue-classifier", env="prod"),
+])
+```
+
+Or by name: `exporters: [{name: datadog, config: {api_key: "${DD_API_KEY}", service: ...}}]`.
+
+## Two transports
+
+- **`agent`** (default) — maps each record to a DD APM span via `ddtrace` and writes it to a
+  local DD Agent (`agent_endpoint: http://datadog-agent:8126`), plus emits cost/token DD
+  metrics. Direct intake (no `agent_endpoint`) requires `api_key`.
+- **`otlp`** — sends OTLP/HTTP to the DD Agent's OTLP port (`agent_endpoint: http://datadog-agent:4318`)
+  with the DD unified tags applied as resource attributes. Reuses `forgesight-otel`.
+
+A DD Agent / intake outage makes `export()` return `FAILURE` (counted, never raised — P6);
+it never blocks the agent. Prompt/response content is attached only with
+`capture_content=True` (off by default, P7).
+
+## OTLP-native backends need **no package**
+
+Because the domain model maps cleanly onto the OTel GenAI conventions, anything that ingests
+OTLP works through `forgesight-otel` with **no dedicated package** — point it at the backend
+and you're done:
+
+| Backend | How to send |
+|---|---|
+| Honeycomb | `forgesight-otel` → `api.honeycomb.io:443` + `x-honeycomb-team` header |
+| Jaeger / Tempo / SigNoz | `forgesight-otel` → its OTLP collector |
+| New Relic | `forgesight-otel` → `otlp.nr-data.net:4317` + `api-key` header |
+| AWS X-Ray | `forgesight-otel` → ADOT collector |
+| Arize Phoenix | `forgesight-otel` → Phoenix OTLP endpoint |
+
+Datadog earns a package **only** because its richest path (DD-native APM tagging +
+cost-as-DD-metric) is DD-specific. A team that only wants generic spans in Datadog can use
+the OTLP path and skip this package entirely.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `api_key` | `DD_API_KEY` / `FORGESIGHT_DATADOG_API_KEY` | — (required for direct intake) |
+| `site` | `DD_SITE` / `FORGESIGHT_DATADOG_SITE` | `datadoghq.com` |
+| `service` | `DD_SERVICE` / `FORGESIGHT_DATADOG_SERVICE` | `agentforge` |
+| `env` | `DD_ENV` / `FORGESIGHT_DATADOG_ENV` | — |
+| `version` | `DD_VERSION` / `FORGESIGHT_DATADOG_VERSION` | — |
+| `agent_endpoint` | `FORGESIGHT_DATADOG_AGENT_ENDPOINT` | — |
+| `transport` | `FORGESIGHT_DATADOG_TRANSPORT` | `agent` |
+
+Constructor kwargs win over env (FR-12).
+
+## License
+
+Apache-2.0

forgesight_datadog-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "forgesight-datadog"
+version = "0.1.0"
+description = "ForgeSight Datadog exporter — DD-native APM spans + cost metric, via DD Agent or OTLP intake."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "datadog", "apm", "ai-agents", "forgesight", "ddtrace"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core", "forgesight-otel", "ddtrace>=2"]
+
+[project.entry-points."forgesight.exporters"]
+datadog = "forgesight_datadog.exporter:DatadogExporter"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_datadog"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }
+forgesight-otel = { workspace = true }

forgesight_datadog-0.1.0/src/forgesight_datadog/__init__.py

@@ -0,0 +1,34 @@
+"""ForgeSight Datadog exporter — DD-native APM spans + cost metric (DD Agent or OTLP)."""
+
+from __future__ import annotations
+
+from .exporter import (
+    COST_METRIC,
+    DD_SITES,
+    OTLP_NATIVE_BACKENDS,
+    TOKENS_METRIC,
+    DatadogExporter,
+    DatadogMetricSink,
+    DatadogSpan,
+    DatadogSpanWriter,
+    record_to_span,
+)
+from .testing import InMemoryDatadogMetricSink, InMemoryDatadogSpanWriter, MetricCall
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "COST_METRIC",
+    "DD_SITES",
+    "OTLP_NATIVE_BACKENDS",
+    "TOKENS_METRIC",
+    "DatadogExporter",
+    "DatadogMetricSink",
+    "DatadogSpan",
+    "DatadogSpanWriter",
+    "InMemoryDatadogMetricSink",
+    "InMemoryDatadogSpanWriter",
+    "MetricCall",
+    "__version__",
+    "record_to_span",
+]

forgesight_datadog-0.1.0/src/forgesight_datadog/_ddtrace.py

@@ -0,0 +1,95 @@
+"""Vendor-backed defaults for the ``agent`` transport — ``ddtrace`` + dogstatsd.
+
+These touch the live Datadog SDK / Agent, so they are exercised only against a real DD
+Agent (every line is ``pragma: no cover``). The pure record→span mapping lives in
+:mod:`forgesight_datadog.exporter` and is fully unit-tested via injected doubles; this
+module is the thin edge that pushes a mapped :class:`DatadogSpan` onto a ``ddtrace`` span
+and a DD metric onto dogstatsd.
+
+Vendor access goes through an ``Any``-typed dynamic boundary on purpose: the package
+supports ``ddtrace>=2`` and the exact span/writer API drifts across major versions, so we
+resolve it at runtime (against whatever ``ddtrace`` is installed) rather than pinning to
+one version's symbols at type-check time.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+from collections.abc import Sequence
+from typing import Any
+
+from .exporter import DatadogSpan
+
+_DD_64BIT_MASK = (1 << 64) - 1
+_NANOS_PER_S = 1_000_000_000
+
+
+class DDTraceSpanWriter:  # pragma: no cover - requires a live DD Agent
+    """Writes mapped spans to a DD Agent via ``ddtrace``'s public tracer."""
+
+    def __init__(
+        self,
+        *,
+        service: str,
+        api_key: str | None,
+        site: str,
+        agent_endpoint: str | None,
+    ) -> None:
+        trace_mod: Any = importlib.import_module("ddtrace.trace")
+        self._tracer: Any = trace_mod.tracer
+        if agent_endpoint:
+            # best-effort; the tracer falls back to its default agent url
+            with contextlib.suppress(Exception):
+                self._tracer.configure(hostname=None, port=None, url=agent_endpoint)
+        self._service = service
+
+    def write(self, span: DatadogSpan) -> None:
+        dd = self._tracer.start_span(
+            span.name, service=span.service, resource=span.resource, activate=False
+        )
+        dd.trace_id = int(span.trace_id, 16)
+        dd.span_id = int(span.span_id, 16) & _DD_64BIT_MASK
+        if span.parent_id:
+            dd.parent_id = int(span.parent_id, 16) & _DD_64BIT_MASK
+        dd.start_ns = span.start_ns
+        dd.error = span.error
+        for key, tag in span.meta.items():
+            dd.set_tag(key, tag)
+        for key, metric in span.metrics.items():
+            dd.set_metric(key, metric)
+        dd.finish(finish_time=(span.start_ns + span.duration_ns) / _NANOS_PER_S)
+
+    def flush(self) -> bool:
+        flush = getattr(self._tracer, "flush", None)
+        if not callable(flush):
+            return True
+        try:
+            flush()
+        except Exception:
+            return False
+        return True
+
+    def stop(self) -> None:
+        shutdown = getattr(self._tracer, "shutdown", None)
+        if callable(shutdown):
+            shutdown()
+
+
+class DogStatsdMetricSink:  # pragma: no cover - requires a live DD Agent / dogstatsd
+    """Emits DD metrics (cost / tokens) to dogstatsd via the DD Agent."""
+
+    def __init__(self, *, agent_endpoint: str | None) -> None:
+        dogstatsd_mod: Any = importlib.import_module("ddtrace.internal.dogstatsd")
+        host = "localhost"
+        if agent_endpoint:
+            host = agent_endpoint.split("://", 1)[-1].split(":", 1)[0]
+        self._client: Any = dogstatsd_mod.get_dogstatsd_client(f"udp://{host}:8125")
+
+    def emit(self, name: str, value: float, tags: Sequence[str]) -> None:
+        self._client.distribution(name, value, tags=list(tags))
+
+    def close(self) -> None:
+        close = getattr(self._client, "close", None)
+        if callable(close):
+            close()