forgesight-datadog 0.1.0__py3-none-any.whl

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/_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()

forgesight_datadog/exporter.py

@@ -0,0 +1,510 @@
+"""``DatadogExporter`` — ForgeSight records → Datadog APM spans + DD metrics.
+
+A :class:`~forgesight_api.TelemetryExporter` (so it resolves via the
+``forgesight.exporters`` entry point and passes the conformance suite) that surfaces
+agent telemetry in Datadog with the unified ``service`` / ``env`` / ``version`` tags, the
+SDK's computed cost as the monitorable DD metric ``forgesight.cost_usd``, and LLM / tool /
+MCP calls as child APM spans.
+
+Two transports:
+
+* ``"agent"`` (default) maps each record to a :class:`DatadogSpan` and hands it to a
+  :class:`DatadogSpanWriter` (a ``ddtrace`` writer to a local DD Agent by default), plus
+  emits cost/token DD metrics via a :class:`DatadogMetricSink`. The vendor-backed default
+  writer/sink are built lazily; tests inject doubles.
+* ``"otlp"`` reuses ``forgesight-otel``'s :class:`~forgesight_otel.OTelExporter` pointed at
+  the DD Agent's OTLP port (or DD's OTLP intake), with the DD unified tags applied as
+  resource attributes Datadog reads.
+
+``export`` never raises (P6): a DD Agent / intake outage returns ``ExportResult.FAILURE``,
+counted by the pipeline, invisible to the agent. Content is attached only when
+``capture_content`` is on (P7). Runs on the export worker, never the hot path.
+
+**OTLP-native backends need no package.** Honeycomb / Jaeger / Tempo / SigNoz / New Relic /
+X-Ray / Phoenix all ingest OTLP — point ``forgesight-otel`` at them (see
+:data:`OTLP_NATIVE_BACKENDS`). Datadog earns a package only because its richest path is
+DD-specific.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Protocol, runtime_checkable
+
+from forgesight_api import ExportResult, Kind, Record, RunStatus
+
+_log = logging.getLogger("forgesight.datadog")
+
+DEFAULT_SERVICE = "agentforge"
+DEFAULT_SITE = "datadoghq.com"
+DEFAULT_DD_AGENT_OTLP = "http://localhost:4317"
+
+# Datadog sites a team may point at (architecture.md §4.5).
+DD_SITES = frozenset(
+    {
+        "datadoghq.com",
+        "us3.datadoghq.com",
+        "us5.datadoghq.com",
+        "datadoghq.eu",
+        "ap1.datadoghq.com",
+        "ddog-gov.com",
+    }
+)
+
+# The keystone, stated once: these ingest OTLP and need NO dedicated package — point
+# forgesight-otel at them. Datadog is the deliberate exception (its richest path is
+# DD-specific), which is why this package exists.
+OTLP_NATIVE_BACKENDS: Mapping[str, str] = MappingProxyType(
+    {
+        "honeycomb": "forgesight-otel -> api.honeycomb.io:443 + x-honeycomb-team header",
+        "jaeger": "forgesight-otel -> Jaeger OTLP :4317",
+        "tempo": "forgesight-otel -> Grafana Tempo OTLP endpoint",
+        "signoz": "forgesight-otel -> SigNoz OTLP collector",
+        "newrelic": "forgesight-otel -> otlp.nr-data.net:4317 + api-key header",
+        "xray": "forgesight-otel -> AWS Distro for OpenTelemetry (ADOT) collector",
+        "phoenix": "forgesight-otel -> Arize Phoenix OTLP endpoint",
+    }
+)
+
+_OP_INVOKE_AGENT = "invoke_agent"
+_OP_INVOKE_WORKFLOW = "invoke_workflow"
+_OP_CHAT = "chat"
+_OP_EXECUTE_TOOL = "execute_tool"
+_MCP_TOOLS_CALL = "tools/call"
+
+_AGENT_VERSION_KEY = "agent.version"
+_PARENT_RUN_ID_KEY = "parent.run_id"
+_CONTEXT_ID_KEY = "context.id"
+_STRUCTURED_KEYS = frozenset({_AGENT_VERSION_KEY, _PARENT_RUN_ID_KEY, _CONTEXT_ID_KEY})
+
+_OK_STATUSES = frozenset({RunStatus.OK, RunStatus.RUNNING})
+
+# DD APM operation names per kind (span.name; the detail goes in span.resource).
+_DD_SPAN_NAME: Mapping[Kind, str] = {
+    Kind.AGENT: "forgesight.agent",
+    Kind.WORKFLOW: "forgesight.workflow",
+    Kind.STEP: "forgesight.step",
+    Kind.LLM: "forgesight.llm",
+    Kind.TOOL: "forgesight.tool",
+    Kind.MCP: "forgesight.mcp",
+}
+
+COST_METRIC = "forgesight.cost_usd"
+TOKENS_METRIC = "forgesight.tokens"
+
+
+@dataclass(frozen=True)
+class DatadogSpan:
+    """A backend-neutral DD APM span — the seam between mapping and the ``ddtrace`` writer."""
+
+    trace_id: str  # W3C hex trace id (the writer narrows to DD's id space)
+    span_id: str
+    parent_id: str | None
+    name: str  # DD operation name
+    resource: str  # DD resource (agent_name / model / tool / method)
+    service: str
+    start_ns: int
+    duration_ns: int
+    error: int  # 1 on a failed op, else 0
+    meta: dict[str, str]  # string tags
+    metrics: dict[str, float]  # numeric tags
+
+
+@runtime_checkable
+class DatadogSpanWriter(Protocol):
+    """Submits mapped spans to Datadog (``ddtrace`` writer → DD Agent by default)."""
+
+    def write(self, span: DatadogSpan) -> None: ...
+
+    def flush(self) -> bool: ...
+
+    def stop(self) -> None: ...
+
+
+@runtime_checkable
+class DatadogMetricSink(Protocol):
+    """Emits DD metrics (cost / tokens) — dogstatsd via the DD Agent by default."""
+
+    def emit(self, name: str, value: float, tags: Sequence[str]) -> None: ...
+
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class _Sink(Protocol):
+    """The transport-specific delivery surface DatadogExporter delegates to."""
+
+    def export(self, records: Sequence[Record]) -> ExportResult: ...
+
+    def force_flush(self, timeout_millis: int) -> bool: ...
+
+    def shutdown(self, timeout_millis: int) -> None: ...
+
+
+def _env(*keys: str) -> str | None:
+    for key in keys:
+        value = os.environ.get(key)
+        if value:
+            return value
+    return None
+
+
+def _env_bool(key: str, default: bool) -> bool:
+    raw = os.environ.get(key)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+class DatadogExporter:
+    """Maps SDK records → Datadog APM spans + DD metrics (incl. cost). Stable from v0.2."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        site: str = DEFAULT_SITE,
+        service: str = DEFAULT_SERVICE,
+        env: str | None = None,
+        version: str | None = None,
+        agent_endpoint: str | None = None,
+        transport: str = "agent",
+        capture_content: bool = False,
+        span_writer: DatadogSpanWriter | None = None,
+        metric_sink: DatadogMetricSink | None = None,
+        span_exporter: object | None = None,
+    ) -> None:
+        self._api_key = (
+            api_key if api_key is not None else _env("DD_API_KEY", "FORGESIGHT_DATADOG_API_KEY")
+        )
+        self._site = (
+            site
+            if site != DEFAULT_SITE
+            else (_env("DD_SITE", "FORGESIGHT_DATADOG_SITE") or DEFAULT_SITE)
+        )
+        if self._site not in DD_SITES:
+            raise ValueError(
+                f"unknown Datadog site {self._site!r}; expected one of {sorted(DD_SITES)}"
+            )
+        self._service = (
+            service
+            if service != DEFAULT_SERVICE
+            else (_env("DD_SERVICE", "FORGESIGHT_DATADOG_SERVICE") or DEFAULT_SERVICE)
+        )
+        self._env = env if env is not None else _env("DD_ENV", "FORGESIGHT_DATADOG_ENV")
+        self._version = (
+            version if version is not None else _env("DD_VERSION", "FORGESIGHT_DATADOG_VERSION")
+        )
+        self._agent_endpoint = (
+            agent_endpoint
+            if agent_endpoint is not None
+            else _env("FORGESIGHT_DATADOG_AGENT_ENDPOINT")
+        )
+        self._transport = (
+            transport if transport != "agent" else (_env("FORGESIGHT_DATADOG_TRANSPORT") or "agent")
+        )
+        if self._transport not in ("agent", "otlp"):
+            raise ValueError(f"transport must be 'agent' or 'otlp', got {self._transport!r}")
+        self._capture_content = capture_content or _env_bool("FORGESIGHT_CAPTURE_CONTENT", False)
+
+        self._sink: _Sink = self._build_sink(span_writer, metric_sink, span_exporter)
+
+    # --- TelemetryExporter Protocol --------------------------------------
+    def export(self, records: Sequence[Record]) -> ExportResult:
+        return self._sink.export(records)
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return self._sink.force_flush(timeout_millis)
+
+    def shutdown(self, timeout_millis: int = 30_000) -> None:
+        self._sink.shutdown(timeout_millis)
+
+    # --- transport wiring -------------------------------------------------
+    def _build_sink(
+        self,
+        span_writer: DatadogSpanWriter | None,
+        metric_sink: DatadogMetricSink | None,
+        span_exporter: object | None,
+    ) -> _Sink:
+        if self._transport == "otlp":
+            if not self._agent_endpoint:
+                raise ValueError(
+                    "transport='otlp' requires agent_endpoint "
+                    "(DD Agent OTLP port or DD OTLP intake)"
+                )
+            return _OTLPSink(
+                endpoint=self._agent_endpoint,
+                service=self._service,
+                env=self._env,
+                version=self._version,
+                capture_content=self._capture_content,
+                span_exporter=span_exporter,
+            )
+        # transport == "agent"
+        if span_writer is None and not self._agent_endpoint and not self._api_key:
+            raise ValueError(
+                "transport='agent' direct intake requires api_key (or set agent_endpoint "
+                "for a local DD Agent)"
+            )
+        writer = span_writer if span_writer is not None else self._default_span_writer()
+        sink = metric_sink if metric_sink is not None else self._default_metric_sink()
+        return _AgentSink(
+            writer=writer,
+            metric_sink=sink,
+            service=self._service,
+            env=self._env,
+            version=self._version,
+            capture_content=self._capture_content,
+        )
+
+    def _default_span_writer(self) -> DatadogSpanWriter:  # pragma: no cover - needs a live DD Agent
+        from ._ddtrace import DDTraceSpanWriter
+
+        return DDTraceSpanWriter(
+            service=self._service,
+            api_key=self._api_key,
+            site=self._site,
+            agent_endpoint=self._agent_endpoint,
+        )
+
+    def _default_metric_sink(self) -> DatadogMetricSink:  # pragma: no cover - needs a live DD Agent
+        from ._ddtrace import DogStatsdMetricSink
+
+        return DogStatsdMetricSink(agent_endpoint=self._agent_endpoint)
+
+
+# --- record → DatadogSpan mapping (pure, fully tested) ----------------------
+def _op(record: Record) -> str:
+    kind = record.kind
+    if kind is Kind.AGENT:
+        return _OP_INVOKE_AGENT
+    if kind is Kind.WORKFLOW:
+        return _OP_INVOKE_WORKFLOW
+    if kind is Kind.LLM:
+        return _OP_CHAT
+    if kind is Kind.TOOL:
+        return _OP_EXECUTE_TOOL
+    if kind is Kind.MCP and record.mcp is not None and record.mcp.method == _MCP_TOOLS_CALL:
+        return _OP_EXECUTE_TOOL
+    return ""
+
+
+def _error_type(record: Record) -> str | None:
+    if record.error is not None:
+        return record.error.error_type
+    if record.status not in _OK_STATUSES:
+        return record.status.value
+    return None
+
+
+def _resource(record: Record) -> str:
+    if record.kind is Kind.MCP and record.mcp is not None:
+        return record.mcp.method
+    return record.name
+
+
+def record_to_span(
+    record: Record, *, service: str, env: str | None, version: str | None, capture_content: bool
+) -> DatadogSpan:
+    """Map a Record onto a DD APM span with unified tags, gen_ai tags, and cost."""
+    attrs = record.attributes
+    meta: dict[str, str] = {"forgesight.run_id": record.run_id}
+    if env is not None:
+        meta["env"] = env
+    if version is not None:
+        meta["version"] = version
+    for key, value in attrs.items():
+        if key not in _STRUCTURED_KEYS:
+            meta[key] = str(value)
+    if _PARENT_RUN_ID_KEY in attrs:
+        meta["forgesight.parent_run_id"] = str(attrs[_PARENT_RUN_ID_KEY])
+    if _CONTEXT_ID_KEY in attrs:
+        meta["gen_ai.conversation.id"] = str(attrs[_CONTEXT_ID_KEY])
+    if _AGENT_VERSION_KEY in attrs:
+        meta["gen_ai.agent.version"] = str(attrs[_AGENT_VERSION_KEY])
+
+    op = _op(record)
+    if op:
+        meta["gen_ai.operation.name"] = op
+    if record.kind is Kind.AGENT:
+        meta["gen_ai.agent.name"] = record.name
+
+    metrics: dict[str, float] = {}
+    llm = record.llm
+    if llm is not None:
+        meta["gen_ai.provider.name"] = llm.provider
+        meta["gen_ai.request.model"] = llm.request_model
+        if llm.response_model is not None:
+            meta["gen_ai.response.model"] = llm.response_model
+        usage = llm.usage
+        for tag, value in (
+            ("input_tokens", usage.input),
+            ("output_tokens", usage.output),
+            ("cache_read_tokens", usage.cache_read),
+            ("cache_creation_tokens", usage.cache_creation),
+            ("reasoning_tokens", usage.reasoning),
+        ):
+            if value:
+                metrics[f"gen_ai.usage.{tag}"] = float(value)
+        if llm.cost_usd is not None:
+            metrics[COST_METRIC] = llm.cost_usd
+            meta[COST_METRIC] = f"{llm.cost_usd:.6f}"  # also a span tag (monitorable)
+        if capture_content and llm.content is not None:
+            _attach_content(llm.content, meta)
+    if record.tool is not None:
+        meta["gen_ai.tool.name"] = record.tool.name
+        meta["gen_ai.tool.type"] = record.tool.tool_type
+    if record.mcp is not None:
+        meta["mcp.method.name"] = record.mcp.method
+        meta["mcp.server"] = record.mcp.server
+        if record.mcp.tool is not None:
+            meta["gen_ai.tool.name"] = record.mcp.tool
+
+    error_type = _error_type(record)
+    if error_type is not None:
+        meta["error.type"] = error_type
+        if record.error is not None:
+            meta["error.message"] = record.error.message
+
+    end = record.end_unix_nanos if record.end_unix_nanos is not None else record.start_unix_nanos
+    return DatadogSpan(
+        trace_id=record.trace_id,
+        span_id=record.span_id,
+        parent_id=record.parent_span_id,
+        name=_DD_SPAN_NAME[record.kind],
+        resource=_resource(record),
+        service=service,
+        start_ns=record.start_unix_nanos,
+        duration_ns=max(0, end - record.start_unix_nanos),
+        error=0 if record.status in _OK_STATUSES else 1,
+        meta=meta,
+        metrics=metrics,
+    )
+
+
+def _attach_content(content: object, meta: dict[str, str]) -> None:
+    import json
+
+    for attr, key in (
+        ("input_messages", "gen_ai.input.messages"),
+        ("output_messages", "gen_ai.output.messages"),
+        ("system_instructions", "gen_ai.system_instructions"),
+    ):
+        value = getattr(content, attr, None)
+        if value is not None:
+            meta[key] = json.dumps(value, default=str)
+
+
+# --- transports -------------------------------------------------------------
+class _AgentSink:
+    """DD Agent transport: ddtrace span writer + dogstatsd cost/token metrics."""
+
+    def __init__(
+        self,
+        *,
+        writer: DatadogSpanWriter,
+        metric_sink: DatadogMetricSink,
+        service: str,
+        env: str | None,
+        version: str | None,
+        capture_content: bool,
+    ) -> None:
+        self._writer = writer
+        self._metrics = metric_sink
+        self._service = service
+        self._env = env
+        self._version = version
+        self._capture_content = capture_content
+
+    def export(self, records: Sequence[Record]) -> ExportResult:
+        try:
+            for record in records:
+                span = record_to_span(
+                    record,
+                    service=self._service,
+                    env=self._env,
+                    version=self._version,
+                    capture_content=self._capture_content,
+                )
+                self._writer.write(span)
+                self._emit_metrics(record, span)
+        except Exception:  # a DD Agent outage is counted, never raised (P6)
+            _log.warning("datadog agent export failed", exc_info=True)
+            return ExportResult.FAILURE
+        return ExportResult.SUCCESS
+
+    def _emit_metrics(self, record: Record, span: DatadogSpan) -> None:
+        llm = record.llm
+        if llm is None:
+            return
+        base = [f"service:{self._service}"]
+        if self._env is not None:
+            base.append(f"env:{self._env}")
+        model_tags = [*base, f"provider:{llm.provider}", f"model:{llm.request_model}"]
+        if llm.cost_usd is not None:
+            self._metrics.emit(COST_METRIC, llm.cost_usd, model_tags)
+        for token_type, value in (
+            ("input", llm.usage.input),
+            ("output", llm.usage.output),
+            ("cache_read", llm.usage.cache_read),
+            ("cache_creation", llm.usage.cache_creation),
+            ("reasoning", llm.usage.reasoning),
+        ):
+            if value:
+                self._metrics.emit(
+                    TOKENS_METRIC, float(value), [*model_tags, f"gen_ai_token_type:{token_type}"]
+                )
+
+    def force_flush(self, timeout_millis: int) -> bool:
+        return self._writer.flush()
+
+    def shutdown(self, timeout_millis: int) -> None:
+        try:
+            self._writer.stop()
+        finally:
+            self._metrics.close()
+
+
+class _OTLPSink:
+    """OTLP transport: forgesight-otel → DD Agent OTLP port, with DD unified tags."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        service: str,
+        env: str | None,
+        version: str | None,
+        capture_content: bool,
+        span_exporter: object | None,
+    ) -> None:
+        from forgesight_otel import OTelExporter
+
+        resource: dict[str, str] = {}
+        if env is not None:
+            resource["deployment.environment"] = env  # DD reads this as `env`
+        if version is not None:
+            resource["service.version"] = version  # DD reads this as `version`
+        # http/protobuf needs no optional [grpc] extra; the DD Agent's OTLP/HTTP port is
+        # :4318. (forgesight-otel can still do grpc if the extra is installed.)
+        self._otel = OTelExporter(
+            endpoint=endpoint,
+            protocol="http/protobuf",
+            service_name=service,
+            capture_content=capture_content,
+            resource_attributes=resource or None,
+            span_exporter=span_exporter,  # type: ignore[arg-type]
+        )
+
+    def export(self, records: Sequence[Record]) -> ExportResult:
+        return self._otel.export(records)
+
+    def force_flush(self, timeout_millis: int) -> bool:
+        return self._otel.force_flush(timeout_millis)
+
+    def shutdown(self, timeout_millis: int) -> None:
+        self._otel.shutdown(timeout_millis)

forgesight_datadog/testing.py

@@ -0,0 +1,69 @@
+"""Doubles for testing the Datadog exporter without a live DD Agent.
+
+:class:`InMemoryDatadogSpanWriter` and :class:`InMemoryDatadogMetricSink` satisfy the
+``DatadogSpanWriter`` / ``DatadogMetricSink`` protocols and record everything written, so a
+test (or a consuming team's pipeline test) can assert the mapped spans, unified tags, and
+the cost / token DD metrics.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from .exporter import DatadogSpan
+
+
+class InMemoryDatadogSpanWriter:
+    """Captures every mapped :class:`DatadogSpan` instead of writing to a DD Agent."""
+
+    def __init__(self) -> None:
+        self.spans: list[DatadogSpan] = []
+        self.flushed = 0
+        self.stopped = False
+
+    def write(self, span: DatadogSpan) -> None:
+        self.spans.append(span)
+
+    def flush(self) -> bool:
+        self.flushed += 1
+        return True
+
+    def stop(self) -> None:
+        self.stopped = True
+
+    def by_resource(self) -> dict[str, DatadogSpan]:
+        return {span.resource: span for span in self.spans}
+
+
+@dataclass(frozen=True)
+class MetricCall:
+    """One emitted DD metric."""
+
+    name: str
+    value: float
+    tags: list[str] = field(default_factory=list)
+
+
+class InMemoryDatadogMetricSink:
+    """Captures every emitted DD metric instead of sending to dogstatsd."""
+
+    def __init__(self) -> None:
+        self.metrics: list[MetricCall] = []
+        self.closed = False
+
+    def emit(self, name: str, value: float, tags: Sequence[str]) -> None:
+        self.metrics.append(MetricCall(name=name, value=value, tags=list(tags)))
+
+    def close(self) -> None:
+        self.closed = True
+
+    def named(self, name: str) -> list[MetricCall]:
+        return [m for m in self.metrics if m.name == name]
+
+
+__all__ = [
+    "InMemoryDatadogMetricSink",
+    "InMemoryDatadogSpanWriter",
+    "MetricCall",
+]

forgesight_datadog-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+forgesight_datadog/__init__.py,sha256=CSJ6vowkefjicTeZzttc1La32UAX6w6YkjJIQSvP9w8,760
+forgesight_datadog/_ddtrace.py,sha256=JqXssLQpIel060ZsckcMNjhSMrjhH2zHts9Xg3N-1Jg,3563
+forgesight_datadog/exporter.py,sha256=c-NGvV6Ju2HUaJ4OzgiI1I-2Qe7eNK5GSeqJmpHfnwQ,18528
+forgesight_datadog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forgesight_datadog/testing.py,sha256=-7CZjY_pA3wMy4eJesHmylpYGCoHC70WBUBhIYcbqtQ,1901
+forgesight_datadog-0.1.0.dist-info/METADATA,sha256=LfA2BjyASV2dEnLeBO-gR4dMCy4EVzY1Dk0p3OoMyGg,4125
+forgesight_datadog-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+forgesight_datadog-0.1.0.dist-info/entry_points.txt,sha256=YIpk7x-mXg8VHVkv14jSbI631Lih3hS7VK93hKToz_8,77
+forgesight_datadog-0.1.0.dist-info/RECORD,,

forgesight_datadog-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

forgesight_datadog-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[forgesight.exporters]
+datadog = forgesight_datadog.exporter:DatadogExporter