Skip to content

Commit fbaac8e

Browse files
committed
fix(ag2): honour the latest setup() TraceConfig and traceAI context
R4: a second setup(..., config=TraceConfig(hide_inputs=True, hide_outputs=True)) on a provider that already had an AG2SpanProcessor was silently ignored, so content was exported despite the hide request (reviewer probe: gen_ai.input/output.messages still on the chat span). install_span_processor now applies an explicit config to the installed processor (AG2SpanProcessor.update_config; most recent call wins) and logs a warning when it changes. config=None keeps the installed config, so a later setup() never re-exposes content. R5: on_start did nothing, so using_session / using_user / using_metadata / using_attributes were ignored on AG2 spans. on_start now copies fi_instrumentation get_attributes_from_context() onto AG2-scope spans without overriding keys AG2 already set (later AG2 set_attribute calls still win), except session.id: the context session is re-applied in on_end so it beats a static span_attributes value. Pending sessions are kept in a bounded map keyed by (trace_id, span_id) and released on end. Foreign-scope spans are untouched. README (setup, sessions, conformance table), setup()/processor docstrings and CHANGELOG updated. Tests first, red on ec9fc07: test_later_setup_config_replaces_installed_ processor_config, test_using_session_sets_session_on_every_ag2_span, test_using_attributes_context_reaches_ag2_spans, test_context_session_wins_but_other_ag2_keys_are_not_overridden, test_pending_context_sessions_are_bounded_and_released_on_end (also red against a no-eviction mutant: 40 == 16). Guards that stay green: test_later_setup_without_config_keeps_installed_config, test_context_attributes_skip_foreign_scope_spans. 70 passed on ag2 1.1.2. approved: Nikhil 2026-10-03 blanket Refs: TH-8236
1 parent 30479c4 commit fbaac8e

6 files changed

Lines changed: 233 additions & 18 deletions

File tree

‎python/frameworks/ag2/CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,11 @@
1919
- Requires `fi-instrumentation-otel>=1.1.0` (was `>=1.0.0`): published 1.0.0
2020
crashes in `register()` with `opentelemetry-exporter-otlp-proto-http` 1.45.0
2121
(`AttributeError: 'HTTPSpanExporter' object has no attribute '_headers'`).
22+
- A later `setup(..., config=...)` on a provider that already has an
23+
`AG2SpanProcessor` now replaces that processor's `TraceConfig` (most recent
24+
call wins, warning logged when it changes) instead of being ignored;
25+
`config=None` keeps the installed config.
26+
- traceAI context helpers (`using_session`, `using_user`, `using_metadata`,
27+
`using_attributes`, ...) now reach AG2 spans: `AG2SpanProcessor.on_start`
28+
copies `get_attributes_from_context()` without overriding keys AG2 sets,
29+
except `session.id`, where the context wins over `span_attributes`.

‎python/frameworks/ag2/README.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,23 @@ worker = Agent("worker", config=cfg, middleware=[mw])
8787

8888
Call `setup(tracer_provider=trace_provider)` once in that case too, so the span
8989
processor is installed. `setup` is idempotent: an agent that already has a
90-
`TelemetryMiddleware` is skipped.
90+
`TelemetryMiddleware` is skipped. One `AG2SpanProcessor` serves the provider:
91+
a later `setup(..., config=TraceConfig(...))` replaces its `TraceConfig` (the
92+
most recent call wins and a warning is logged when it changes), while
93+
`config=None` keeps the current one.
94+
95+
Sessions and users come from traceAI's context helpers, as with the other
96+
traceAI integrations:
97+
98+
```python
99+
from fi_instrumentation import using_attributes, using_session
100+
101+
with using_session("chat-123"):
102+
reply = await agent.ask("Hello") # every AG2 span gets session.id="chat-123"
103+
104+
with using_attributes(session_id="chat-123", user_id="user-7", metadata={"tier": "pro"}):
105+
reply = await agent.ask("Hello")
106+
```
91107

