Skip to content

Commit 763008e

Browse files
lesnik512claude
andauthored
fix(otel): split opentelemetry api/sdk presence so [fastmcp] imports (#154)
is_opentelemetry_installed (find_spec("opentelemetry")) is True with only opentelemetry-api, but the OTel instrument imports opentelemetry.sdk.* — so any api-only environment (e.g. lite-bootstrap[fastmcp], which pulls bare opentelemetry-api transitively) crashed `import lite_bootstrap`. Add is_opentelemetry_sdk_installed, gate the instrument's sdk imports on it, and require api+sdk in check_dependencies. Also warn (instead of silently skipping) when opentelemetry_endpoint is set but the gRPC OTLP exporter is absent. Promotes architecture/instruments.md (three-way api/sdk/exporter guard) and clears the OTel-stack dependency-model deferral. Reproduced the crash on a regular 3.12 interpreter; fixed and verified `[fastmcp]` now imports. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 650206f commit 763008e

6 files changed

Lines changed: 208 additions & 87 deletions

File tree

‎architecture/instruments.md‎

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -61,26 +61,31 @@ lite_bootstrap`. `import_checker._safe_find_spec` wraps `find_spec` for dotted
6161
names and treats that exception as absent; `is_fastapi_opentelemetry_installed`
6262
and `is_litestar_opentelemetry_installed` both route through it.
6363

64-
**`is_otlp_grpc_exporter_installed` is a separate guard from
65-
`is_opentelemetry_installed`.** `is_opentelemetry_installed` only means
66-
`opentelemetry-api` resolves — it says nothing about the SDK or the gRPC OTLP
67-
exporter package. `opentelemetry_instrument.py` used to import the gRPC
68-
exporter unconditionally under that coarse guard, crashing `import
69-
lite_bootstrap` in any environment with bare `opentelemetry-api` present (e.g.
70-
`lite-bootstrap[fastmcp]`, which pulls it in transitively without the rest of
71-
the stack). The exporter import — and its use in `bootstrap()` — now sit behind
72-
their own `import_checker.is_otlp_grpc_exporter_installed` guard
73-
(`_safe_find_spec("opentelemetry.exporter.otlp.proto.grpc.trace_exporter")`).
74-
The honest trade-off: `check_dependencies()` still gates OpenTelemetry
75-
activation on `is_opentelemetry_installed` alone, so setting
76-
`opentelemetry_endpoint` in an environment where `opentelemetry-api` is present
77-
but the exporter package is not now **silently skips OTLP export** —
78-
`bootstrap()`'s exporter block simply omits the span processor when
79-
`is_otlp_grpc_exporter_installed` is False, with none of the
80-
`InstrumentDependencyMissingWarning` a configured-but-missing dependency
81-
normally gets. Making `check_dependencies()` distinguish api/sdk/exporter
82-
presence, so this case gets the standard warning instead of silence, is
83-
deferred — see `planning/deferred.md`.
64+
**OpenTelemetry resolves as three independent distributions: api, sdk, exporter.**
65+
`opentelemetry-api` (the `opentelemetry.trace`/`.metrics`/`.context` namespace),
66+
`opentelemetry-sdk` (`opentelemetry.sdk.*`), and each OTLP exporter package are
67+
separate PyPI distributions — a real environment can have any subset. Three
68+
`import_checker` flags mirror that:
69+
70+
- **`is_opentelemetry_installed`** (`find_spec("opentelemetry")`) — the api. The
71+
six api-only consumers (logging trace-injection, framework
72+
`get_tracer_provider`, faststream health-check spans) import only
73+
`opentelemetry.trace`/`.metrics` and gate on this.
74+
- **`is_opentelemetry_sdk_installed`** (`_safe_find_spec("opentelemetry.sdk")`) —
75+
the sdk. `opentelemetry_instrument.py` imports `opentelemetry.sdk.*`, so its
76+
module-level import block gates on this, and `check_dependencies()` requires
77+
**both** api and sdk. Without the split, bare `opentelemetry-api` (e.g.
78+
`lite-bootstrap[fastmcp]`, which pulls it transitively without the sdk) crashed
79+
`import lite_bootstrap` at `from opentelemetry.sdk import resources`.
80+
- **`is_otlp_grpc_exporter_installed`**
81+
(`_safe_find_spec("opentelemetry.exporter.otlp.proto.grpc.trace_exporter")`) —
82+
the gRPC OTLP exporter. Its import and its use in `bootstrap()` sit behind this
83+
guard; importing it unconditionally under the api flag previously crashed
84+
`import lite_bootstrap` the same way. When `opentelemetry_endpoint` is set but
85+
the exporter package is absent, `bootstrap()` emits an
86+
`InstrumentDependencyMissingWarning` ("…spans will not be exported. Install
87+
lite-bootstrap[otl].") rather than silently omitting the span processor — the
88+
standard configured-but-missing signal.
8489

8590
## Why instruments are not frozen
8691

‎lite_bootstrap/import_checker.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ def _safe_find_spec(module_name: str) -> bool:
1515

1616

1717
is_opentelemetry_installed = find_spec("opentelemetry") is not None
18+
# opentelemetry-api provides the `opentelemetry` namespace (trace, metrics) without the
19+
# sdk. The OTel instrument imports opentelemetry.sdk.* and needs this stricter check;
20+
# api-only consumers (logging trace-injection, framework get_tracer_provider) use the
21+
# flag above. See architecture/instruments.md.
22+
is_opentelemetry_sdk_installed = _safe_find_spec("opentelemetry.sdk")
1823
is_sentry_installed = find_spec("sentry_sdk") is not None
1924
is_structlog_installed = find_spec("structlog") is not None
2025
is_prometheus_client_installed = find_spec("prometheus_client") is not None

‎lite_bootstrap/instruments/opentelemetry_instrument.py‎

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@
66
import warnings
77

88
from lite_bootstrap import import_checker
9-
from lite_bootstrap.exceptions import TeardownError
9+
from lite_bootstrap.exceptions import InstrumentDependencyMissingWarning, TeardownError
1010
from lite_bootstrap.instruments.base import BaseConfig, BaseInstrument
1111

1212

1313
if typing.TYPE_CHECKING:
1414
from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
1515

16-
if import_checker.is_opentelemetry_installed:
16+
if import_checker.is_opentelemetry_sdk_installed:
1717
from opentelemetry.context import Context
1818
from opentelemetry.sdk import resources
1919
from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, TracerProvider
@@ -91,7 +91,7 @@ def _parse_remote_insecure_host(self) -> str | None:
9191
return host
9292

9393

94-
if import_checker.is_opentelemetry_installed and import_checker.is_pyroscope_installed:
94+
if import_checker.is_opentelemetry_sdk_installed and import_checker.is_pyroscope_installed:
9595
_OTEL_PROFILE_ID_KEY: typing.Final = "pyroscope.profile.id"
9696
_PYROSCOPE_SPAN_ID_KEY: typing.Final = "span_id"
9797
_PYROSCOPE_SPAN_NAME_KEY: typing.Final = "span_name"
@@ -131,7 +131,7 @@ class OpenTelemetryInstrument(BaseInstrument[OpenTelemetryConfig]):
131131
"""
132132

133133
not_ready_message = "opentelemetry_endpoint is empty and opentelemetry_log_traces is False"
134-
missing_dependency_message = "opentelemetry is not installed"
134+
missing_dependency_message = "opentelemetry-sdk is not installed"
135135
_tracer_provider: "TracerProvider | None" = dataclasses.field(
136136
default_factory=lambda: None, init=False, repr=False, compare=False
137137
)
@@ -145,7 +145,9 @@ def is_configured(cls, bootstrap_config: "OpenTelemetryConfig") -> bool:
145145

146146
@staticmethod
147147
def check_dependencies() -> bool:
148-
return import_checker.is_opentelemetry_installed
148+
# The instrument imports from both the api (opentelemetry.trace/.context) and
149+
# the sdk (opentelemetry.sdk.*), so it needs both distributions present.
150+
return import_checker.is_opentelemetry_installed and import_checker.is_opentelemetry_sdk_installed
149151

150152
def _build_excluded_urls(self) -> set[str]:
151153
excluded_urls: set[str] = set(self.bootstrap_config.opentelemetry_excluded_urls)
@@ -181,17 +183,23 @@ def bootstrap(self) -> None:
181183
tracer_provider.add_span_processor(PyroscopeSpanProcessor())
182184
if self.bootstrap_config.opentelemetry_log_traces:
183185
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter(formatter=_format_span)))
184-
if (
185-
self.bootstrap_config.opentelemetry_endpoint and import_checker.is_otlp_grpc_exporter_installed
186-
): # pragma: no cover
187-
tracer_provider.add_span_processor(
188-
BatchSpanProcessor(
189-
OTLPSpanExporter(
190-
endpoint=self.bootstrap_config.opentelemetry_endpoint,
191-
insecure=self.bootstrap_config.opentelemetry_insecure,
186+
if self.bootstrap_config.opentelemetry_endpoint:
187+
if import_checker.is_otlp_grpc_exporter_installed:
188+
tracer_provider.add_span_processor( # pragma: no cover
189+
BatchSpanProcessor(
190+
OTLPSpanExporter(
191+
endpoint=self.bootstrap_config.opentelemetry_endpoint,
192+
insecure=self.bootstrap_config.opentelemetry_insecure,
193+
),
192194
),
193-
),
194-
)
195+
)
196+
else:
197+
warnings.warn(
198+
"opentelemetry_endpoint is set but the gRPC OTLP exporter is not installed; "
199+
"spans will not be exported. Install lite-bootstrap[otl].",
200+
category=InstrumentDependencyMissingWarning,
201+
stacklevel=2,
202+
)
195203
for one_instrumentor in self.bootstrap_config.opentelemetry_instrumentors:
196204
if isinstance(one_instrumentor, InstrumentorWithParams):
197205
one_instrumentor.instrumentor.instrument(
Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
summary: Split the OTel presence check into api (`is_opentelemetry_installed`) and sdk (`is_opentelemetry_sdk_installed`) so `import lite_bootstrap` no longer crashes in an api-only environment (e.g. `lite-bootstrap[fastmcp]`); gate the OTel instrument's sdk imports + `check_dependencies` on sdk, and warn (instead of silently skipping) when an OTLP endpoint is set without the gRPC exporter installed.
3+
---
4+
5+
# Design: Fix the opentelemetry api/sdk/exporter conflation
6+
7+
## Summary
8+
9+
`is_opentelemetry_installed = find_spec("opentelemetry")` is `True` with only
10+
`opentelemetry-api` installed, but three sites in `OpenTelemetryInstrument`
11+
import or require `opentelemetry.sdk.*`. Any environment with the api package but
12+
not the sdk — notably `lite-bootstrap[fastmcp]`, whose deps pull bare
13+
`opentelemetry-api` — crashes on `import lite_bootstrap`. Introduce a
14+
correctly-scoped `is_opentelemetry_sdk_installed` flag, gate the three sdk sites
15+
on it, and (a related consistency fix) warn instead of silently skipping when an
16+
OTLP endpoint is configured but the gRPC exporter package is absent.
17+
18+
## Motivation
19+
20+
Reproduced on regular (GIL) CPython 3.12, `uv pip install "lite-bootstrap[fastmcp]"`:
21+
22+
```
23+
File ".../instruments/opentelemetry_instrument.py", line 18, in <module>
24+
from opentelemetry.sdk import resources
25+
ModuleNotFoundError: No module named 'opentelemetry.sdk'
26+
```
27+
28+
`opentelemetry` (api) and `opentelemetry.trace`/`.metrics` are present;
29+
`opentelemetry.sdk` is absent. `lite-bootstrap[fastmcp]` without `otl` has never
30+
been importable — not ft-specific. (This is the third of three
31+
incomplete-opentelemetry-stack bugs; the api-namespace crash and the unconditional
32+
gRPC-exporter import were fixed in `2026-07-18.01`. It was deferred there and is
33+
now picked up.)
34+
35+
## Design
36+
37+
### 1. Two presence flags, precisely scoped
38+
39+
`import_checker.py`: add
40+
41+
```python
42+
is_opentelemetry_sdk_installed = _safe_find_spec("opentelemetry.sdk")
43+
```
44+
45+
Keep `is_opentelemetry_installed` (api) for the **six api-only consumers** whose
46+
guarded blocks import only `opentelemetry.trace`/`.metrics` (all provided by
47+
`opentelemetry-api`): `logging_instrument.py:30`, `fastapi_bootstrapper.py:30`,
48+
`litestar_bootstrapper.py:46`, `faststream_bootstrapper.py:27,102`, and the
49+
`is_{fastapi,litestar}_opentelemetry_installed` derivations.
50+
51+
`opentelemetry_instrument.py`: switch the **three sdk sites** to the new flag:
52+
53+
- the module-level import block (`opentelemetry.sdk.resources`,
54+
`opentelemetry.sdk.trace.*`) — the crash site;
55+
- the `PyroscopeSpanProcessor(SpanProcessor)` block (`SpanProcessor` is sdk);
56+
- `check_dependencies()` → `return import_checker.is_opentelemetry_sdk_installed`.
57+
58+
Rejected: redefining `is_opentelemetry_installed` to mean sdk — it would break the
59+
six api-only features whenever api is present without sdk (log trace-injection,
60+
faststream health-check spans, framework `get_tracer_provider`). Those genuinely
61+
need only the api.
62+
63+
### 2. `check_dependencies` now reflects sdk
64+
65+
Because the instrument requires the sdk, `check_dependencies()` returning sdk
66+
presence means the standard construction flow (`is_configured` →
67+
`check_dependencies` → warn+skip) fires the existing
68+
`InstrumentDependencyMissingWarning` when OTel is configured but only the api is
69+
present — a warning, not a crash.
70+
71+
### 3. Warn on a configured endpoint without the gRPC exporter
72+
73+
`bootstrap()` currently silently no-ops the OTLP exporter when
74+
`opentelemetry_endpoint` is set but `is_otlp_grpc_exporter_installed` is `False`.
75+
Replace the silent skip with a warning:
76+
77+
```python
78+
if self.bootstrap_config.opentelemetry_endpoint:
79+
if import_checker.is_otlp_grpc_exporter_installed:
80+
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(...))) # pragma: no cover
81+
else:
82+
warnings.warn(
83+
"opentelemetry_endpoint is set but the gRPC OTLP exporter is not installed; "
84+
"spans will not be exported. Install lite-bootstrap[otl].",
85+
category=InstrumentDependencyMissingWarning,
86+
stacklevel=2,
87+
)
88+
```
89+
90+
## Non-goals
91+
92+
- **A config-aware `check_dependencies(config)`.** The endpoint→exporter
93+
relationship is config-dependent, so the warning lives in `bootstrap()` rather
94+
than reworking the base `check_dependencies()` staticmethod contract.
95+
- **Re-adding `fastmcp` to the ft CI leg.** Now unblocked on 3.14t, but a separate
96+
CI-scope decision (`cffi` still blocks 3.13t). Tracked in `deferred.md`.
97+
98+
## Testing
99+
100+
- **Regression (crash):** with `opentelemetry.sdk` emulated absent
101+
(`emulate_package_missing` + module reload, as in `2026-07-18.01`'s tests),
102+
`is_opentelemetry_sdk_installed is False`, the instrument module reimports
103+
cleanly, and `check_dependencies()` is `False`. Fails on current code
104+
(`ModuleNotFoundError`), green after.
105+
- **Warn branch:** endpoint configured + `is_otlp_grpc_exporter_installed`
106+
monkeypatched `False` → `bootstrap()` emits `InstrumentDependencyMissingWarning`
107+
(removes the previously-untested silent skip; the true exporter branch keeps its
108+
live-collector `# pragma: no cover`).
109+
- `just test` 100% coverage; `just lint-ci` clean.
110+
111+
## Risk
112+
113+
- **Behaviour change for a partial-otel install (low × low).** Configuring OTel
114+
with only the api, or an endpoint without the exporter, now warns instead of
115+
crashing/silently-skipping — strictly better, and pinned by the two tests.

