From 43a14cdd5e2c73cd772b8657803c1024192f42dd Mon Sep 17 00:00:00 2001 From: dach-a Date: Tue, 10 Nov 2026 04:41:11 +0000 Subject: [PATCH] Add optional OpenTelemetry tracing for agent runs Observability is the missing half of an agent harness: the audit log records what happened, but nothing emits it as a trace. Each model run is now an `invoke_agent` span with `chat ` and `execute_tool ` children, and the money path gets `txn_agent.purchase` / `txn_agent.checkout_cart` spans carrying the gate decision, its reasons, the outcome and the idempotency key. Approval verdicts get their own child span. The core stays stdlib-only: OpenTelemetry is imported lazily, so an unconfigured provider means every helper is a no-op, and tool arguments and prompts are never recorded as attributes. --- CHANGELOG.md | 12 +++ README.md | 22 +++++ pyproject.toml | 3 +- tests/test_telemetry.py | 207 ++++++++++++++++++++++++++++++++++++++++ txn_agent/agent.py | 95 ++++++++++++++---- txn_agent/llm.py | 65 +++++++++---- txn_agent/telemetry.py | 205 +++++++++++++++++++++++++++++++++++++++ txn_agent/tools.py | 25 +++-- 8 files changed, 591 insertions(+), 43 deletions(-) create mode 100644 tests/test_telemetry.py create mode 100644 txn_agent/telemetry.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 576a9da..83d4cff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,18 @@ All notable changes to this project are documented here. Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning: SemVer. +## [Unreleased] + +### Added +- **Optional OpenTelemetry tracing** (`txn_agent/telemetry.py`, extra `txn-agent[otel]`): + one `invoke_agent txn-agent` span per model run, with `chat ` children carrying + `gen_ai.usage.*` token counts, `execute_tool ` spans per tool call, and a + `txn_agent.checkout_cart` span recording the gate decision, its reasons, the cart + total, the outcome and the idempotency key. Approval verdicts get their own child + span. Tool arguments and prompts are never recorded. The core stays stdlib-only: + no import of `opentelemetry` at module load, and an unconfigured provider means + every helper is a no-op. + ## [0.4.5] - 2026-10-29 ### Added diff --git a/README.md b/README.md index fe203e1..413e815 100644 --- a/README.md +++ b/README.md @@ -154,6 +154,28 @@ Merchants: become agent-purchasable in an afternoon — run the reference distri adapter (`MERCHANT_API_KEY=dist-key uvicorn examples.distributor_service:app --port 9000`) and see [`docs/distributor-pitch.md`](docs/distributor-pitch.md) for the one-page ask. +## Tracing (optional) + +The core is still stdlib-only: OpenTelemetry is never imported unless you ask for it. + +```bash +pip install 'txn-agent[otel]' # opentelemetry-api; bring your own exporter/SDK +``` + +Every agent run becomes a trace — `invoke_agent txn-agent` → `chat ` and +`execute_tool ` spans — plus `txn_agent.checkout_cart` with the gate decision, +reasons, cart total, outcome and the idempotency key as attributes. Tool arguments and +prompt text are deliberately **not** recorded. No provider configured means no-op, so +library users pay nothing for it. + +```python +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider + +trace.set_tracer_provider(TracerProvider()) # your exporter of choice +txn_agent.telemetry.reset() # re-detect the configured provider +``` + ## Docs - [docs/architecture.md](docs/architecture.md) — module map diff --git a/pyproject.toml b/pyproject.toml index bf6d50b..8ee81a3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,9 +30,10 @@ build-backend = "setuptools.build_meta" packages = ["txn_agent", "txn_agent.connectors"] [project.optional-dependencies] -dev = ["pytest", "pytest-cov", "ruff", "mypy", "httpx"] +dev = ["pytest", "pytest-cov", "ruff", "mypy", "httpx", "opentelemetry-sdk"] llm = ["anthropic"] service = ["fastapi>=0.110", "uvicorn"] +otel = ["opentelemetry-api>=1.20"] [project.urls] Homepage = "https://github.com/cyberd4ch/txn-agent" diff --git a/tests/test_telemetry.py b/tests/test_telemetry.py new file mode 100644 index 0000000..b9e1be8 --- /dev/null +++ b/tests/test_telemetry.py @@ -0,0 +1,207 @@ +"""Tracing is optional and must never break a purchase. + +These tests use an injected tracer rather than a real exporter: the point is to pin +the contract (span names, the facts recorded, and the no-op path when +`opentelemetry-api` is absent), not to test somebody else's SDK. +""" +import importlib.util +from decimal import Decimal as D + +import pytest + +from txn_agent import telemetry +from txn_agent.agent import TransactionalAgent +from txn_agent.connectors import default_connectors +from txn_agent.intent import parse_request +from txn_agent.llm import run_llm_request +from txn_agent.models import Cart, CartItem +from txn_agent.payments import DemoVault +from txn_agent.tools import ToolRouter + + +class FakeSpan: + def __init__(self, name: str): + self.name = name + self.attributes: dict[str, object] = {} + self.events: list[tuple[str, dict]] = [] + self.exceptions: list[BaseException] = [] + + def set_attribute(self, key: str, value: object) -> None: + self.attributes[key] = value + + def add_event(self, name: str, attributes: dict | None = None) -> None: + self.events.append((name, attributes or {})) + + def record_exception(self, exception: BaseException) -> None: + self.exceptions.append(exception) + + +class FakeContext: + def __init__(self, span: FakeSpan): + self.span = span + + def __enter__(self) -> FakeSpan: + return self.span + + def __exit__(self, *exc: object) -> bool: + return False + + +class FakeTracer: + def __init__(self) -> None: + self.spans: list[FakeSpan] = [] + + def start_as_current_span(self, name: str, **kwargs: object) -> FakeContext: + span = FakeSpan(name) + self.spans.append(span) + return FakeContext(span) + + def named(self, name: str) -> FakeSpan: + matches = [s for s in self.spans if s.name == name] + assert matches, f"no span named {name!r}; got {[s.name for s in self.spans]}" + return matches[-1] + + +@pytest.fixture(autouse=True) +def _fresh_tracer(): + telemetry.reset() + yield + telemetry.reset() + + +def make_agent(confirm=None) -> TransactionalAgent: + return TransactionalAgent(default_connectors(), DemoVault(), confirm=confirm) + + +def make_cart(agent: TransactionalAgent, query: str = "dishwasher lower rack wheel kit under $50") -> Cart: + """A one-line cart built from a real search, so the cart path is exercised too.""" + offers = [o for o in agent.search(parse_request(query)) if o.in_stock] + assert offers, "fixture search returned nothing in stock" + return Cart(items=(CartItem(offer=offers[0]),), cart_id="test-cart") + + +def test_configured_tracer_is_used() -> None: + tracer = FakeTracer() + telemetry.configure(tracer) + assert telemetry._tracer() is tracer + + +def test_checkout_records_gate_decision_outcome_and_key() -> None: + tracer = FakeTracer() + telemetry.configure(tracer) + + agent = make_agent() + out = agent.checkout_cart(make_cart(agent)) + assert out.status.value == "purchased" + + span = tracer.named(telemetry.SPAN_CHECKOUT) + assert span.attributes[telemetry.ATTR_GATE_DECISION] == "auto_buy" + assert span.attributes[telemetry.ATTR_OUTCOME] == "purchased" + assert span.attributes[telemetry.ATTR_MERCHANT] == "AppliancePartsCo" + # The key is a hash, not a cart dump: safe to put on a span. + assert len(str(span.attributes[telemetry.ATTR_IDEMPOTENCY_KEY])) == 32 + # Decimals are stringified so the attribute type stays valid. + assert isinstance(span.attributes[telemetry.ATTR_CART_TOTAL], str) + assert telemetry.ATTR_APPROVAL_REQUIRED not in span.attributes + + +def test_declined_approval_is_a_child_span_with_the_verdict() -> None: + tracer = FakeTracer() + telemetry.configure(tracer) + + # Flights always need approval; no approver wired means fail closed -> declined. + # This exercises the single-offer path (`run`), which has its own span. + out = make_agent().run(parse_request("flight SFO to JFK under $400")) + assert out.status.value == "declined" + + checkout = tracer.named(telemetry.SPAN_PURCHASE) + assert checkout.attributes[telemetry.ATTR_GATE_DECISION] == "confirm" + assert checkout.attributes[telemetry.ATTR_APPROVAL_REQUIRED] is True + assert checkout.attributes[telemetry.ATTR_OUTCOME] == "declined" + + approval = tracer.named(telemetry.SPAN_APPROVAL) + assert approval.attributes[telemetry.ATTR_APPROVED] is False + + +def test_tool_spans_carry_genai_attributes_and_no_arguments() -> None: + tracer = FakeTracer() + telemetry.configure(tracer) + + router = ToolRouter(make_agent(), budget_ceiling=D("150")) + out = router.call("search_offers", + {"vertical": "parts", "query": "door gasket", "max_total": 999}) + assert "offers" in out + + span = tracer.named("execute_tool search_offers") + assert span.attributes[telemetry.ATTR_TOOL_NAME] == "search_offers" + assert span.attributes[telemetry.ATTR_OPERATION] == "execute_tool" + assert span.attributes[telemetry.ATTR_VERTICAL] == "parts" + # The model's prose never lands in telemetry. + assert "door gasket" not in str(span.attributes.values()) + + +def test_tool_errors_are_marked_not_raised() -> None: + tracer = FakeTracer() + telemetry.configure(tracer) + + router = ToolRouter(make_agent(), budget_ceiling=D("150")) + out = router.call("search_offers", {}) # malformed model arguments + assert "error" in out + + span = tracer.named("execute_tool search_offers") + assert span.attributes[telemetry.ATTR_TOOL_ERROR] == "invalid_arguments" + + +class FakeBlock: + def __init__(self, block: dict) -> None: + self.__dict__.update(block) + + +class FakeUsage: + input_tokens = 120 + output_tokens = 30 + + +class FakeResponse: + stop_reason = "end_turn" + role = "assistant" + usage = FakeUsage() + + def __init__(self) -> None: + self.content = [FakeBlock({"type": "text", "text": "Nothing needed."})] + + +class FakeClient: + def __init__(self) -> None: + self.messages = self + + def create(self, **kwargs: object) -> FakeResponse: + return FakeResponse() + + +def test_llm_run_records_agent_chat_and_usage() -> None: + tracer = FakeTracer() + telemetry.configure(tracer) + + result = run_llm_request(make_agent(), "check the wheel kit", budget_ceiling=D("150"), + model="test-model", client=FakeClient()) + assert result.stopped_reason == "end_turn" + + run = tracer.named(telemetry.SPAN_AGENT_RUN) + assert run.attributes[telemetry.ATTR_OPERATION] == "invoke_agent" + assert run.attributes[telemetry.ATTR_MODEL] == "test-model" + assert run.attributes[telemetry.ATTR_TURNS] == 1 + assert run.attributes[telemetry.ATTR_STOP_REASON] == "end_turn" + + chat = tracer.named("chat test-model") + assert chat.attributes[telemetry.ATTR_INPUT_TOKENS] == 120 + assert chat.attributes[telemetry.ATTR_OUTPUT_TOKENS] == 30 + + +@pytest.mark.skipif(importlib.util.find_spec("opentelemetry") is not None, + reason="opentelemetry-api is installed; the no-op path is not the default") +def test_span_is_a_noop_without_opentelemetry() -> None: + with telemetry.span("anything", {"a": 1}) as active: + active.set_attribute("b", 2) + active.add_event("e") + telemetry.set_attribute(active, "c", None) # None attributes are dropped diff --git a/txn_agent/agent.py b/txn_agent/agent.py index 5a978a6..3103294 100644 --- a/txn_agent/agent.py +++ b/txn_agent/agent.py @@ -5,7 +5,9 @@ from dataclasses import dataclass, replace from decimal import Decimal as D from enum import Enum +from typing import Any +from . import telemetry from .approval import Approver from .audit import AuditLog from .connectors.base import CheckoutError, Connector @@ -98,6 +100,24 @@ def _void(self, payment_ref: str, context_id: str) -> None: def checkout_cart(self, cart: Cart, quoted_total: D | None = None) -> Outcome: """Revalidate every line -> gate the whole cart -> (approve) -> one idempotent checkout.""" + with telemetry.span(telemetry.SPAN_CHECKOUT, { + telemetry.ATTR_CART_ID: cart.cart_id, + telemetry.ATTR_MERCHANT: cart.merchant, + telemetry.ATTR_VERTICAL: cart.vertical.value, + telemetry.ATTR_CART_TOTAL: cart.total, + telemetry.ATTR_CART_LINES: len(cart.items), + }) as active: + return self._checkout_cart(cart, quoted_total, active) + + def _checkout_cart(self, cart: Cart, quoted_total: D | None, active: Any) -> Outcome: + """The checkout pipeline, with the span passed in so every exit is recorded.""" + + def done(outcome: Outcome) -> Outcome: + telemetry.set_attribute(active, telemetry.ATTR_OUTCOME, outcome.status.value) + if outcome.reasons: + telemetry.add_event(active, "txn_agent.outcome", {"reasons": list(outcome.reasons)}) + return outcome + conn = self.connectors[cart.vertical] live_items = tuple(CartItem(offer=conn.revalidate(i.offer), quantity=i.quantity) for i in cart.items) # never buy on stale quotes @@ -106,33 +126,49 @@ def checkout_cart(self, cart: Cart, quoted_total: D | None = None) -> Outcome: quoted_total=quoted_total if quoted_total is not None else live.total) self.audit.record(live.cart_id, "gate", cart=to_dict(live), decision=gate.decision, reasons=list(gate.reasons)) + # The decision is the fact worth querying later: which gates fire, on what, + # and how often. Reasons are a short tuple, not free text, so they stay + # safe as an attribute (and the gate is what produces them). + telemetry.set_attributes(active, { + telemetry.ATTR_GATE_DECISION: gate.decision.value, + telemetry.ATTR_GATE_REASONS: list(gate.reasons), + }) if gate.decision is Decision.REJECT: - return Outcome(Status.REJECTED, live.cart_id, cart=live, - reasons=tuple(f"{live.merchant}: {r}" for r in gate.reasons)) + return done(Outcome(Status.REJECTED, live.cart_id, cart=live, + reasons=tuple(f"{live.merchant}: {r}" for r in gate.reasons))) if gate.decision in (Decision.CONFIRM, Decision.B2B_REVIEW): - approved = self._approve(live, gate) + with telemetry.span(telemetry.SPAN_APPROVAL, { + telemetry.ATTR_CART_ID: live.cart_id, + telemetry.ATTR_CART_TOTAL: live.total, + }) as approval_span: + approved = self._approve(live, gate) + telemetry.set_attribute(approval_span, telemetry.ATTR_APPROVED, approved) + telemetry.set_attribute(active, telemetry.ATTR_APPROVAL_REQUIRED, True) self.audit.record(live.cart_id, "confirmation", approved=approved) if not approved: - return Outcome(Status.DECLINED, live.cart_id, cart=live, reasons=gate.reasons) + return done(Outcome(Status.DECLINED, live.cart_id, cart=live, reasons=gate.reasons)) key = cart_idempotency_key(live) + telemetry.set_attribute(active, telemetry.ATTR_IDEMPOTENCY_KEY, key) first = live.items[0].offer lines = [(i.offer.offer_id, i.quantity) for i in live.items] try: payment_ref, charged = self._pay(live, key, live.cart_id) except PaymentError as e: - return Outcome(Status.FAILED, live.cart_id, cart=live, reasons=(f"payment: {e}",)) + telemetry.add_event(active, "txn_agent.payment_failed", {"error": str(e)}) + return done(Outcome(Status.FAILED, live.cart_id, cart=live, reasons=(f"payment: {e}",))) try: receipt = conn.checkout(first, payment_ref, key, lines=lines) except CheckoutError as e: + telemetry.record_exception(active, e) if charged: self._void(payment_ref, live.cart_id) self.audit.record(live.cart_id, "checkout_failed", error=str(e)) - return Outcome(Status.FAILED, live.cart_id, cart=live, reasons=(str(e),)) + return done(Outcome(Status.FAILED, live.cart_id, cart=live, reasons=(str(e),))) self.audit.record(live.cart_id, "purchased", receipt=to_dict(receipt)) - return Outcome(Status.PURCHASED, live.cart_id, cart=live, receipt=receipt, - reasons=gate.reasons) + return done(Outcome(Status.PURCHASED, live.cart_id, cart=live, receipt=receipt, + reasons=gate.reasons)) def _rank_cost(self, o: Offer) -> D: cost = o.total * (1 + o.return_policy.restocking_fee_pct / 100) @@ -150,36 +186,63 @@ def search(self, intent: Intent) -> list[Offer]: return ranked def purchase(self, intent: Intent, quote: Offer) -> Outcome: + with telemetry.span(telemetry.SPAN_PURCHASE, { + telemetry.ATTR_MERCHANT: quote.merchant, + telemetry.ATTR_VERTICAL: quote.vertical.value, + telemetry.ATTR_CART_TOTAL: quote.total, + }) as active: + return self._purchase(intent, quote, active) + + def _purchase(self, intent: Intent, quote: Offer, active: Any) -> Outcome: + """Single-offer path (run/CLI), with the span passed in for every exit.""" + + def done(outcome: Outcome) -> Outcome: + telemetry.set_attribute(active, telemetry.ATTR_OUTCOME, outcome.status.value) + return outcome + conn = self.connectors[intent.vertical] live = conn.revalidate(quote) # never buy on a stale quote gate = evaluate(live, intent, self.policy, quote.total) self.audit.record(intent.intent_id, "gate", offer=to_dict(live), decision=gate.decision, reasons=gate.reasons) + telemetry.set_attributes(active, { + telemetry.ATTR_GATE_DECISION: gate.decision.value, + telemetry.ATTR_GATE_REASONS: list(gate.reasons), + }) if gate.decision is Decision.REJECT: - return Outcome(Status.REJECTED, intent.intent_id, live, - reasons=tuple(f"{live.merchant}: {r}" for r in gate.reasons)) + return done(Outcome(Status.REJECTED, intent.intent_id, live, + reasons=tuple(f"{live.merchant}: {r}" for r in gate.reasons))) if gate.decision in (Decision.CONFIRM, Decision.B2B_REVIEW): - approved = self._approve(single_line_cart(live, intent.intent_id), gate) + with telemetry.span(telemetry.SPAN_APPROVAL, { + telemetry.ATTR_CART_TOTAL: live.total, + telemetry.ATTR_VERTICAL: live.vertical.value, + }) as approval_span: + approved = self._approve(single_line_cart(live, intent.intent_id), gate) + telemetry.set_attribute(approval_span, telemetry.ATTR_APPROVED, approved) + telemetry.set_attribute(active, telemetry.ATTR_APPROVAL_REQUIRED, True) self.audit.record(intent.intent_id, "confirmation", approved=approved) if not approved: - return Outcome(Status.DECLINED, intent.intent_id, live, reasons=gate.reasons) + return done(Outcome(Status.DECLINED, intent.intent_id, live, reasons=gate.reasons)) key = idempotency_key(intent, live) + telemetry.set_attribute(active, telemetry.ATTR_IDEMPOTENCY_KEY, key) try: payment_ref, charged = self._pay(single_line_cart(live, intent.intent_id), key, intent.intent_id) except PaymentError as e: - return Outcome(Status.FAILED, intent.intent_id, live, reasons=(f"payment: {e}",)) + telemetry.add_event(active, "txn_agent.payment_failed", {"error": str(e)}) + return done(Outcome(Status.FAILED, intent.intent_id, live, reasons=(f"payment: {e}",))) try: receipt = conn.checkout(live, payment_ref, key) except CheckoutError as e: + telemetry.record_exception(active, e) if charged: self._void(payment_ref, intent.intent_id) self.audit.record(intent.intent_id, "checkout_failed", error=str(e)) - return Outcome(Status.FAILED, intent.intent_id, live, reasons=(str(e),)) + return done(Outcome(Status.FAILED, intent.intent_id, live, reasons=(str(e),))) self.audit.record(intent.intent_id, "purchased", receipt=to_dict(receipt)) - return Outcome(Status.PURCHASED, intent.intent_id, live, receipt, - reasons=gate.reasons) + return done(Outcome(Status.PURCHASED, intent.intent_id, live, receipt, + reasons=gate.reasons)) def run(self, intent: Intent) -> Outcome: rejections: list[str] = [] diff --git a/txn_agent/llm.py b/txn_agent/llm.py index 3c6a8c1..46cd483 100644 --- a/txn_agent/llm.py +++ b/txn_agent/llm.py @@ -14,6 +14,7 @@ from decimal import Decimal as D from typing import Any +from . import telemetry from .agent import TransactionalAgent from .tools import TOOL_SCHEMAS, ToolRouter @@ -56,26 +57,50 @@ def run_llm_request(agent: TransactionalAgent, request: str, *, budget_ceiling: messages: list[dict[str, Any]] = [{"role": "user", "content": request}] tool_calls: list[dict[str, Any]] = [] reply, stop = "", "end_turn" + turns = 0 - for _ in range(max_turns): - resp = client.messages.create(model=model, max_tokens=1024, system=SYSTEM_PROMPT, - messages=messages, tools=TOOL_SCHEMAS) - reply = "".join(b.text for b in resp.content if getattr(b, "type", "") == "text") - if resp.stop_reason != "tool_use": - stop = resp.stop_reason - break - messages.append({"role": resp.role, "content": resp.content}) - results: list[dict[str, Any]] = [] - for block in resp.content: - if getattr(block, "type", "") != "tool_use": - continue - out = router.call(block.name, dict(block.input)) - tool_calls.append({"tool": block.name, "args": dict(block.input), "result": out}) - agent.audit.record("llm", "tool_call", tool=block.name, result=out) - results.append({"type": "tool_result", "tool_use_id": block.id, - "content": json.dumps(out, default=str)}) - messages.append({"role": "user", "content": results}) - else: - stop = "max_turns" # model kept requesting tools past the turn budget + # One parent span per agent run: model calls and tool executions nest under it, + # which is what makes a looping agent readable in a trace instead of flat. + with telemetry.span(telemetry.SPAN_AGENT_RUN, { + telemetry.ATTR_OPERATION: "invoke_agent", + telemetry.ATTR_AGENT_NAME: "txn-agent", + telemetry.ATTR_MODEL: model, + }) as active: + for turn in range(max_turns): + turns = turn + 1 + with telemetry.span(telemetry.chat_span_name(model), { + telemetry.ATTR_OPERATION: "chat", + telemetry.ATTR_MODEL: model, + }) as chat_span: + resp = client.messages.create(model=model, max_tokens=1024, system=SYSTEM_PROMPT, + messages=messages, tools=TOOL_SCHEMAS) + usage = getattr(resp, "usage", None) + if usage is not None: + telemetry.set_attributes(chat_span, { + telemetry.ATTR_INPUT_TOKENS: getattr(usage, "input_tokens", None), + telemetry.ATTR_OUTPUT_TOKENS: getattr(usage, "output_tokens", None), + }) + reply = "".join(b.text for b in resp.content if getattr(b, "type", "") == "text") + if resp.stop_reason != "tool_use": + stop = resp.stop_reason + break + messages.append({"role": resp.role, "content": resp.content}) + results: list[dict[str, Any]] = [] + for block in resp.content: + if getattr(block, "type", "") != "tool_use": + continue + out = router.call(block.name, dict(block.input)) + tool_calls.append({"tool": block.name, "args": dict(block.input), "result": out}) + agent.audit.record("llm", "tool_call", tool=block.name, result=out) + results.append({"type": "tool_result", "tool_use_id": block.id, + "content": json.dumps(out, default=str)}) + messages.append({"role": "user", "content": results}) + else: + stop = "max_turns" # model kept requesting tools past the turn budget + + telemetry.set_attributes(active, { + telemetry.ATTR_TURNS: turns, + telemetry.ATTR_STOP_REASON: stop, + }) return LLMResult(reply=reply, stopped_reason=stop, tool_calls=tool_calls) diff --git a/txn_agent/telemetry.py b/txn_agent/telemetry.py new file mode 100644 index 0000000..d6e29af --- /dev/null +++ b/txn_agent/telemetry.py @@ -0,0 +1,205 @@ +"""Optional OpenTelemetry tracing for agent runs. + +The core keeps its stdlib-only promise: OpenTelemetry is never imported at module +load. With ``opentelemetry-api`` installed (``pip install 'txn-agent[otel]'``) and a +provider configured by the host, spans go wherever that provider sends them; without +it every helper here is a no-op, so importing and running the package is unchanged. + +``configure()`` also accepts any tracer-shaped object, which is how the tests assert +on spans without pulling a real exporter into CI. + +Naming follows the OpenTelemetry GenAI conventions where they exist (agent +invocation, chat, tool execution) and a ``txn_agent.*`` namespace for the domain +facts this package is actually about: gate decisions, budgets, idempotency keys. +Semantic conventions are still moving, so every attribute name lives in this file — +a rename is one edit, not a grep. +""" +from __future__ import annotations + +from collections.abc import Iterator, Mapping +from contextlib import contextmanager +from typing import Any, Literal + +INSTRUMENTATION_NAME = "txn-agent" + +# Span names. GenAI conventions: "{operation} {name}" for agent/chat/tool spans. +SPAN_PURCHASE = "txn_agent.purchase" +SPAN_CHECKOUT = "txn_agent.checkout_cart" +SPAN_APPROVAL = "txn_agent.approval" +SPAN_AGENT_RUN = "invoke_agent txn-agent" +SPAN_CHAT = "chat {}" +SPAN_TOOL = "execute_tool {}" + +# --- OpenTelemetry GenAI semantic convention keys ------------------------------- +ATTR_OPERATION = "gen_ai.operation.name" +ATTR_PROVIDER = "gen_ai.provider.name" +ATTR_MODEL = "gen_ai.request.model" +ATTR_AGENT_NAME = "gen_ai.agent.name" +ATTR_TOOL_NAME = "gen_ai.tool.name" +ATTR_TOOL_CALL_ID = "gen_ai.tool.call.id" +ATTR_INPUT_TOKENS = "gen_ai.usage.input_tokens" +ATTR_OUTPUT_TOKENS = "gen_ai.usage.output_tokens" + +# --- domain keys ---------------------------------------------------------------- +ATTR_CART_ID = "txn_agent.cart.id" +ATTR_CART_TOTAL = "txn_agent.cart.total" +ATTR_CART_LINES = "txn_agent.cart.lines" +ATTR_MERCHANT = "txn_agent.merchant" +ATTR_VERTICAL = "txn_agent.vertical" +ATTR_GATE_DECISION = "txn_agent.gate.decision" +ATTR_GATE_REASONS = "txn_agent.gate.reasons" +ATTR_OUTCOME = "txn_agent.outcome" +ATTR_IDEMPOTENCY_KEY = "txn_agent.idempotency_key" +ATTR_APPROVAL_REQUIRED = "txn_agent.approval.required" +ATTR_APPROVED = "txn_agent.approval.approved" +ATTR_TOOL_ERROR = "txn_agent.tool.error" +ATTR_TURNS = "txn_agent.llm.turns" +ATTR_STOP_REASON = "txn_agent.llm.stop_reason" + +_ABSENT = object() + + +def _coerce(value: Any) -> Any: + """Map Python values onto the primitive types an attribute may hold.""" + from decimal import Decimal + + if isinstance(value, bool) or isinstance(value, (int, float, str)): + return value + if isinstance(value, Decimal): + return str(value) + if isinstance(value, (list, tuple)): + return [_coerce(v) for v in value] + if value is None: + return _ABSENT + return str(value) + + +class _NullSpan: + """Span-shaped no-op, so call sites never need a branch.""" + + def set_attribute(self, key: str, value: Any) -> None: # noqa: D102 - no-op + return None + + def add_event(self, name: str, attributes: Mapping[str, Any] | None = None) -> None: + return None + + def record_exception(self, exception: BaseException) -> None: + return None + + +class _NullContext: + def __enter__(self) -> _NullSpan: + return _NullSpan() + + def __exit__(self, *exc: object) -> Literal[False]: + return False + + +class _NullTracer: + def start_as_current_span(self, name: str, **kwargs: Any) -> _NullContext: + return _NullContext() + + +_TRACER: Any = _ABSENT + + +def _tracer() -> Any: + global _TRACER + if _TRACER is not _ABSENT: + return _TRACER + try: + from opentelemetry import trace # type: ignore[import-not-found, unused-ignore] + except ImportError: + _TRACER = _NullTracer() + else: + _TRACER = trace.get_tracer(INSTRUMENTATION_NAME) + return _TRACER + + +def configure(tracer: object) -> None: + """Install a tracer (a real one, or a test double). `None` restores detection.""" + global _TRACER + _TRACER = _ABSENT if tracer is None else tracer + + +def reset() -> None: + """Forget any injected tracer and re-detect OpenTelemetry on next use.""" + configure(None) + + +@contextmanager +def span(name: str, attributes: Mapping[str, Any] | None = None) -> Iterator[Any]: + """Open a span, set attributes as primitives, and never let tracing raise. + + Observability must not be able to break a purchase: a tracer that throws is + swallowed here rather than propagated into the transaction path. + """ + try: + ctx = _tracer().start_as_current_span(name) + except Exception: # pragma: no cover - defensive: a broken tracer is not fatal + yield _NullSpan() + return + with _ctx(ctx) as active: + if attributes: + set_attributes(active, attributes) + yield active + + +class _ctx: # noqa: N801 - tiny helper, private + """Enter whatever the tracer returned, falling back to a no-op span.""" + + def __init__(self, ctx: Any) -> None: + self._ctx = ctx + self._entered: Any = None + + def __enter__(self) -> Any: + try: + self._entered = self._ctx.__enter__() + except Exception: # pragma: no cover + self._entered = _NullSpan() + return self._entered if self._entered is not None else _NullSpan() + + def __exit__(self, *exc: object) -> Literal[False]: + # Never report suppression: a span must not swallow the caller's exception. + try: + self._ctx.__exit__(*exc) + except Exception: # pragma: no cover + pass + return False + + +def set_attributes(active: Any, attributes: Mapping[str, Any]) -> None: + for key, value in attributes.items(): + coerced = _coerce(value) + if coerced is _ABSENT: + continue + try: + active.set_attribute(key, coerced) + except Exception: # pragma: no cover + continue + + +def set_attribute(active: Any, key: str, value: Any) -> None: + set_attributes(active, {key: value}) + + +def add_event(active: Any, name: str, attributes: Mapping[str, Any] | None = None) -> None: + try: + active.add_event(name, attributes or {}) + except Exception: # pragma: no cover + return None + + +def record_exception(active: Any, exc: BaseException) -> None: + try: + active.record_exception(exc) + except Exception: # pragma: no cover + return None + + +def tool_span_name(tool: str) -> str: + return SPAN_TOOL.format(tool) + + +def chat_span_name(model: str) -> str: + return SPAN_CHAT.format(model) diff --git a/txn_agent/tools.py b/txn_agent/tools.py index 3fedafa..82cc801 100644 --- a/txn_agent/tools.py +++ b/txn_agent/tools.py @@ -5,6 +5,7 @@ from decimal import Decimal as D from typing import TYPE_CHECKING, Any +from . import telemetry from .agent import TransactionalAgent from .models import Cart, CartItem, Intent, Offer, Vertical, to_dict @@ -121,12 +122,24 @@ def _budget(self, requested: Any) -> D: raise ValueError(f"unparseable budget {requested!r}") from e def call(self, name: str, args: dict[str, Any]) -> dict[str, Any]: - try: - return self._dispatch(name, args) - except (KeyError, TypeError, ValueError) as e: - # Local/weak models send malformed arguments; fail soft so the loop can - # report the problem back to the model instead of crashing the run. - return {"error": f"invalid arguments for {name}: {e}"} + # Every tool execution is a span: the arguments are deliberately NOT recorded + # (they can carry user data), only the tool name, the outcome and an error + # class when the call failed. + with telemetry.span(telemetry.tool_span_name(name), { + telemetry.ATTR_OPERATION: "execute_tool", + telemetry.ATTR_TOOL_NAME: name, + telemetry.ATTR_VERTICAL: args.get("vertical"), + }) as active: + try: + out = self._dispatch(name, args) + except (KeyError, TypeError, ValueError) as e: + # Local/weak models send malformed arguments; fail soft so the loop can + # report the problem back to the model instead of crashing the run. + telemetry.set_attribute(active, telemetry.ATTR_TOOL_ERROR, "invalid_arguments") + return {"error": f"invalid arguments for {name}: {e}"} + if isinstance(out, dict) and "error" in out: + telemetry.set_attribute(active, telemetry.ATTR_TOOL_ERROR, str(out["error"])[:120]) + return out def _dispatch(self, name: str, args: dict[str, Any]) -> dict[str, Any]: if name == "search_offers":