92108
`provider_name` is never invented. Pass it if you want it on every span;
93109
otherwise AG2 fills it from the model response when the client reports one.
@@ -117,8 +133,8 @@ setup(agent, tracer_provider=trace_provider, capture_content=True) # opt in
117133
| Model | `gen_ai.request.model`, `gen_ai.response.model` pass through | When AG2 did not set them |
118134
| Provider | `gen_ai.provider.name` from `provider_name` or the model response | When neither is known |
119135
| Tokens | `gen_ai.usage.input_tokens` / `output_tokens` pass through; cache and thinking tokens are aliased and kept | When the usage field is zero/absent. Cost is not emitted |
120-
| Session | Not emitted by AG2 | Set it yourself: `setup(..., span_attributes={"session.id": "..."})` |
121-
| User | Not emitted | Always |
136+
| Session | Not emitted by AG2. `session.id` from traceAI's `using_session` / `using_attributes` context, which wins over a static value; or set it yourself: `setup(..., span_attributes={"session.id": "..."})` | When neither is set |
137+
| User, metadata, tags | `user.id`, `metadata`, `tag.tags` (and the other traceAI context keys) from `using_user` / `using_metadata` / `using_tags` / `using_attributes`; a key AG2 or `span_attributes` already set is not overridden | When the context does not set them |
122138
| Tools | `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.tool.type`; arguments/result only with `capture_content=True` | |
123139
| Errors | OTel status `ERROR` on failing tool / model / agent spans | |
124140

‎python/frameworks/ag2/tests/test_processor.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,21 @@ def test_agent_name_map_is_bounded():
268268
assert [set(v) for v in processor._agents_by_trace.values()] == [{"b"}, {"c"}]
269269

270270

271+
def test_pending_context_sessions_are_bounded_and_released_on_end():
272+
from fi_instrumentation import using_session
273+
274+
processor = AG2SpanProcessor(config=TraceConfig(), max_tracked_traces=1)
275+
provider = TracerProvider()
276+
provider.add_span_processor(processor)
277+
tracer = provider.get_tracer(AG2_INSTRUMENTATION_SCOPE)
278+
with using_session("s"):
279+
open_spans = [tracer.start_span(f"s{i}") for i in range(40)]
280+
assert len(processor._session_by_span) == processor._max_pending_spans == 16
281+
for span in open_spans:
282+
span.end()
283+
assert len(processor._session_by_span) == 0
284+
285+
271286
def test_processor_only_adds_keys_by_default(pipeline):
272287
"""Nothing AG2 set is stripped, including propagation-related keys."""
273288
provider, exporter = pipeline

‎python/frameworks/ag2/tests/test_setup.py‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88

99
import asyncio
1010
import inspect
11+
import logging
1112

1213
import pytest
1314
from fi_instrumentation.instrumentation.config import TraceConfig
@@ -114,6 +115,43 @@ def test_trace_config_is_a_second_gate_when_content_is_on():
114115
assert_no_content(attrs(span), span.name)
115116

116117

118+
def test_later_setup_config_replaces_installed_processor_config(caplog):
119+
"""README path: setup(tracer_provider=...) first, then setup(agent, config=...).
120+
The most recent explicit config wins and the change is logged."""
121+
provider, exporter = memory_provider()
122+
setup(tracer_provider=provider)
123+
agent = weather_agent()
124+
with caplog.at_level(logging.WARNING, logger="traceai_ag2"):
125+
setup(
126+
agent,
127+
tracer_provider=provider,
128+
capture_content=True,
129+
config=TraceConfig(hide_inputs=True, hide_outputs=True),
130+
)
131+
assert any("TraceConfig" in r.getMessage() for r in caplog.records), caplog.text
132+
chain = provider._active_span_processor._span_processors
133+
assert sum(isinstance(p, AG2SpanProcessor) for p in chain) == 1
134+
ask(agent)
135+
spans = exporter.get_finished_spans()
136+
assert spans
137+
for span in spans:
138+
assert_no_content(attrs(span), span.name)
139+
140+
141+
def test_later_setup_without_config_keeps_installed_config(caplog):
142+
"""config=None means "no change": a later setup() never re-exposes content."""
143+
provider, exporter = memory_provider()
144+
setup(tracer_provider=provider, config=TraceConfig(hide_inputs=True, hide_outputs=True))
145+
agent = weather_agent()
146+
with caplog.at_level(logging.WARNING, logger="traceai_ag2"):
147+
setup(agent, tracer_provider=provider, capture_content=True)
148+
setup(agent, tracer_provider=provider, config=TraceConfig(hide_inputs=True, hide_outputs=True))
149+
assert not [r for r in caplog.records if "TraceConfig" in r.getMessage()], caplog.text
150+
ask(agent)
151+
for span in exporter.get_finished_spans():
152+
assert_no_content(attrs(span), span.name)
153+
154+
117155
# --- span shape, kinds, model, usage ----------------------------------------
118156

