modmex-lambda 0.4.1__tar.gz → 0.5.0__tar.gz

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modmex-lambda
-Version: 0.4.1
+Version: 0.5.0
 Summary: Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling.
 Author: Modmex
 License: MIT
@@ -607,6 +607,75 @@ The logger emits structured JSON, reads `LOG_LEVEL`, uses `SERVICE_NAME` or
 `AWS_LAMBDA_FUNCTION_NAME` when no service is passed, and can extract Lambda
 request IDs and API Gateway correlation IDs.
 
+## Tracing
+
+Tracing is optional and lazy. The core package does not require
+`opentelemetry-api`, does not initialize an SDK/exporter, and does not import
+OpenTelemetry during `import modmex_lambda`.
+
+`Tracer` uses OpenTelemetry when an OpenTelemetry runtime is available. For
+Lambda, the recommended runtime is the AWS Distro for OpenTelemetry (ADOT)
+Lambda layer.
+
+The example below uses Serverless Framework. If you use another IaC tool, the
+same pieces are required: enable Lambda tracing, attach the ADOT Python layer
+for the AWS region where the function runs, and configure the OpenTelemetry
+environment variables.
+
+```yaml
+provider:
+  name: aws
+  runtime: python3.12
+  region: mx-central-1
+  tracing:
+    lambda: true
+
+functions:
+  api:
+    handler: app.lambda_handler
+    layers:
+      - arn:aws:lambda:mx-central-1:610118373846:layer:AWSOpenTelemetryDistroPython:13
+    environment:
+      AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
+      OTEL_SERVICE_NAME: ${self:service}
+```
+
+Do not bundle `opentelemetry-*` packages in your function when using the ADOT
+layer. The layer provides the OpenTelemetry runtime; bundling a different
+version can conflict with the layer. Public ADOT layer ARNs are regional, so
+use the ARN that matches your configured AWS region.
+
+```python
+from modmex_lambda import Tracer
+
+tracer = Tracer(service="orders")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return handle(event)
+
+
+@tracer.capture_method(name="handle_order")
+def handle(event):
+    tracer.set_attribute("tenant_id", event.get("tenant_id"))
+    return {"ok": True}
+```
+
+If OpenTelemetry is not installed or configured, the tracer is a no-op. Use an
+external OpenTelemetry setup, such as an ADOT Lambda layer or your own SDK
+configuration, when spans should be exported.
+
+When decorating route handlers, put the route decorator above
+`capture_method`, so the router registers the traced function:
+
+```python
+@app.post("/todos")
+@tracer.capture_method(name="create_todo")
+def create_todo(todo: Annotated[Todo, Body()]) -> dict:
+    return todo.model_dump()
+```
+
 
 ## Stream Handlers
 

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/README.md

@@ -584,6 +584,75 @@ The logger emits structured JSON, reads `LOG_LEVEL`, uses `SERVICE_NAME` or
 `AWS_LAMBDA_FUNCTION_NAME` when no service is passed, and can extract Lambda
 request IDs and API Gateway correlation IDs.
 
+## Tracing
+
+Tracing is optional and lazy. The core package does not require
+`opentelemetry-api`, does not initialize an SDK/exporter, and does not import
+OpenTelemetry during `import modmex_lambda`.
+
+`Tracer` uses OpenTelemetry when an OpenTelemetry runtime is available. For
+Lambda, the recommended runtime is the AWS Distro for OpenTelemetry (ADOT)
+Lambda layer.
+
+The example below uses Serverless Framework. If you use another IaC tool, the
+same pieces are required: enable Lambda tracing, attach the ADOT Python layer
+for the AWS region where the function runs, and configure the OpenTelemetry
+environment variables.
+
+```yaml
+provider:
+  name: aws
+  runtime: python3.12
+  region: mx-central-1
+  tracing:
+    lambda: true
+
+functions:
+  api:
+    handler: app.lambda_handler
+    layers:
+      - arn:aws:lambda:mx-central-1:610118373846:layer:AWSOpenTelemetryDistroPython:13
+    environment:
+      AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
+      OTEL_SERVICE_NAME: ${self:service}
+```
+
+Do not bundle `opentelemetry-*` packages in your function when using the ADOT
+layer. The layer provides the OpenTelemetry runtime; bundling a different
+version can conflict with the layer. Public ADOT layer ARNs are regional, so
+use the ARN that matches your configured AWS region.
+
+```python
+from modmex_lambda import Tracer
+
+tracer = Tracer(service="orders")
+
+
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+    return handle(event)
+
+
+@tracer.capture_method(name="handle_order")
+def handle(event):
+    tracer.set_attribute("tenant_id", event.get("tenant_id"))
+    return {"ok": True}
+```
+
+If OpenTelemetry is not installed or configured, the tracer is a no-op. Use an
+external OpenTelemetry setup, such as an ADOT Lambda layer or your own SDK
+configuration, when spans should be exported.
+
+When decorating route handlers, put the route decorator above
+`capture_method`, so the router registers the traced function:
+
+```python
+@app.post("/todos")
+@tracer.capture_method(name="create_todo")
+def create_todo(todo: Annotated[Todo, Body()]) -> dict:
+    return todo.model_dump()
+```
+
 
 ## Stream Handlers
 

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/modmex_lambda/__init__.py

