From b764c97558312d68d49340c37bc16a91439ec433 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Wed, 18 Nov 2026 12:43:23 +0300 Subject: [PATCH] docs: clarify OpenTelemetry recovery after failed startup (#457) --- docs/introduction/configuration.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/introduction/configuration.md b/docs/introduction/configuration.md index 6a4797c..e27d1e1 100644 --- a/docs/introduction/configuration.md +++ b/docs/introduction/configuration.md @@ -275,6 +275,25 @@ bootstrap. For metrics-only requests without external tracing, spans do not reco and JSON logs omit `tracing`; there are no `span_id` or `trace_id` values to inject. Metrics collection is unchanged. +### Startup failure and recovery + +A failed `bootstrap()` cleans up started instruments and cannot be retried on the +same bootstrapper. Cleanup does not undo every change to the application. + +If startup fails after lite-bootstrap installs a global `TracerProvider` or +`MeterProvider`, restart the process before bootstrapping again. OpenTelemetry +allows each global provider to be set only once. Rollback shuts down the owned +provider but leaves it globally registered; a replacement bootstrapper cannot +replace it, so its configured exporters will not be used. For example, a custom +`opentelemetry_instrumentors` entry that raises during setup can leave tracing in +this state. + +A failure before provider registration does not itself require a restart for +OpenTelemetry. Local no-op tracing leaves the global tracer slot untouched; +an existing external tracer provider is preserved. Any +retry still needs a new bootstrapper and, where applicable, a new application. +The same global-provider limitation applies after normal teardown. + ### Metrics Left unset, no `MeterProvider` is installed and the metrics signal stays off. Set it, and the