Skip to content

Commit ff8e7ba

Browse files
nik13claude
andcommitted
fix(strands): skip Strands' OTLP exporter only for an exact duplicate on a provider that keeps its exporter (TH-8727)
43e25de skipped Strands' OTLP exporter whenever a processor on the provider exported to the same host and port. Review found two ways that loses spans: - On fi-instrumentation-otel 1.1.0, register() still marks its exporter as a default the next add_span_processor() call replaces. With OTEL_EXPORTER_OTLP_* at Future AGI, the skip left that marked exporter as the only one, and the next processor (enable_console_exporter=True, or one the application adds) replaced it: Future AGI got nothing. traceai-strands 0.1.0 never hit this, because Strands' own exporter consumed the mark. - When register() ran without FI keys and the keys reached Strands' exporter through otlp_headers or OTEL_EXPORTER_OTLP_HEADERS, the skip removed the only exporter Future AGI would accept. The exporter is now skipped only when all of these hold: - the provider would keep its exporter on the next add_span_processor() call: no `_default_processor` mark on that provider. This is the flag the core's add_span_processor() override reads, checked on the provider being configured rather than through a version number. On 1.1.0 Strands' exporter is then added exactly as in 0.1.0. A bare fi_instrumentation TracerProvider() whose construction default is still pending replacement is covered by the same check. - a processor on the provider exports to the same traces URL: scheme, userinfo, host, port (default filled in), path (repeated and trailing slashes dropped) and query, instead of host and port only; - that exporter already sends every header Strands' exporter would send, with the same value, and no client certificate or credential provider is set for Strands' exporter. Strands' endpoint and headers come from an upstream OTLPSpanExporter built with no arguments, as Strands builds it, read back and shut down. That follows the installed exporter release: 1.45 merges environment headers into passed ones and moved them to `_client`, and treats an empty OTEL_EXPORTER_OTLP_TRACES_ENDPOINT differently from 1.29-1.39. A floor of fi-instrumentation-otel>=1.1.1 was not added: it would make traceai-strands 0.1.1 uninstallable until the core is published (and fail this repo's CI install from PyPI), tie it to a version number that changes if #272 ships first, and still not protect an environment resolved without it (--no-deps, a lock pinned to 1.1.0). Tests: unit tests for each rule (URL parts and spellings, keys only on one side, other keys, x-project-name, unreadable headers, mTLS and credential-provider variables, both header layouts, the marked provider). README Option 1 run for real, now also with the console exporter, a processor added afterwards, keys only on Strands' exporter and a base endpoint, on the repo core and on 1.1.0. README Option 1 and the CHANGELOG say exactly when the exporter is added. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 43e25de commit ff8e7ba

6 files changed

Lines changed: 564 additions & 111 deletions

File tree

‎python/frameworks/strands/CHANGELOG.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,19 @@
11
## [0.1.1] - 2026-10-21
22
### Fixed
3-
- `configure_strands_tracing()` no longer adds Strands' OTLP span exporter for a collector the tracer provider already
4-
exports to. With the provider `fi_instrumentation.register()` returns and `OTEL_EXPORTER_OTLP_*` pointing at Future AGI,
5-
every span reached Future AGI twice once fi-instrumentation-otel stopped dropping `register()`'s exporter when another
6-
span processor is added (TH-8727). The skip is logged at INFO. Strands' OTLP exporter is still added for any other
7-
collector, including the default `localhost:4318`, and the console exporter and meter are set up as before.
3+
- `configure_strands_tracing()` no longer adds Strands' OTLP span exporter when it would only send copies of what the
4+
tracer provider already sends. With the provider `fi_instrumentation.register()` returns and `OTEL_EXPORTER_OTLP_*`
5+
pointing at Future AGI, every span reached Future AGI twice once fi-instrumentation-otel stopped dropping
6+
`register()`'s exporter when another span processor is added (TH-8727). The exporter is skipped, with an INFO log line,
7+
only when all of these hold:
8+
- a span processor on the provider already exports to the same traces URL (scheme, host, port, path and query,
9+
normalised; credentials in the URL must match too);
10+
- that exporter already sends every header Strands' exporter would send, with the same value, and no client
11+
certificate or credential provider is set for Strands' exporter;
12+
- the provider keeps that exporter when another span processor is added. On fi-instrumentation-otel 1.1.0 and
13+
earlier it does not, so there Strands' exporter is added exactly as in 0.1.0.
14+
15+
Strands' OTLP exporter is still added in every other case, including the default `localhost:4318`, and the console
16+
exporter and meter are set up as before.
817

918
## [0.1.0]
1019
### Feature

‎python/frameworks/strands/README.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,15 @@ agent = Agent(
5454
response = agent("Hello!")
5555
```
5656

57-
`register()`'s exporter sends the spans to Future AGI, so Option 1 needs no `OTEL_EXPORTER_OTLP_*` setting. Set `OTEL_EXPORTER_OTLP_*` only to send a second copy to another collector: Strands' own OTLP exporter is added for it. When those variables point at a collector the provider already exports to, such as Future AGI, that exporter is not added, so spans are not sent twice. On fi-instrumentation-otel 1.1.0 and earlier, Strands adding its own exporter replaced `register()`'s, so spans stopped reaching Future AGI: upgrade fi-instrumentation-otel as well.
57+
`register()`'s exporter sends the spans to Future AGI, so Option 1 needs no `OTEL_EXPORTER_OTLP_*` setting for that. `configure_strands_tracing()` still adds Strands' own OTLP exporter, for the traces URL the `OTEL_EXPORTER_OTLP_*` variables resolve to: `http://localhost:4318/v1/traces` when none is set, which logs export errors when no collector listens there. Point the variables at another collector to send it a second copy.
58+
59+
Strands' exporter is not added, so spans do not reach Future AGI twice, only when all of these hold:
60+
61+
- The variables resolve to the traces URL `register()` exports to, `<FI_BASE_URL>/tracer/v1/traces`, for example `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.futureagi.com/tracer/v1/traces`. `OTEL_EXPORTER_OTLP_ENDPOINT=https://api.futureagi.com` resolves to `https://api.futureagi.com/v1/traces`, another URL.
62+
- Every header Strands' exporter would send (from `OTEL_EXPORTER_OTLP_HEADERS`, `otlp_headers=` or `project_name=`) is one `register()`'s exporter already sends, with the same value. Keys only Strands' exporter carries, or other keys, keep it. So does a client certificate or credential provider set for it.
63+
- The provider keeps its exporter when another span processor is added.
64+
65+
On fi-instrumentation-otel 1.1.0 and earlier, the first span processor added to the provider `register()` returns replaces its exporter. Strands' exporter is then always added and is the only one left, so spans reach Future AGI only when the variables point there, with your keys in `OTEL_EXPORTER_OTLP_HEADERS`. Upgrade fi-instrumentation-otel.
5866

5967
### Option 2: Direct OTLP Configuration
6068

@@ -225,7 +233,7 @@ The integration captures these OpenTelemetry GenAI semantic attributes:
225233

226234
## Environment Variables
227235

228-
Strands respects standard OpenTelemetry environment variables. With Option 1 they are optional and configure a second destination; see Option 1 above.
236+
Strands respects standard OpenTelemetry environment variables. With Option 1 they only set where Strands' own OTLP exporter sends; see Option 1 above.
229237

230238
```bash
231239
# OTLP endpoint

‎python/frameworks/strands/tests/strands_export_scenario.py‎

Lines changed: 77 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,31 @@
22
33
Run by test_real_export.py in a fresh interpreter, because conftest.py replaces opentelemetry,
44
fi_instrumentation and strands with mocks for the rest of the test session. Two OTLP/HTTP
5-
collectors on 127.0.0.1 record the span names they receive: one is Future AGI (FI_BASE_URL), the
6-
other a second backend.
7-
8-
argv[1] says where OTEL_EXPORTER_OTLP_TRACES_ENDPOINT points Strands' own OTLP exporter:
9-
"future-agi" the Future AGI collector, as the README's environment section suggests
10-
"other" the second collector
11-
12-
Prints one JSON line with what each collector received.
5+
collectors on 127.0.0.1 record the spans they receive, with the X-Api-Key each request carried:
6+
one is Future AGI (FI_BASE_URL), the other a second backend.
7+
8+
argv[1] says where Strands' own OTLP exporter is pointed:
9+
"future-agi" OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, at register()'s Future AGI traces URL
10+
"future-agi-base" OTEL_EXPORTER_OTLP_ENDPOINT, a base URL that resolves to that same URL
11+
"other" OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, at the second collector
12+
Options:
13+
--keys {fi,both,strands} who carries the Future AGI keys: register() only, through
14+
FI_API_KEY/FI_SECRET_KEY (default); register() and Strands' exporter,
15+
the same keys also in OTEL_EXPORTER_OTLP_HEADERS; or Strands' exporter
16+
only, through configure_strands_tracing(otlp_headers=...)
17+
--console configure_strands_tracing(enable_console_exporter=True)
18+
--processor-after the application adds an in-memory span processor afterwards
19+
20+
Prints one line, "SCENARIO_RESULT <json>", with what each collector received.
1321
1422
strands-agents is not a dev dependency. Without it, `strands.telemetry` is a copy of the part of
1523
strands-agents' StrandsTelemetry this package calls: setup_otlp_exporter() wraps the upstream
16-
OTLP/HTTP span exporter in a BatchSpanProcessor and adds it to the provider. With strands-agents
24+
OTLP/HTTP span exporter in a BatchSpanProcessor and adds it to the provider, and
25+
setup_console_exporter() adds a SimpleSpanProcessor with a ConsoleSpanExporter. With strands-agents
1726
installed, the real StrandsTelemetry is used.
1827
"""
1928

29+
import argparse
2030
import gzip
2131
import json
2232
import os
@@ -28,9 +38,14 @@
2838

2939
from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest
3040

41+
RESULT_PREFIX = "SCENARIO_RESULT "
42+
API_KEY = "test-api-key"
43+
SECRET_KEY = "test-secret-key"
3144

32-
def _collector() -> Tuple[ThreadingHTTPServer, List[str]]:
33-
received: List[str] = []
45+
46+
def _collector() -> Tuple[ThreadingHTTPServer, List[Tuple[str, str]]]:
47+
"""An OTLP/HTTP collector recording (span name, X-Api-Key or "") for every span it receives."""
48+
received: List[Tuple[str, str]] = []
3449

3550
class _Handler(BaseHTTPRequestHandler):
3651
def do_POST(self) -> None:
@@ -39,8 +54,9 @@ def do_POST(self) -> None:
3954
body = gzip.decompress(body)
4055
request = ExportTraceServiceRequest()
4156
request.ParseFromString(body)
57+
api_key = self.headers.get("X-Api-Key", "")
4258
received.extend(
43-
span.name
59+
(span.name, api_key)
4460
for resource_spans in request.resource_spans
4561
for scope_spans in resource_spans.scope_spans
4662
for span in scope_spans.spans
@@ -67,7 +83,11 @@ def _install_strands_telemetry_stand_in() -> bool:
6783
pass
6884

6985
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
70-
from opentelemetry.sdk.trace.export import BatchSpanProcessor
86+
from opentelemetry.sdk.trace.export import (
87+
BatchSpanProcessor,
88+
ConsoleSpanExporter,
89+
SimpleSpanProcessor,
90+
)
7191

7292
class StrandsTelemetry:
7393
def __init__(self, tracer_provider: Any = None) -> None:
@@ -77,6 +97,12 @@ def setup_otlp_exporter(self, **kwargs: Any) -> "StrandsTelemetry":
7797
self.tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(**kwargs)))
7898
return self
7999

100+
def setup_console_exporter(self, **kwargs: Any) -> "StrandsTelemetry":
101+
self.tracer_provider.add_span_processor(
102+
SimpleSpanProcessor(ConsoleSpanExporter(**kwargs))
103+
)
104+
return self
105+
80106
strands = types.ModuleType("strands")
81107
telemetry = types.ModuleType("strands.telemetry")
82108
telemetry.StrandsTelemetry = StrandsTelemetry
@@ -87,30 +113,41 @@ def setup_otlp_exporter(self, **kwargs: Any) -> "StrandsTelemetry":
87113

88114

89115
def main() -> None:
90-
mode = sys.argv[1]
116+
parser = argparse.ArgumentParser()
117+
parser.add_argument("mode", choices=["future-agi", "future-agi-base", "other"])
118+
parser.add_argument("--keys", choices=["fi", "both", "strands"], default="fi")
119+
parser.add_argument("--console", action="store_true")
120+
parser.add_argument("--processor-after", action="store_true")
121+
args = parser.parse_args()
122+
91123
future_agi, future_agi_received = _collector()
92124
other, other_received = _collector()
93125
future_agi_url = f"http://127.0.0.1:{future_agi.server_address[1]}"
94126

95127
for name in list(os.environ):
96-
if name.startswith("OTEL_"):
128+
if name.startswith(("OTEL_", "_OTEL_", "FI_")):
97129
del os.environ[name]
98130
os.environ["FI_BASE_URL"] = future_agi_url
99-
os.environ["FI_API_KEY"] = "test-api-key"
100-
os.environ["FI_SECRET_KEY"] = "test-secret-key"
101-
if mode == "future-agi":
131+
if args.keys in ("fi", "both"):
132+
os.environ["FI_API_KEY"] = API_KEY
133+
os.environ["FI_SECRET_KEY"] = SECRET_KEY
134+
if args.keys == "both":
135+
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"X-Api-Key={API_KEY},X-Secret-Key={SECRET_KEY}"
136+
if args.mode == "future-agi":
102137
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = f"{future_agi_url}/tracer/v1/traces"
103-
elif mode == "other":
138+
elif args.mode == "future-agi-base":
139+
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = f"{future_agi_url}/tracer/"
140+
else:
104141
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = (
105142
f"http://127.0.0.1:{other.server_address[1]}/v1/traces"
106143
)
107-
else:
108-
raise SystemExit(f"unknown mode {mode!r}")
109144

110145
real_strands = _install_strands_telemetry_stand_in()
111146

112147
from fi_instrumentation import register
113148
from fi_instrumentation.fi_types import ProjectType
149+
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
150+
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
114151

115152
from traceai_strands import configure_strands_tracing
116153

@@ -124,23 +161,37 @@ def main() -> None:
124161
# next add_span_processor() call replaces (fixed by TH-8727).
125162
register_marks_its_exporter = bool(getattr(provider, "_default_processor", False))
126163

127-
configure_strands_tracing(tracer_provider=provider, enable_metrics=False)
128-
164+
configure_strands_tracing(
165+
tracer_provider=provider,
166+
otlp_headers=(
167+
{"X-Api-Key": API_KEY, "X-Secret-Key": SECRET_KEY} if args.keys == "strands" else None
168+
),
169+
enable_console_exporter=args.console,
170+
enable_metrics=False,
171+
)
129172
span_processors = len(provider._active_span_processor._span_processors)
173+
174+
added_after = InMemorySpanExporter()
175+
if args.processor_after:
176+
provider.add_span_processor(SimpleSpanProcessor(added_after))
177+
130178
tracer = provider.get_tracer("traceai-strands-test")
131179
for i in range(3):
132180
with tracer.start_as_current_span(f"span-{i}"):
133181
pass
134182
provider.force_flush(timeout_millis=10_000)
135183

136184
print(
137-
json.dumps(
185+
RESULT_PREFIX
186+
+ json.dumps(
138187
{
139188
"real_strands": real_strands,
140189
"register_marks_its_exporter": register_marks_its_exporter,
141190
"span_processors": span_processors,
142-
"future_agi": sorted(future_agi_received),
143-
"other": sorted(other_received),
191+
"future_agi": sorted(name for name, _ in future_agi_received),
192+
"future_agi_with_keys": sorted(name for name, key in future_agi_received if key),
193+
"other": sorted(name for name, _ in other_received),
194+
"added_after": sorted(s.name for s in added_after.get_finished_spans()),
144195
}
145196
),
146197
flush=True,

0 commit comments

Comments
 (0)