@@ -16,6 +16,7 @@ __all__ = [
     "create_dependency_resolver",
     "default_dependency_resolver",
     "Logger",
+    "Tracer",
     "ModmexValidator",
     "ValidationError",
 ]
@@ -38,6 +39,7 @@ def __getattr__(name):
         "create_dependency_resolver": ("modmex_lambda.dependencies", "create_dependency_resolver"),
         "default_dependency_resolver": ("modmex_lambda.dependencies", "default_dependency_resolver"),
         "Logger": ("modmex_lambda.logging", "Logger"),
+        "Tracer": ("modmex_lambda.tracing", "Tracer"),
         "ModmexValidator": ("modmex_lambda.validation", "ModmexValidator"),
         "ValidationError": ("modmex_lambda.validation", "ValidationError"),
     }.get(name)

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/modmex_lambda/logging.py

@@ -7,8 +7,11 @@ import os
 import sys
 import traceback
 from datetime import datetime, timezone
+from threading import RLock
 from typing import Any, Callable, TextIO
 
+from modmex_lambda.shared.json_encoder import JSONEncoder
+
 
 _LEVELS = {
     "DEBUG": 10,
@@ -19,6 +22,17 @@ _LEVELS = {
 }
 
 
+class _LoggerJSONEncoder(JSONEncoder):
+    def default(self, obj: object) -> object:
+        if hasattr(obj, "model_dump"):
+            value = obj.model_dump()
+            try:
+                return json.loads(value)
+            except (TypeError, ValueError):
+                return value
+        return super().default(obj)
+
+
 class Logger:
     def __init__(
         self,
@@ -31,28 +45,36 @@ class Logger:
     ) -> None:
         self._service = service or os.getenv("SERVICE_NAME") or os.getenv("AWS_LAMBDA_FUNCTION_NAME") or "service"
         self._stream = stream or sys.stdout
-        self._serialize = json_serializer or (lambda payload: json.dumps(payload, separators=(",", ":"), default=str))
+        self._serialize = json_serializer or self._serialize_payload
         self._correlation_id_header = correlation_id_header.lower()
         self._level = self._resolve_level(level)
         self._persistent_keys: dict[str, Any] = {}
         self._context: object | None = None
         self._event: dict[str, Any] | None = None
+        self._lock = RLock()
 
     def set_context(self, *, context: object | None = None, event: dict[str, Any] | None = None) -> None:
-        self._context = context
-        self._event = event
+        with self._lock:
+            self._context = context
+            self._event = event
 
     def append_keys(self, **kwargs: Any) -> None:
-        self._persistent_keys.update(kwargs)
+        with self._lock:
+            self._persistent_keys.update(kwargs)
 
     def clear_state(self) -> None:
-        self._persistent_keys.clear()
+        with self._lock:
+            self._persistent_keys.clear()
+            self._context = None
+            self._event = None
 
     def set_level(self, level: str | int) -> None:
-        self._level = self._resolve_level(level)
+        with self._lock:
+            self._level = self._resolve_level(level)
 
     def is_enabled_for(self, level: str | int) -> bool:
-        return self._resolve_level(level) >= self._level
+        with self._lock:
+            return self._resolve_level(level) >= self._level
 
     def debug(self, message: Any, *args: Any, **kwargs: Any) -> None:
         self._log("DEBUG", message, *args, **kwargs)
@@ -70,31 +92,32 @@ class Logger:
         self._log("CRITICAL", message, *args, exc_info=exc_info, **kwargs)
 
     def _log(self, level: str, message: Any, *args: Any, exc_info: bool = False, **kwargs: Any) -> None:
-        if not self.is_enabled_for(level):
-            return
+        with self._lock:
+            if not self.is_enabled_for(level):
+                return
 
-        record: dict[str, Any] = {
-            "timestamp": datetime.now(timezone.utc).isoformat(),
-            "level": level,
-            "service": self._service,
-            "message": self._format_message(message, args),
-        }
-        record.update(self._persistent_keys)
+            record: dict[str, Any] = {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "level": level,
+                "service": self._service,
+                "message": self._format_message(message, args),
+            }
+            record.update(self._persistent_keys)
 
-        request_id = self._extract_request_id()
-        if request_id:
-            record["request_id"] = request_id
+            request_id = self._extract_request_id()
+            if request_id:
+                record["request_id"] = request_id
 
-        correlation_id = self._extract_correlation_id()
-        if correlation_id and "correlation_id" not in record:
-            record["correlation_id"] = correlation_id
+            correlation_id = self._extract_correlation_id()
+            if correlation_id and "correlation_id" not in record:
+                record["correlation_id"] = correlation_id
 
-        record.update(kwargs)
+            record.update(kwargs)
 
-        if exc_info:
-            record["exception"] = traceback.format_exc()
+            if exc_info:
+                record["exception"] = traceback.format_exc()
 
-        self._stream.write(self._serialize(record) + "\n")
+            self._stream.write(self._serialize(record) + "\n")
 
     def _resolve_level(self, level: str | int | None) -> int:
         if isinstance(level, int):
@@ -102,6 +125,12 @@ class Logger:
         level_name = (level or os.getenv("LOG_LEVEL") or "INFO").upper()
         return _LEVELS.get(level_name, _LEVELS["INFO"])
 
+    def _serialize_payload(self, payload: dict[str, Any]) -> str:
+        try:
+            return json.dumps(payload, separators=(",", ":"), cls=_LoggerJSONEncoder)
+        except TypeError:
+            return json.dumps(payload, separators=(",", ":"), default=str)
+
     def _format_message(self, message: Any, args: tuple[Any, ...]) -> Any:
         if not args:
             return message

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/modmex_lambda/stream/flavors/base_flavor.py

@@ -11,10 +11,10 @@ from modmex_lambda.dependencies import (
     DependencyResolver,
     default_dependency_resolver,
 )
+from modmex_lambda.logging import Logger
 from modmex_lambda.stream.flavors.iflavor import IFlavor
 from modmex_lambda.stream.operators.publisher import Publisher, PublisherOptions
 from modmex_lambda.stream.utils.contracts import Event
-from modmex_lambda.stream.utils.opt import DEFAULT_OPTIONS
 
 
 if TYPE_CHECKING:
@@ -39,7 +39,7 @@ class BaseFlavor(Generic[TEvent], IFlavor):
         dependency_resolver: Optional[DependencyResolver] = None,
         publisher_options: Optional[PublisherOptions] = None,
     ) -> None:
-        self.logger = logger or DEFAULT_OPTIONS.get("logger")
+        self.logger = logger or Logger()
         self.connector = connector
         self.dependency_resolver = dependency_resolver
         self.publisher_options = publisher_options or {}
@@ -127,7 +127,7 @@ class BaseFlavor(Generic[TEvent], IFlavor):
             self._publisher = Publisher[TEvent](
                 connector=self.connector or self.resolve(IEventBridgeConnector),
                 logger=self.logger,
-                bus_name=options.get("bus_name") or DEFAULT_OPTIONS.get("bus_name"),
+                bus_name=options.get("bus_name"),
                 source=options.get("source"),
                 event_field=options.get("event_field"),
                 publish_request_entry_field=options.get("publish_request_entry_field"),

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/modmex_lambda/stream/operators/publisher.py

@@ -42,7 +42,7 @@ class Publisher(Generic[TEvent], IOperator[Uow[TEvent]]):
         logger: Optional[object] = None,
     ):
         self.connector = connector or Connector()
-        self.bus_name = bus_name or os.getenv('BUS_NAME')
+        self.bus_name = bus_name or os.getenv('BUS_NAME') or 'undefined'
         self.source = source or os.getenv('BUS_SRC') or 'custom'
         self.event_field = event_field or 'event'
         self.publish_request_entry_field = publish_request_entry_field or 'publish_request_entry'

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/modmex_lambda/stream/runner.py

