wellapi 0.10.1__tar.gz → 0.10.2__tar.gz

{wellapi-0.10.1 → wellapi-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wellapi
-Version: 0.10.1
+Version: 0.10.2
 Summary: A simple web framework for aws lambda
 Author-email: romayuhym <romayuhym@gmail.com>
 Requires-Python: >=3.12

{wellapi-0.10.1 → wellapi-0.10.2}/docs/telemetry.md

@@ -74,17 +74,6 @@ SERVER  GET /orders/{id}
 Call `use_telemetry()` before `instrument()`. (Reverse order also works — OTel's
 `ProxyTracer` resolves to the global provider at span-creation time.)
 
-## Trace context propagation
-
-Every invocation starts its **own** trace. The inbound W3C trace context — the
-`traceparent` header on API Gateway requests, or the `traceparent` SQS message
-attribute — is attached to the root span as a **span link**, not used as its
-parent. This is deliberate: a sticky or shared upstream `traceparent` (e.g. a
-client that reuses one trace across many calls, or a producer that fans out many
-messages within a single trace) would otherwise collapse unrelated invocations
-into a single `trace_id`. Linking instead of parenting keeps each invocation a
-distinct trace while preserving the correlation back to the caller.
-
 ## Logs
 
 wellapi configures and flushes a `LoggerProvider` but does not attach handlers —
@@ -118,6 +107,36 @@ to the function name).
 `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` override these without code
 changes.
 
+## SnapStart and ID uniqueness
+
+When `warmup`/`use_snap_start` is on, the function is published with AWS Lambda
+SnapStart: Lambda boots one environment, snapshots its memory, and restores that
+**same** snapshot into every execution environment. Anything seeded once at init
+is therefore shared by all restored environments.
+
+OpenTelemetry's default ID generator draws trace/span IDs from Python's
+module-level `random` (a Mersenne Twister seeded once at import). Under SnapStart
+that frozen state is cloned, so every restored environment emits the **same
+sequence** of trace/span IDs — you see one `trace_id` reused across unrelated
+requests. wellapi avoids this by configuring the tracer provider with a
+`SystemRandom` (`os.urandom`-backed) ID generator: the kernel CSPRNG is reseeded
+with fresh entropy on restore, so IDs stay unique. No action needed for telemetry.
+
+If your own handlers (or other libraries) rely on the `random` module, `uuid1`,
+or any non-CSPRNG source for uniqueness, they have the same SnapStart hazard.
+Reseed them in an after-restore hook:
+
+```python
+import random
+from snapshot_restore_py import register_after_restore
+
+@register_after_restore
+def _reseed():
+    random.seed()  # pull fresh entropy from the OS after restore
+```
+
+`os.urandom`, `secrets`, and `uuid4` read the kernel CSPRNG and are already safe.
+
 ## Local development
 
 Telemetry is off until `use_telemetry()` is called. If you call it locally without