119157

@@ -192,6 +230,75 @@ def test_app_can_stamp_session_through_span_attributes():
192230
assert attrs(span)["session.id"] == "sess-42", span.name
193231

194232

233+
def _ask_inside(agent, *context_managers):
234+
from contextlib import ExitStack
235+
236+
async def _run():
237+
with ExitStack() as stack:
238+
for cm in context_managers:
239+
stack.enter_context(cm)
240+
return await agent.ask(USER_PROMPT)
241+
242+
return asyncio.run(_run())
243+
244+
245+
def test_using_session_sets_session_on_every_ag2_span():
246+
from fi_instrumentation import using_session
247+
248+
provider, exporter = memory_provider()
249+
agent = weather_agent()
250+
setup(agent, tracer_provider=provider)
251+
_ask_inside(agent, using_session("sess-ctx-1"))
252+
spans = exporter.get_finished_spans()
253+
assert {s.name for s in spans} >= {"invoke_agent weather_bot", "execute_tool get_weather"}
254+
for span in spans:
255+
assert attrs(span).get("session.id") == "sess-ctx-1", span.name
256+
257+
258+
def test_using_attributes_context_reaches_ag2_spans():
259+
from fi_instrumentation import using_attributes
260+
261+
provider, exporter = memory_provider()
262+
agent = weather_agent()
263+
setup(agent, tracer_provider=provider)
264+
_ask_inside(agent, using_attributes(session_id="s-1", user_id="u-1", metadata={"tenant": "acme"}, tags=["t1"]))
265+
for span in exporter.get_finished_spans():
266+
a = attrs(span)
267+
assert a.get("session.id") == "s-1", span.name
268+
assert a.get("user.id") == "u-1", span.name
269+
assert "acme" in a.get("metadata", ""), span.name
270+
assert list(a.get("tag.tags", ())) == ["t1"], span.name
271+
272+
273+
def test_context_session_wins_but_other_ag2_keys_are_not_overridden():
274+
"""session.id from using_session replaces a static span_attributes value;
275+
any other key AG2 set itself is kept."""
276+
from fi_instrumentation import using_session, using_user
277+
278+
provider, exporter = memory_provider()
279+
agent = weather_agent()
280+
setup(agent, tracer_provider=provider, span_attributes={"session.id": "static", "user.id": "from-ag2"})
281+
_ask_inside(agent, using_session("dynamic"), using_user("from-context"))
282+
spans = exporter.get_finished_spans()
283+
assert spans
284+
for span in spans:
285+
a = attrs(span)
286+
assert a["session.id"] == "dynamic", span.name
287+
assert a["user.id"] == "from-ag2", span.name
288+
289+
290+
def test_context_attributes_skip_foreign_scope_spans():
291+
from fi_instrumentation import using_session
292+
293+
provider, exporter = memory_provider()
294+
setup(tracer_provider=provider)
295+
with using_session("sess-ctx-1"):
296+
with provider.get_tracer("some.other.instrumentation").start_as_current_span("other"):
297+
pass
298+
(span,) = exporter.get_finished_spans()
299+
assert "session.id" not in attrs(span)
300+
301+
195302
# --- AC-06 errors and cancellation -------------------------------------------
196303

197304

‎python/frameworks/ag2/traceai_ag2/_processor.py‎