@@ -1,29 +1,45 @@
 import copy
 import multiprocessing
+import os
 import threading
-from typing import Iterable, Optional
+from typing import Any, Callable, Iterable, TypedDict
 
 from reactivex import Observable, from_list, operators as ops
 from reactivex.scheduler import ThreadPoolScheduler
 
 from modmex_lambda.stream.irules_registry import IRulesRegistry
+from modmex_lambda.stream.utils.eventbridge import publish_to_event_bridge
 from modmex_lambda.stream.utils.faults import flush_faults
-from modmex_lambda.stream.utils.opt import DEFAULT_OPTIONS
 from modmex_lambda.logging import Logger
 from modmex_lambda.stream.utils.operators import tap
 
 
+PublishFactory = Callable[[dict[str, Any]], Any]
+BusName = str | Callable[[dict[str, Any]], str] | None
+
+
+class RunOptions(TypedDict, total=False):
+    bus_name: BusName
+    publish: PublishFactory
+    logger: Any
+
+
+def _publish_to_event_bridge(params: dict[str, Any]) -> Any:
+    return publish_to_event_bridge(**params)
+
+
 def run(
     events: Iterable,
     registry: IRulesRegistry,
-    opt: Optional[dict] = None,
+    opt: RunOptions | None = None,
     on_next=None,
     on_error=None,
     on_completed=None,
     concurrency=True,
 ):
     opt = {
-        **DEFAULT_OPTIONS,
+        'bus_name': os.getenv('BUS_NAME'),
+        'publish': _publish_to_event_bridge,
         **(opt or {}),
     }
     optimal_thread_count = multiprocessing.cpu_count()

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/modmex_lambda/stream/utils/eventbridge.py

@@ -1,4 +1,3 @@
-import os
 from modmex_lambda.logging import Logger
 from modmex_lambda.connectors.eventbridge import Connector
 from modmex_lambda.stream.operators.publisher import Publisher