‎planning/deferred.md‎

Lines changed: 13 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -42,57 +42,19 @@ verification commands, for two separate, independent reasons — one per leg:
4242
build-environment problem, the same shape as msgspec's 3.13t gate below.
4343
Reproduced 2026-07-18: `uv pip install --python <3.13t venv> ".[fastmcp]"`
4444
fails building `cffi`.
45-
- **3.14t (import-time, partially fixed, one blocker remains):** `fastmcp`
46-
transitively pulls bare `opentelemetry-api` with no other `opentelemetry-*`
47-
package (independent of lite-bootstrap's own `otl` extra, which bundles
48-
api+sdk+exporter+instrumentation together and is excluded from ft for the
49-
unrelated grpcio reason above). Two import-safety bugs this exposed are now
50-
fixed: `import_checker.py`'s dotted `find_spec` calls previously raised
51-
`ModuleNotFoundError` instead of returning `False` when a parent namespace
52-
was incomplete, and `opentelemetry_instrument.py` previously imported the
53-
grpc otlp exporter unconditionally whenever bare `opentelemetry-api` was
54-
present. A third, deeper issue remains, found while verifying the above:
55-
`opentelemetry_instrument.py` also imports several `opentelemetry.sdk.*`
56-
names under the same `is_opentelemetry_installed` guard, and
57-
`check_dependencies()` uses that same flag — but `opentelemetry-sdk` is a
58-
separate PyPI distribution that `fastmcp` does not pull in, so `uv pip
59-
install ".[fastmcp]"` followed by `import lite_bootstrap` still raises
60-
`ModuleNotFoundError: No module named 'opentelemetry.sdk'` (reproduced
61-
2026-07-18 on 3.14t). See "OTel-stack dependency model" below for the fix
62-
shape and a second, independent symptom of the same root cause.
63-
64-
**Trigger:** `cffi` ships free-threaded 3.13 wheels (unblocks 3.13t), or fastmcp
65-
support on the 3.14t leg is wanted (needs the `opentelemetry-sdk`-vs-api
66-
activation fix below first).
67-
68-
### OTel-stack dependency model (api vs sdk vs exporter granularity)
69-
70-
`is_opentelemetry_installed` is one `find_spec("opentelemetry")` check, but
71-
`opentelemetry-api`, `opentelemetry-sdk`, and the OTLP exporter packages are
72-
three independent PyPI distributions — a real environment can have any subset
73-
installed. `check_dependencies()`/activation only sees that one coarse flag,
74-
which produces two distinct symptoms:
75-
76-
- **Import-time:** `opentelemetry_instrument.py` imports several
77-
`opentelemetry.sdk.*` names under the same `is_opentelemetry_installed`
78-
guard used for the now-fixed exporter-import bug (see the fastmcp entry
79-
above), so `import lite_bootstrap` still crashes with `ModuleNotFoundError:
80-
No module named 'opentelemetry.sdk'` whenever `opentelemetry-api` is present
81-
without `opentelemetry-sdk` — the case for `lite-bootstrap[fastmcp]`.
82-
- **Activation-time:** `check_dependencies()` gates OpenTelemetry activation on
83-
`is_opentelemetry_installed` alone, so an environment with `opentelemetry-api`
84-
present but the OTLP exporter package absent passes `check_dependencies()`
85-
cleanly, and `bootstrap()`'s `opentelemetry_endpoint`-gated span-processor
86-
block silently no-ops once `is_otlp_grpc_exporter_installed` is False —
87-
skipping OTLP export without the `InstrumentDependencyMissingWarning` a
88-
configured-but-missing dependency normally gets elsewhere. See
89-
`architecture/instruments.md`'s "Optional-dependency guard" section.
90-
91-
Proper fix: an exporter/sdk-aware `check_dependencies()` (and matching
92-
warning) that distinguishes api/sdk/exporter presence instead of one bool —
93-
an activation-semantics change, not just another import guard.
94-
**Trigger:** `[fastmcp]`-without-`otl` support is wanted (needs this first), or
95-
a user reports the silent OTLP-export skip.
45+
- **3.14t (now importable):** `fastmcp` transitively pulls bare
46+
`opentelemetry-api` with no other `opentelemetry-*` package. The three
47+
incomplete-opentelemetry-stack bugs this exposed are all fixed — the
48+
`import_checker` namespace crash and the unconditional grpc-exporter import in
49+
`changes/2026-07-18.01`, and the api-vs-sdk conflation
50+
(`opentelemetry_instrument.py` importing `opentelemetry.sdk.*` and
51+
`check_dependencies()` under the api-only flag) in `changes/2026-07-19.01`. So
52+
`uv pip install ".[fastmcp]"` + `import lite_bootstrap` now succeeds on 3.14t;
53+
it is simply not yet wired into the 3.14t leg's extras.
54+
55+
**Trigger:** `cffi` ships free-threaded 3.13 wheels (unblocks 3.13t), **or** add
56+
`fastmcp`/`fastmcp-metrics` to the 3.14t leg's extras in `_checks.yml` (import
57+
now works there).
9658