{wellapi-0.10.1 → wellapi-0.10.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wellapi"
-version = "0.10.1"
+version = "0.10.2"
 description = "A simple web framework for aws lambda"
 readme = "README.md"
 authors = [

{wellapi-0.10.1 → wellapi-0.10.2}/src/wellapi/telemetry/config.py

@@ -1,4 +1,5 @@
 import os
+import random
 from dataclasses import dataclass
 from typing import Any
 
@@ -13,6 +14,37 @@ _INSTALL_HINT = (
 )
 
 
+class _SystemRandomIdGenerator:
+    """Trace/span ID generator backed by the kernel CSPRNG (`os.urandom`).
+
+    OpenTelemetry's default `RandomIdGenerator` draws IDs from the module-level
+    Mersenne Twister, which Python seeds once at import. AWS Lambda SnapStart
+    captures that PRNG state in the snapshot and shares it across every restored
+    execution environment, so the default generator emits identical trace/span
+    IDs in lockstep across environments — observed as duplicate `trace_id`s on
+    unrelated requests. The kernel CSPRNG is reseeded with fresh entropy on
+    restore, so `random.SystemRandom` (i.e. `os.urandom`) stays unique. Duck-typed
+    against `opentelemetry.sdk.trace.id_generator.IdGenerator` to avoid importing
+    the SDK at module import time (kept lazy, like the rest of this module)."""
+
+    _rand = random.SystemRandom()
+
+    def generate_span_id(self) -> int:
+        span_id = self._rand.getrandbits(64)
+        while span_id == trace.INVALID_SPAN_ID:
+            span_id = self._rand.getrandbits(64)
+        return span_id
+
+    def generate_trace_id(self) -> int:
+        trace_id = self._rand.getrandbits(128)
+        while trace_id == trace.INVALID_TRACE_ID:
+            trace_id = self._rand.getrandbits(128)
+        return trace_id
+
+    def is_trace_id_random(self) -> bool:
+        return True
+
+
 @dataclass
 class TelemetryHandle:
     """Handles to the configured providers. Returned by `app.use_telemetry()` so
@@ -73,7 +105,10 @@ def _build_providers(resource: Any) -> tuple[Any, Any, Any]:
 
     # Exporters default to OTEL_EXPORTER_OTLP_ENDPOINT or http://localhost:4318,
     # i.e. the collector-only Lambda layer running on localhost.
-    tracer_provider = TracerProvider(resource=resource)
+    # _SystemRandomIdGenerator keeps IDs unique under SnapStart (see its docstring).
+    tracer_provider = TracerProvider(
+        resource=resource, id_generator=_SystemRandomIdGenerator()
+    )
     tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
 
     meter_provider = MeterProvider(

{wellapi-0.10.1 → wellapi-0.10.2}/src/wellapi/telemetry/middleware.py

@@ -4,8 +4,7 @@ import typing
 
 try:
     from opentelemetry import propagate
-    from opentelemetry.context import Context
-    from opentelemetry.trace import Link, Span, SpanKind, get_current_span
+    from opentelemetry.trace import Span, SpanKind
     from opentelemetry.trace.status import Status, StatusCode
 except ImportError as err:  # pragma: no cover
     raise RuntimeError(
@@ -68,14 +67,7 @@ class TelemetryMiddleware:
         start = time.perf_counter()
 
         attribute = get_request_attribute(request)
-        # Each invocation starts its OWN trace (root span). The inbound trace
-        # context is attached as a link, not used as the parent: a sticky or
-        # shared upstream traceparent would otherwise collapse unrelated
-        # invocations into a single trace_id (warm-container fan-in).
-        upstream = get_current_span(
-            propagate.extract(get_trace_carrier(request))
-        ).get_span_context()
-        links = [Link(upstream)] if upstream.is_valid else None
+        parent = propagate.extract(get_trace_carrier(request))
         span_attributes = {
             **attribute.attributes,
             **get_code_attribute(),
@@ -86,10 +78,9 @@ class TelemetryMiddleware:
         response: ResponseAPIGateway | None = None
         with self.tracer.start_as_current_span(
             attribute.span_name,
-            context=Context(),
+            context=parent,
             kind=_SPAN_KIND.get(attribute.kind, SpanKind.SERVER),
             attributes=span_attributes,
-            links=links,
         ) as span:
             if self.request_hook:
                 self.request_hook(span, request)

{wellapi-0.10.1 → wellapi-0.10.2}/tests/conftest.py

@@ -83,24 +83,11 @@ def job_event():
     }
 
 
-@pytest.fixture
-def api_gateway_event_no_trace(api_gateway_event):
-    event = dict(api_gateway_event)
-    event["headers"] = {"Host": "api.example.com"}
-    event["multiValueHeaders"] = {"Host": ["api.example.com"]}
-    return event
-
-
 @pytest.fixture
 def api_gateway_request(api_gateway_event):
     return RequestAPIGateway.create_request_from_event(api_gateway_event)
 
 
-@pytest.fixture
-def api_gateway_request_no_trace(api_gateway_event_no_trace):
-    return RequestAPIGateway.create_request_from_event(api_gateway_event_no_trace)
-
-
 @pytest.fixture
 def sqs_request(sqs_event):
     return RequestSQS.create_request_from_event(sqs_event)

{wellapi-0.10.1 → wellapi-0.10.2}/tests/telemetry/test_config.py

@@ -1,3 +1,5 @@
+import random
+
 import wellapi.telemetry.config as config_mod
 from wellapi.telemetry.config import TelemetryHandle, _build_resource
 
@@ -6,6 +8,40 @@ def _attrs(resource):
     return dict(resource.attributes)
 
 
+def _ids_after_seed(generator, seed):
+    """IDs a freshly snapshot-restored env would emit: identical frozen
+    module-level random state (the AWS SnapStart failure mode)."""
+    state = random.getstate()
+    try:
+        random.seed(seed)
+        return generator.generate_trace_id(), generator.generate_span_id()
+    finally:
+        random.setstate(state)
+
+
+def test_default_random_id_generator_collides_under_cloned_random_state():
+    # Documents the bug: the OTel default generator draws from the module-level
+    # Mersenne Twister, which SnapStart freezes and shares across restored envs.
+    from opentelemetry.sdk.trace.id_generator import RandomIdGenerator
+
+    gen = RandomIdGenerator()
+    assert _ids_after_seed(gen, 1234) == _ids_after_seed(gen, 1234)
+
+
+def test_snapstart_safe_id_generator_survives_cloned_random_state():
+    gen = config_mod._SystemRandomIdGenerator()
+    # Two envs restored from the same snapshot (same frozen MT state) must still
+    # produce distinct trace/span IDs.
+    assert _ids_after_seed(gen, 1234) != _ids_after_seed(gen, 1234)
+
+
+def test_snapstart_safe_id_generator_marks_trace_id_random():
+    gen = config_mod._SystemRandomIdGenerator()
+    assert gen.is_trace_id_random() is True
+    assert 0 < gen.generate_trace_id() < 2**128
+    assert 0 < gen.generate_span_id() < 2**64
+
+
 def test_resource_uses_faas_env(monkeypatch):
     monkeypatch.setenv("AWS_LAMBDA_FUNCTION_NAME", "orders-fn")
     monkeypatch.setenv("AWS_REGION", "eu-west-1")
@@ -53,6 +89,9 @@ def test_build_providers_attaches_resource_and_returns_sdk_types():
     assert isinstance(mp, MeterProvider)
     assert isinstance(lp, LoggerProvider)
     assert dict(tp.resource.attributes)["service.name"] == "t"
+    # SnapStart-safe IDs: the tracer provider must not use the default MT-backed
+    # generator, otherwise restored envs emit duplicate trace/span IDs.
+    assert isinstance(tp.id_generator, config_mod._SystemRandomIdGenerator)
 
 
 def test_configure_reuses_existing_sdk_provider(monkeypatch):

{wellapi-0.10.1 → wellapi-0.10.2}/tests/telemetry/test_middleware.py

@@ -63,7 +63,7 @@ def test_span_is_active_in_context(telemetry, api_gateway_request, monkeypatch):
     assert captured["ctx"].span_id == span.context.span_id
 
 
-def test_inbound_traceparent_becomes_link_not_parent(
+def test_parent_context_extracted_from_traceparent(
     telemetry, api_gateway_request, monkeypatch
 ):
     handle, exporter, _ = telemetry
@@ -72,40 +72,8 @@ def test_inbound_traceparent_becomes_link_not_parent(
         api_gateway_request
     )
     (span,) = exporter.get_finished_spans()
-    # The span starts its own trace instead of inheriting a (possibly sticky)
-    # upstream traceparent that would collapse unrelated requests into one trace.
-    assert span.context.trace_id != TRACE_ID
-    assert span.parent is None
-    # The upstream context is preserved as a link for cross-trace correlation.
-    (link,) = span.links
-    assert link.context.trace_id == TRACE_ID
-    assert link.context.span_id == PARENT_SPAN_ID
-
-
-def test_two_invocations_with_same_traceparent_get_distinct_traces(
-    telemetry, api_gateway_request, monkeypatch
-):
-    handle, exporter, _ = telemetry
-    monkeypatch.setattr(mw_mod, "force_flush", lambda *a, **k: None)
-    mw = TelemetryMiddleware(lambda req: ResponseAPIGateway(status_code=200), handle)
-    mw(api_gateway_request)
-    mw(api_gateway_request)
-    trace_ids = {s.context.trace_id for s in exporter.get_finished_spans()}
-    assert len(trace_ids) == 2
-    assert TRACE_ID not in trace_ids
-
-
-def test_no_inbound_traceparent_starts_root_without_link(
-    telemetry, api_gateway_request_no_trace, monkeypatch
-):
-    handle, exporter, _ = telemetry
-    monkeypatch.setattr(mw_mod, "force_flush", lambda *a, **k: None)
-    TelemetryMiddleware(lambda req: ResponseAPIGateway(status_code=200), handle)(
-        api_gateway_request_no_trace
-    )
-    (span,) = exporter.get_finished_spans()
-    assert span.parent is None
-    assert span.links == ()
+    assert span.context.trace_id == TRACE_ID
+    assert span.parent.span_id == PARENT_SPAN_ID
 
 
 def test_exception_sets_error_status_and_reraises(

{wellapi-0.10.1 → wellapi-0.10.2}/uv.lock

@@ -672,7 +672,7 @@ wheels = [
 
 [[package]]
 name = "wellapi"
-version = "0.10.1"
+version = "0.10.2"
 source = { editable = "." }
 dependencies = [
     { name = "email-validator" },