@@ -6,12 +5,12 @@ from modmex_lambda.stream.operators.publisher import Publisher
 # pylint: disable=unused-argument,too-many-arguments
 def publish_to_event_bridge(
     logger=None,
-    bus_name=os.getenv('BUS_NAME') or 'undefined',
-    source=os.getenv('BUS_SRC') or 'custom',
-    event_field='event',
-    publish_request_entry_field='publish_request_entry',
-    publish_request_field='publish_request',
-    batch_size=os.getenv('PUBLISH_BATCH_SIZE') or os.getenv('BATCH_SIZE') or 10,
+    bus_name=None,
+    source=None,
+    event_field=None,
+    publish_request_entry_field=None,
+    publish_request_field=None,
+    batch_size=None,
     ):
     return Publisher(
         connector=Connector(),

modmex_lambda-0.5.0/modmex_lambda/tracing.py

@@ -0,0 +1,189 @@
+"""Lazy OpenTelemetry-compatible tracing helpers."""
+
+from __future__ import annotations
+
+import inspect
+import os
+from contextlib import contextmanager
+from functools import wraps
+from importlib import import_module
+from typing import Any, Callable, Iterator, Mapping, TypeVar
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class _NoopSpan:
+    def set_attribute(self, _key: str, _value: Any) -> None:
+        return None
+
+    def add_event(self, _name: str, attributes: Mapping[str, Any] | None = None) -> None:
+        return None
+
+    def record_exception(self, _exception: BaseException) -> None:
+        return None
+
+
+class Tracer:
+    """Tiny lazy tracer facade.
+
+    The core package does not depend on OpenTelemetry. If ``opentelemetry-api``
+    is unavailable, all operations are no-ops.
+    """
+
+    def __init__(
+        self,
+        *,
+        service: str | None = None,
+        enabled: bool = True,
+        tracer_provider: Any | None = None,
+    ) -> None:
+        self.service = service or os.getenv("SERVICE_NAME") or os.getenv("AWS_LAMBDA_FUNCTION_NAME") or "service"
+        self.enabled = enabled
+        self.tracer_provider = tracer_provider
+        self._tracer: Any | None = None
+        self._cold_start = True
+
+    def capture_method(
+        self,
+        func: F | None = None,
+        *,
+        name: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> F | Callable[[F], F]:
+        def decorator(method: F) -> F:
+            span_name = name or method.__qualname__
+
+            if inspect.iscoroutinefunction(method):
+
+                @wraps(method)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    with self._start_span(span_name, attributes=attributes):
+                        return await method(*args, **kwargs)
+
+                return async_wrapper  # type: ignore[return-value]
+
+            @wraps(method)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with self._start_span(span_name, attributes=attributes):
+                    return method(*args, **kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+    def capture_lambda_handler(
+        self,
+        func: F | None = None,
+        *,
+        name: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> F | Callable[[F], F]:
+        def decorator(handler: F) -> F:
+            span_name = name or handler.__name__
+
+            @wraps(handler)
+            def wrapper(event: Any, context: Any, *args: Any, **kwargs: Any) -> Any:
+                with self._start_span(span_name, attributes=attributes) as span:
+                    self._set_lambda_context_attributes(span, context)
+                    return handler(event, context, *args, **kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        span = self._current_span()
+        span.set_attribute(key, value)
+
+    def add_event(self, name: str, attributes: Mapping[str, Any] | None = None) -> None:
+        span = self._current_span()
+        span.add_event(name, attributes=attributes)
+
+    @contextmanager
+    def _start_span(
+        self,
+        name: str,
+        *,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> Iterator[Any]:
+        tracer = self._get_tracer()
+        if tracer is None:
+            yield _NoopSpan()
+            return
+
+        try:
+            span_context = tracer.start_as_current_span(name)
+        except AttributeError:
+            yield _NoopSpan()
+            return
+
+        with span_context as span:
+            for key, value in (attributes or {}).items():
+                span.set_attribute(key, value)
+            try:
+                yield span
+            except Exception as exc:
+                span.record_exception(exc)
+                self._set_error_status(span)
+                raise
+
+    def _get_tracer(self) -> Any | None:
+        if not self.enabled:
+            return None
+        if self._tracer is not None:
+            return self._tracer
+
+        try:
+            trace = import_module("opentelemetry.trace")
+        except ImportError:
+            return None
+
+        self._tracer = trace.get_tracer(
+            __name__,
+            tracer_provider=self.tracer_provider,
+        )
+        return self._tracer
+
+    def _current_span(self) -> Any:
+        if not self.enabled:
+            return _NoopSpan()
+
+        try:
+            trace = import_module("opentelemetry.trace")
+        except ImportError:
+            return _NoopSpan()
+
+        try:
+            return trace.get_current_span()
+        except AttributeError:
+            return _NoopSpan()
+
+    def _set_lambda_context_attributes(self, span: Any, context: Any) -> None:
+        if self._cold_start:
+            span.set_attribute("faas.coldstart", True)
+            self._cold_start = False
+        else:
+            span.set_attribute("faas.coldstart", False)
+
+        request_id = getattr(context, "aws_request_id", None)
+        if request_id:
+            span.set_attribute("faas.execution", str(request_id))
+
+        function_name = getattr(context, "function_name", None)
+        if function_name:
+            span.set_attribute("faas.name", str(function_name))
+
+    def _set_error_status(self, span: Any) -> None:
+        try:
+            trace = import_module("opentelemetry.trace")
+            span.set_status(trace.Status(trace.StatusCode.ERROR))
+        except (ImportError, AttributeError):
+            return
+
+
+__all__ = ["Tracer"]

{modmex_lambda-0.4.1 → modmex_lambda-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modmex-lambda"
-version = "0.4.1"
+version = "0.5.0"
 description = "Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling."
 readme = "README.md"
 requires-python = ">=3.10,<4.0"