9759
### litestar on free-threaded Python 3.13 (msgspec gates Py_GIL_DISABLED to 3.14+)
9860

‎tests/instruments/test_opentelemetry_instrument.py‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
99

1010
from lite_bootstrap import import_checker
11-
from lite_bootstrap.exceptions import TeardownError
11+
from lite_bootstrap.exceptions import InstrumentDependencyMissingWarning, TeardownError
1212
from lite_bootstrap.instruments.opentelemetry_instrument import (
1313
InstrumentorWithParams,
1414
OpenTelemetryConfig,
@@ -213,3 +213,29 @@ def test_opentelemetry_instrument_survives_missing_grpc_exporter() -> None:
213213
assert import_checker.is_otlp_grpc_exporter_installed is False
214214
finally:
215215
sys.modules.update(saved_submodules)
216+
217+
218+
def test_opentelemetry_instrument_survives_missing_sdk() -> None:
219+
# opentelemetry-api present but opentelemetry-sdk absent (e.g. lite-bootstrap[fastmcp],
220+
# which pulls bare opentelemetry-api transitively) must not crash importing
221+
# opentelemetry_instrument, whose guarded block imports opentelemetry.sdk.* symbols.
222+
with emulate_package_missing_with_module_reload(
223+
"opentelemetry.sdk",
224+
["lite_bootstrap.instruments.opentelemetry_instrument"],
225+
):
226+
assert import_checker.is_opentelemetry_sdk_installed is False
227+
assert OpenTelemetryInstrument.check_dependencies() is False
228+
229+
230+
def test_bootstrap_warns_when_endpoint_set_without_grpc_exporter() -> None:
231+
# SDK present but the grpc exporter absent, with an endpoint configured: bootstrap()
232+
# must warn (configured-but-missing) rather than silently skip OTLP export.
233+
instrument = OpenTelemetryInstrument(bootstrap_config=OpenTelemetryConfig(opentelemetry_endpoint="localhost:4317"))
234+
try:
235+
with (
236+
patch.object(import_checker, "is_otlp_grpc_exporter_installed", False),
237+
pytest.warns(InstrumentDependencyMissingWarning, match="gRPC OTLP exporter"),
238+
):
239+
instrument.bootstrap()
240+
finally:
241+
instrument.teardown()

0 commit comments

Comments
 (0)