|
| 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. |
0 commit comments