Lines changed: 58 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,11 @@
1616
counts each model call once. ``aggregation`` and ``compaction`` usage keeps
1717
its promoted tokens: AG2 calls the model outside the middleware for those;
1818
* applies ``TraceConfig`` as a second content gate (``hide_inputs`` /
19-
``hide_outputs`` and the other ``TraceConfig.mask`` rules).
19+
``hide_outputs`` and the other ``TraceConfig.mask`` rules);
20+
* in ``on_start``, copies traceAI context attributes (``using_session``,
21+
``using_user``, ``using_metadata``, ``using_attributes``, ...) onto the span
22+
without overriding keys AG2 sets, except ``session.id``, where the context
23+
wins.
2024
2125
Spans from any other instrumentation scope pass through untouched.
2226
"""
@@ -26,10 +30,11 @@
2630
import logging
2731
import threading
2832
from collections import OrderedDict
29-
from typing import AbstractSet, Any, Dict, FrozenSet, Mapping, Optional, Set
33+
from typing import AbstractSet, Any, Dict, FrozenSet, Mapping, Optional, Set, Tuple
3034

3135
from fi_instrumentation.fi_types import FiSpanKindValues, SpanAttributes
3236
from fi_instrumentation.instrumentation.config import TraceConfig
37+
from fi_instrumentation.instrumentation.context_attributes import get_attributes_from_context
3338
from opentelemetry.context import Context
3439
from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
3540

@@ -141,6 +146,16 @@ def normalize_attributes(
141146
_SUBTASK_USAGE_KIND = "subtask"
142147
_USAGE_LABEL = "ag2.usage.label"
143148
_AGENT_NAME = "gen_ai.agent.name"
149+
_SESSION_ID = SpanAttributes.SESSION_ID # session.id
150+
151+
152+
def _scope_name(span: Any) -> Optional[str]:
153+
return getattr(getattr(span, "instrumentation_scope", None), "name", None)
154+
155+
156+
def _span_key(span: Any) -> Tuple[int, int]:
157+
ctx = span.context
158+
return (ctx.trace_id, ctx.span_id) if ctx is not None else (0, id(span))
144159

145160

146161
def _demote_duplicate_usage(mapped: Dict[str, Any], instrumented_agents: AbstractSet[str] = frozenset()) -> None:
@@ -200,6 +215,9 @@ def __init__(self, config: Optional[TraceConfig] = None, *, max_tracked_traces:
200215
self._shutdown = False
201216
self._max_tracked_traces = max(1, int(max_tracked_traces))
202217
self._agents_by_trace: "OrderedDict[int, Set[str]]" = OrderedDict()
218+
# Context session ids of AG2 spans that started but have not ended.
219+
self._max_pending_spans = 16 * self._max_tracked_traces
220+
self._session_by_span: "OrderedDict[Tuple[int, int], Any]" = OrderedDict()
203221
self._lock = threading.Lock()
204222

205223
def _note_agent(self, trace_id: int, attributes: Mapping[str, Any]) -> None:
@@ -222,21 +240,56 @@ def _agents_in(self, trace_id: int) -> FrozenSet[str]:
222240
with self._lock:
223241
return frozenset(self._agents_by_trace.get(trace_id, ()))
224242

243+
def update_config(self, config: TraceConfig) -> bool:
244+
"""Replace the ``TraceConfig`` applied to later spans; ``True`` if it changed."""
245+
with self._lock:
246+
if config == self._config:
247+
return False
248+
self._config = config
249+
return True
250+
225251
def on_start(self, span: Span, parent_context: Optional[Context] = None) -> None:
226-
return
252+
"""Copy traceAI context attributes (``using_session``, ``using_user``,
253+
``using_metadata``, ``using_attributes``, ...) onto AG2 spans.
254+
255+
A key AG2 already set is not overridden, and a key AG2 sets later wins,
256+
except ``session.id``: a session from the context replaces one from
257+
``span_attributes`` (re-applied in ``on_end``).
258+
"""
259+
if self._shutdown or _scope_name(span) != AG2_INSTRUMENTATION_SCOPE:
260+
return
261+
try:
262+
context_attributes = dict(get_attributes_from_context())
263+
if not context_attributes:
264+
return
265+
present = span.attributes or {}
266+
for key, value in context_attributes.items():
267+
if key == _SESSION_ID or key not in present:
268+
span.set_attribute(key, value)
269+
session = context_attributes.get(_SESSION_ID)
270+
if session is not None:
271+
with self._lock:
272+
self._session_by_span[_span_key(span)] = session
273+
while len(self._session_by_span) > self._max_pending_spans:
274+
self._session_by_span.popitem(last=False)
275+
except Exception: # pragma: no cover - defensive
276+
logger.debug("traceai-ag2: could not read context attributes for %r", getattr(span, "name", None), exc_info=True)
227277

228278
def on_end(self, span: ReadableSpan) -> None:
229279
if self._shutdown:
230280
return
231-
scope = getattr(getattr(span, "instrumentation_scope", None), "name", None)
232-
if scope != AG2_INSTRUMENTATION_SCOPE:
281+
if _scope_name(span) != AG2_INSTRUMENTATION_SCOPE:
233282
return
234283
try:
284+
with self._lock:
285+
session = self._session_by_span.pop(_span_key(span), None)
235286
current = dict(span.attributes or {})
236287
trace_id = span.context.trace_id if span.context is not None else 0
237288
self._note_agent(trace_id, current)
238289
agents = self._agents_in(trace_id) if current.get("ag2.usage.kind") == _SUBTASK_USAGE_KIND else frozenset()
239290
mapped = normalize_attributes(current, self._config, instrumented_agents=agents)
291+
if session is not None:
292+
mapped[_SESSION_ID] = session
240293
if mapped != current:
241294
# ``ReadableSpan.attributes`` is a read-only view over
242295
# ``_attributes``; every later processor and exporter in the

‎python/frameworks/ag2/traceai_ag2/_setup.py‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,10 @@ def install_span_processor(
7979
"""Install :class:`AG2SpanProcessor` ahead of the provider's exporters.
8080
8181
Returns ``True`` when installed, ``False`` when the provider has no span
82-
processor chain or already has an ``AG2SpanProcessor``.
82+
processor chain or already has an ``AG2SpanProcessor``. In the latter case
83+
an explicit ``config`` replaces the installed processor's ``TraceConfig``
84+
(the most recent call wins) and a warning is logged when it changes;
85+
``config=None`` leaves the installed config as it is.
8386
8487
The processor is prepended to the active multi-processor rather than added
8588
with ``add_span_processor``: the provider returned by
@@ -102,15 +105,23 @@ def install_span_processor(
102105
if lock is not None:
103106
with lock:
104107
existing = tuple(active._span_processors)
105-
if any(isinstance(p, AG2SpanProcessor) for p in existing):
106-
return False
107-
active._span_processors = (processor,) + existing
108+
installed = next((p for p in existing if isinstance(p, AG2SpanProcessor)), None)
109+
if installed is None:
110+
active._span_processors = (processor,) + existing
108111
else: # pragma: no cover - SDK multi-processors always carry a lock
109112
existing = tuple(active._span_processors)
110-
if any(isinstance(p, AG2SpanProcessor) for p in existing):
111-
return False
112-
active._span_processors = (processor,) + existing
113-
return True
113+
installed = next((p for p in existing if isinstance(p, AG2SpanProcessor)), None)
114+
if installed is None:
115+
active._span_processors = (processor,) + existing
116+
if installed is None:
117+
return True
118+
if config is not None and installed.update_config(config):
119+
logger.warning(
120+
"traceai-ag2: an AG2SpanProcessor was already installed on this provider; "
121+
"its TraceConfig is now replaced by the one from the latest call: %r",
122+
config,
123+
)
124+
return False
114125

115126

116127
def _has_telemetry_middleware(agent: Any) -> bool:
@@ -154,10 +165,15 @@ def setup(
154165
capture_content: Forwarded to ``TelemetryMiddleware``. Defaults to
155166
``False``, overriding AG2's upstream default of ``True``.
156167
provider_name, model_name, span_attributes, max_tool_result_chars:
157-
Forwarded to ``TelemetryMiddleware``. ``span_attributes`` is how an
158-
app stamps ``session.id`` on every span; AG2 emits no session id.
168+
Forwarded to ``TelemetryMiddleware``. ``span_attributes`` is one
169+
way to stamp ``session.id`` on every span (AG2 emits no session
170+
id); traceAI's ``using_session`` context takes precedence.
159171
config: ``TraceConfig`` applied by the span processor as a second
160172
content gate. Defaults to ``TraceConfig()`` (reads ``FI_HIDE_*``).
173+
One processor serves the whole provider: when it is already
174+
installed, an explicit ``config`` replaces its config (the most
175+
recent call wins, with a warning when it changes) and
176+
``config=None`` keeps the installed one.
161177
162178
Returns:
163179
The tracer provider in use. Short scripts call ``force_flush()`` on it

0 commit comments

Comments
 (0)