Repository navigation
Commit c22fb91
authored
feat(sdk): add optional traceprovider parameter (#260)
## Summary
- The built-in OTEL observability sink always created its own
`TracerProvider`, exporter, and span processor. Applications that
already run OTEL (e.g. Google ADK via `GoogleADKInstrumentor`) ended up
with two disconnected pipelines, splitting application and control spans
across separate export requests.
- Adds an optional `otel_tracer_provider` param to
`agent_control.init()` so the built-in `otel` sink can reuse an
application-owned or globally-registered SDK provider instead of always
creating its own.
## Scope
- **User-facing/API changes:**
- New optional `otel_tracer_provider` kwarg on `agent_control.init()` /
`init_observability()`.
- Applied only when `observability_sink_name="otel"`; ignored for
`default`, `registered`, and other named sinks.
- Provider resolution order: explicit param → valid globally-registered
OTEL SDK `TracerProvider` (via `trace.get_tracer_provider()`) → Agent
Control-owned provider (existing behavior).
- The default OTEL proxy/no-op provider is never treated as a configured
provider.
- README documents a Google ADK shared-provider example.
- **Internal changes:**
- `otel_sink.py`: `create_otel_control_event_sink()` accepts a
`tracer_provider` kwarg, tracks `provider_owned`, and only attaches an
Agent Control exporter/`BatchSpanProcessor` when it creates the provider
itself. OTLP exporter import is now lazy and skipped entirely on the
external-provider path.
- `observability.py`: provider is threaded through a runtime-only global
(`_configured_otel_tracer_provider`), not the JSON-typed
`observability_sink_config`. Changing the explicit provider on
reinitialization invalidates only the cached OTEL sink, leaving other
sink caches untouched.
- `OTELControlEventSink.close()` flushes external providers but no
longer shuts them down; Agent Control-created providers are still shut
down as before.
- **Out of scope:** Orbit, ingest-service, Galileo Python SDK, and
customer application code were not touched. No changes to `default`,
`registered`, or other named custom sink behavior.
## Risk and Rollout
- **Risk level:** low — the new parameter defaults to `None` and only
affects behavior when `observability_sink_name="otel"`; all other sink
paths are unchanged.
- **Rollback plan:** revert the commit; no data migrations, schema
changes, or server-side changes are involved (Python SDK only).
## Testing
- [x] Added or updated automated tests — `test_otel_sink.py`
(explicit-provider precedence, provider-owned vs. external, proxy/no-op
rejection, no duplicate processor, trace/parent correlation,
lifecycle/shutdown ownership, reinitialization invalidation) and
`test_init_validation.py` (runtime-only path, not leaked into
`sink_config`).
- [x] Ran equivalent of `make check`: `uv run pytest` (644 passed, 1
pre-existing unrelated failure requiring a live server, confirmed
failing on the prior commit too), `uv run mypy src/agent_control`
(clean), `uv run ruff check src/` (clean, matches the `make lint`
target).
- [x] Manually verified behavior — traced through provider resolution
order, shutdown/ownership branches, and cache invalidation logic against
each acceptance criterion in the spec; no regressions found in
default/registered/custom sink paths.
## Checklist
- [x] Linked issue/spec (SAO-16152 — reuse existing OTEL provider in
Agent Control Python SDK)
- [x] Updated docs/examples for user-facing changes (README: Google ADK
shared-provider example)
- [ ] Included any required follow-up tasks — none identified1 parent 541f872 commit c22fb91
6 files changed
Lines changed: 516 additions & 22 deletions
File tree
- sdks/python
- src/agent_control
- tests
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
| 41 | + | |
| 42 | + | |
41 | 43 | | |
42 | 44 | | |
43 | 45 | | |
| |||
51 | 53 | | |
52 | 54 | | |
53 | 55 | | |
54 | | - | |
| 56 | + | |
55 | 57 | | |
56 | 58 | | |
57 | 59 | | |
| |||
123 | 125 | | |
124 | 126 | | |
125 | 127 | | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
126 | 131 | | |
127 | 132 | | |
128 | 133 | | |
| |||
460 | 465 | | |
461 | 466 | | |
462 | 467 | | |
| 468 | + | |
463 | 469 | | |
464 | 470 | | |
465 | 471 | | |
| |||
514 | 520 | | |
515 | 521 | | |
516 | 522 | | |
| 523 | + | |
| 524 | + | |
| 525 | + | |
| 526 | + | |
517 | 527 | | |
518 | 528 | | |
519 | 529 | | |
| |||
738 | 748 | | |
739 | 749 | | |
740 | 750 | | |
| 751 | + | |
741 | 752 | | |
742 | 753 | | |
743 | 754 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
83 | 83 | | |
84 | 84 | | |
85 | 85 | | |
| 86 | + | |
86 | 87 | | |
87 | 88 | | |
88 | 89 | | |
| |||
833 | 834 | | |
834 | 835 | | |
835 | 836 | | |
| 837 | + | |
| 838 | + | |
836 | 839 | | |
837 | 840 | | |
838 | 841 | | |
| |||
842 | 845 | | |
843 | 846 | | |
844 | 847 | | |
845 | | - | |
| 848 | + | |
| 849 | + | |
| 850 | + | |
| 851 | + | |
| 852 | + | |
| 853 | + | |
| 854 | + | |
| 855 | + | |
| 856 | + | |
846 | 857 | | |
847 | 858 | | |
848 | 859 | | |
| |||
976 | 987 | | |
977 | 988 | | |
978 | 989 | | |
979 | | - | |
| 990 | + | |
| 991 | + | |
980 | 992 | | |
981 | 993 | | |
| 994 | + | |
| 995 | + | |
| 996 | + | |
| 997 | + | |
| 998 | + | |
982 | 999 | | |
983 | 1000 | | |
984 | 1001 | | |
985 | 1002 | | |
986 | 1003 | | |
| 1004 | + | |
987 | 1005 | | |
988 | 1006 | | |
989 | 1007 | | |
| |||
1004 | 1022 | | |
1005 | 1023 | | |
1006 | 1024 | | |
| 1025 | + | |
1007 | 1026 | | |
1008 | 1027 | | |
1009 | 1028 | | |
| |||
1051 | 1070 | | |
1052 | 1071 | | |
1053 | 1072 | | |
1054 | | - | |
| 1073 | + | |
| 1074 | + | |
1055 | 1075 | | |
1056 | 1076 | | |
1057 | 1077 | | |
1058 | 1078 | | |
1059 | 1079 | | |
1060 | 1080 | | |
| 1081 | + | |
1061 | 1082 | | |
1062 | 1083 | | |
1063 | 1084 | | |
1064 | 1085 | | |
1065 | 1086 | | |
| 1087 | + | |
| 1088 | + | |
| 1089 | + | |
| 1090 | + | |
| 1091 | + | |
| 1092 | + | |
| 1093 | + | |
| 1094 | + | |
| 1095 | + | |
| 1096 | + | |
| 1097 | + | |
| 1098 | + | |
| 1099 | + | |
| 1100 | + | |
| 1101 | + | |
| 1102 | + | |
| 1103 | + | |
| 1104 | + | |
| 1105 | + | |
| 1106 | + | |
| 1107 | + | |
1066 | 1108 | | |
1067 | 1109 | | |
1068 | 1110 | | |
| |||
1109 | 1151 | | |
1110 | 1152 | | |
1111 | 1153 | | |
| 1154 | + | |
1112 | 1155 | | |
1113 | 1156 | | |
1114 | 1157 | | |
| |||
1122 | 1165 | | |
1123 | 1166 | | |
1124 | 1167 | | |
| 1168 | + | |
1125 | 1169 | | |
1126 | 1170 | | |
1127 | 1171 | | |
1128 | 1172 | | |
1129 | | - | |
| 1173 | + | |
1130 | 1174 | | |
1131 | 1175 | | |
1132 | 1176 | | |
| |||
1144 | 1188 | | |
1145 | 1189 | | |
1146 | 1190 | | |
| 1191 | + | |
| 1192 | + | |
| 1193 | + | |
| 1194 | + | |
| 1195 | + | |
| 1196 | + | |
| 1197 | + | |
| 1198 | + | |
| 1199 | + | |
| 1200 | + | |
| 1201 | + | |
1147 | 1202 | | |
1148 | 1203 | | |
1149 | 1204 | | |
| |||
0 commit comments