hexastack-otel 0.0.0__tar.gz

hexastack_otel-0.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: hexastack-otel
+Version: 0.0.0
+Summary: OpenTelemetry distributed tracing, OTLP exporter integration, and CQRS tracing middleware for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0 ; extra == 'otlp'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0 ; extra == 'otlp'
+Requires-Python: >=3.13
+Provides-Extra: otlp
+Description-Content-Type: text/markdown
+
+# hexastack-otel
+
+**Vendor-agnostic OpenTelemetry distributed tracing and CQRS telemetry middleware for Hexastack.**
+
+Part of the [Hexastack Framework](https://github.com/TheTrueSCU/hexastack).
+
+---
+
+## 1. Architectural Overview
+
+`hexastack-otel` provides a pure hexagonal port interface ([`TracingPort`](file:///home/rjdw/Projects/hexastack/packages/hexastack_otel/src/hexastack_otel/ports/tracing.py)) backed by the official **OpenTelemetry Python SDK**.
+
+It enables 100% vendor-agnostic distributed tracing, automatically linking correlation IDs and creating spans across CQRS Command/Query executions, HTTP endpoints, and gRPC RPCs.
+
+```mermaid
+graph TD
+    CQRS["CQRS Command / Query Dispatch"]
+    MW["TracingMiddleware (order=12)"]
+    PORT["TracingPort"]
+    OTEL["OtelTracingAdapter\n(OpenTelemetry SDK)"]
+    MEM["InMemoryTracingAdapter\n(Test Isolation)"]
+    OTLP["OTLP Exporter\n(gRPC / HTTP)"]
+    COLLECTOR["OTel Collector / Jaeger / Grafana Tempo / Sift"]
+
+    CQRS --> MW
+    MW --> PORT
+    PORT -.-> OTEL
+    PORT -.-> MEM
+    OTEL --> OTLP
+    OTLP --> COLLECTOR
+```
+
+---
+
+## 2. Quickstart
+
+### Installation
+
+```bash
+# Core OpenTelemetry SDK & TracingPort
+pip install hexastack-otel
+
+# With OTLP Protobuf Exporters (gRPC & HTTP)
+pip install hexastack-otel[otlp]
+```
+
+### Configuration (`hexastack.toml` or `pyproject.toml`)
+
+```toml
+[hexastack.otel]
+service_name = "order-service"
+endpoint = "http://localhost:4317"
+exporter = "otlp_grpc" # "memory", "console", "otlp_grpc", "otlp_http"
+sample_rate = 1.0
+enabled = true
+```
+
+---
+
+## 3. Automatic CQRS Tracing & Dynamic Feature Flagging
+
+The [`TracingMiddleware`](file:///home/rjdw/Projects/hexastack/packages/hexastack_otel/src/hexastack_otel/infra/middleware.py) automatically wraps every dispatched command or query in a scoped span:
+
+- **Dynamic Feature Flag Control**: Evaluates `features.otel.tracing` via `FeatureFlagPort` dynamically per-message, enabling zero-downtime activation/deactivation of telemetry spans.
+- **Span Name**: `cqrs.CreateOrderCommand`
+- **Attributes**:
+  - `message.name`: `CreateOrderCommand`
+  - `message.type`: `command`
+  - `correlation.id`: `0724ec78-f952-4467...`
+  - `tenant.id`: `tenant-alpha`
+  - `user.id`: `usr_123`
+- **Error Capture**: Automatically catches unhandled exceptions, records them as span exception events, and sets span status to `ERROR`.

hexastack_otel-0.0.0/README.md

@@ -0,0 +1,72 @@
+# hexastack-otel
+
+**Vendor-agnostic OpenTelemetry distributed tracing and CQRS telemetry middleware for Hexastack.**
+
+Part of the [Hexastack Framework](https://github.com/TheTrueSCU/hexastack).
+
+---
+
+## 1. Architectural Overview
+
+`hexastack-otel` provides a pure hexagonal port interface ([`TracingPort`](file:///home/rjdw/Projects/hexastack/packages/hexastack_otel/src/hexastack_otel/ports/tracing.py)) backed by the official **OpenTelemetry Python SDK**.
+
+It enables 100% vendor-agnostic distributed tracing, automatically linking correlation IDs and creating spans across CQRS Command/Query executions, HTTP endpoints, and gRPC RPCs.
+
+```mermaid
+graph TD
+    CQRS["CQRS Command / Query Dispatch"]
+    MW["TracingMiddleware (order=12)"]
+    PORT["TracingPort"]
+    OTEL["OtelTracingAdapter\n(OpenTelemetry SDK)"]
+    MEM["InMemoryTracingAdapter\n(Test Isolation)"]
+    OTLP["OTLP Exporter\n(gRPC / HTTP)"]
+    COLLECTOR["OTel Collector / Jaeger / Grafana Tempo / Sift"]
+
+    CQRS --> MW
+    MW --> PORT
+    PORT -.-> OTEL
+    PORT -.-> MEM
+    OTEL --> OTLP
+    OTLP --> COLLECTOR
+```
+
+---
+
+## 2. Quickstart
+
+### Installation
+
+```bash
+# Core OpenTelemetry SDK & TracingPort
+pip install hexastack-otel
+
+# With OTLP Protobuf Exporters (gRPC & HTTP)
+pip install hexastack-otel[otlp]
+```
+
+### Configuration (`hexastack.toml` or `pyproject.toml`)
+
+```toml
+[hexastack.otel]
+service_name = "order-service"
+endpoint = "http://localhost:4317"
+exporter = "otlp_grpc" # "memory", "console", "otlp_grpc", "otlp_http"
+sample_rate = 1.0
+enabled = true
+```
+
+---
+
+## 3. Automatic CQRS Tracing & Dynamic Feature Flagging
+
+The [`TracingMiddleware`](file:///home/rjdw/Projects/hexastack/packages/hexastack_otel/src/hexastack_otel/infra/middleware.py) automatically wraps every dispatched command or query in a scoped span:
+
+- **Dynamic Feature Flag Control**: Evaluates `features.otel.tracing` via `FeatureFlagPort` dynamically per-message, enabling zero-downtime activation/deactivation of telemetry spans.
+- **Span Name**: `cqrs.CreateOrderCommand`
+- **Attributes**:
+  - `message.name`: `CreateOrderCommand`
+  - `message.type`: `command`
+  - `correlation.id`: `0724ec78-f952-4467...`
+  - `tenant.id`: `tenant-alpha`
+  - `user.id`: `usr_123`
+- **Error Capture**: Automatically catches unhandled exceptions, records them as span exception events, and sets span status to `ERROR`.

hexastack_otel-0.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "hexastack-otel"
+version = "0.0.0"
+description = "OpenTelemetry distributed tracing, OTLP exporter integration, and CQRS tracing middleware for Hexastack"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "pydantic>=2.10.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+otlp = [
+    "opentelemetry-exporter-otlp-proto-grpc>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+otel = "hexastack_otel.infra.bootstrap:OtelBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_otel"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_otel"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_otel.domain"]
+forbidden_modules = [
+    "hexastack_otel.ports",
+    "hexastack_otel.adapters",
+    "hexastack_otel.infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_otel.ports"]
+forbidden_modules = [
+    "hexastack_otel.adapters",
+    "hexastack_otel.infra",
+]

hexastack_otel-0.0.0/pyproject.toml.orig

@@ -0,0 +1,65 @@
+[project]
+name = "hexastack-otel"
+version = "0.0.0"
+description = "OpenTelemetry distributed tracing, OTLP exporter integration, and CQRS tracing middleware for Hexastack"
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "pydantic>=2.10.0",
+]
+
+[project.optional-dependencies]
+otlp = [
+    "opentelemetry-exporter-otlp-proto-grpc>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+
+[project.entry-points."hexastack.bootstrappers"]
+otel = "hexastack_otel.infra.bootstrap:OtelBootstrapper"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_otel"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_otel"]
+layers = [
+    "adapters",
+    "ports",
+    "domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for domain"
+type = "forbidden"
+source_modules = ["hexastack_otel.domain"]
+forbidden_modules = [
+    "hexastack_otel.ports",
+    "hexastack_otel.adapters",
+    "hexastack_otel.infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for ports"
+type = "forbidden"
+source_modules = ["hexastack_otel.ports"]
+forbidden_modules = [
+    "hexastack_otel.adapters",
+    "hexastack_otel.infra",
+]

hexastack_otel-0.0.0/src/hexastack_otel/__init__.py

@@ -0,0 +1,8 @@
+from hexastack_otel import adapters, domain, infra, ports
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+    "ports",
+]

hexastack_otel-0.0.0/src/hexastack_otel/adapters/__init__.py

@@ -0,0 +1,13 @@
+from hexastack_otel.adapters.tracing import (
+    InMemorySpan,
+    InMemoryTracingAdapter,
+    OtelSpan,
+    OtelTracingAdapter,
+)
+
+__all__ = [
+    "InMemorySpan",
+    "InMemoryTracingAdapter",
+    "OtelSpan",
+    "OtelTracingAdapter",
+]

hexastack_otel-0.0.0/src/hexastack_otel/adapters/tracing/__init__.py

@@ -0,0 +1,15 @@
+from hexastack_otel.adapters.tracing.in_memory import (
+    InMemorySpan,
+    InMemoryTracingAdapter,
+)
+from hexastack_otel.adapters.tracing.otel import (
+    OtelSpan,
+    OtelTracingAdapter,
+)
+
+__all__ = [
+    "InMemorySpan",
+    "InMemoryTracingAdapter",
+    "OtelSpan",
+    "OtelTracingAdapter",
+]

hexastack_otel-0.0.0/src/hexastack_otel/adapters/tracing/in_memory.py

@@ -0,0 +1,155 @@
+import time
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+
+from hexastack_otel.domain.context import SpanContext
+from hexastack_otel.ports.tracing import SpanPort, TracingPort
+
+_current_in_memory_span: ContextVar["InMemorySpan | None"] = ContextVar(
+    "current_in_memory_span", default=None
+)
+
+
+class InMemorySpan(SpanPort):
+    """In-memory telemetry span recording all events, status, and attributes.
+
+    Notes/Architectural Intent:
+        Used for isolated unit and property testing without requiring OTel SDK
+        runtime or live network collectors.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        attributes: dict[str, Any] | None = None,
+        context: SpanContext | None = None,
+        parent_context: SpanContext | None = None,
+    ) -> None:
+        self.name = name
+        self.attributes: dict[str, Any] = dict(attributes or {})
+        self.context = context or SpanContext(
+            trace_id=uuid.uuid4().hex,
+            span_id=uuid.uuid4().hex[:16],
+        )
+        self.parent_context = parent_context
+        self.status = "UNSET"
+        self.status_description: str | None = None
+        self.exceptions: list[BaseException] = []
+        self.start_time: float = time.time()
+        self.end_time: float | None = None
+        self.is_ended: bool = False
+
+    def end(self) -> None:
+        """End the span recording."""
+        if not self.is_ended:
+            self.end_time = time.time()
+            self.is_ended = True
+
+    def record_exception(self, exception: BaseException) -> None:
+        """Record an exception on the in-memory span."""
+        self.exceptions.append(exception)
+        self.set_status("ERROR", str(exception))
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set a single key-value attribute on the span."""
+        self.attributes[key] = value
+
+    def set_attributes(self, attributes: dict[str, Any]) -> None:
+        """Set multiple attributes on the span."""
+        self.attributes.update(attributes)
+
+    def set_status(self, status: str, description: str | None = None) -> None:
+        """Set the span status ('OK', 'ERROR', 'UNSET')."""
+        self.status = status
+        self.status_description = description
+
+
+class InMemoryTracingAdapter(TracingPort):
+    """In-memory implementation of TracingPort for test isolation and assertions.
+
+    Notes/Architectural Intent:
+        Collects all finished spans in a local list, enabling assertions on span
+        counts, tags, and exception capture in test suites.
+    """
+
+    def __init__(self) -> None:
+        self.finished_spans: list[InMemorySpan] = []
+
+    def clear(self) -> None:
+        """Clear recorded finished spans."""
+        self.finished_spans.clear()
+
+    def extract_context(self, carrier: dict[str, str]) -> SpanContext | None:
+        traceparent = carrier.get("traceparent") or carrier.get("TRACEPARENT")
+        if not traceparent:
+            return None
+        parts = traceparent.split("-")
+        if len(parts) >= 4:
+            return SpanContext(trace_id=parts[1], span_id=parts[2])
+        return None
+
+    def get_current_span(self) -> InMemorySpan | None:
+        return _current_in_memory_span.get()
+
+    def get_spans_by_name(self, name: str) -> list[InMemorySpan]:
+        """Find recorded spans matching name."""
+        return [s for s in self.finished_spans if s.name == name]
+
+    def inject_context(self, carrier: dict[str, str]) -> None:
+        current = self.get_current_span()
+        if current:
+            ctx = current.context
+            carrier["traceparent"] = f"00-{ctx.trace_id}-{ctx.span_id}-01"
+
+    def start_span(
+        self,
+        name: str,
+        *,
+        attributes: dict[str, Any] | None = None,
+        parent_context: SpanContext | None = None,
+    ) -> InMemorySpan:
+        parent = parent_context
+        current = self.get_current_span()
+        if parent is None and current is not None and isinstance(current, InMemorySpan):
+            parent = current.context
+
+        trace_id = parent.trace_id if parent else uuid.uuid4().hex
+        span_ctx = SpanContext(
+            trace_id=trace_id,
+            span_id=uuid.uuid4().hex[:16],
+        )
+
+        return InMemorySpan(
+            name=name,
+            attributes=attributes,
+            context=span_ctx,
+            parent_context=parent,
+        )
+
+    @contextmanager
+    def trace_scope(
+        self,
+        name: str,
+        *,
+        attributes: dict[str, Any] | None = None,
+    ) -> Iterator[InMemorySpan]:
+        span = self.start_span(name, attributes=attributes)
+        token = _current_in_memory_span.set(span)
+        try:
+            yield span
+        except BaseException as exc:
+            span.record_exception(exc)
+            raise
+        finally:
+            span.end()
+            self.finished_spans.append(span)
+            _current_in_memory_span.reset(token)
+
+
+__all__ = [
+    "InMemorySpan",
+    "InMemoryTracingAdapter",
+]

hexastack_otel-0.0.0/src/hexastack_otel/adapters/tracing/otel.py

@@ -0,0 +1,138 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    SimpleSpanProcessor,
+    SpanExporter,
+)
+from opentelemetry.trace import (
+    NonRecordingSpan,
+    StatusCode,
+    TraceFlags,
+    TraceState,
+)
+from opentelemetry.trace import (
+    Span as OtelRawSpan,
+)
+from opentelemetry.trace.propagation.tracecontext import (
+    TraceContextTextMapPropagator,
+)
+
+from hexastack_otel.domain.context import SpanContext
+from hexastack_otel.ports.tracing import SpanPort, TracingPort
+
+
+class OtelSpan(SpanPort):
+    """Concrete wrapper around an OpenTelemetry SDK Span."""
+
+    def __init__(self, raw_span: OtelRawSpan) -> None:
+        self._span = raw_span
+
+    def end(self) -> None:
+        self._span.end()
+
+    def record_exception(self, exception: BaseException) -> None:
+        self._span.record_exception(exception)
+        self._span.set_status(StatusCode.ERROR, str(exception))
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        self._span.set_attribute(key, value)
+
+    def set_attributes(self, attributes: dict[str, Any]) -> None:
+        self._span.set_attributes(attributes)
+
+    def set_status(self, status: str, description: str | None = None) -> None:
+        code = StatusCode.OK if status.upper() == "OK" else StatusCode.ERROR
+        self._span.set_status(code, description)
+
+
+class OtelTracingAdapter(TracingPort):
+    """Production OpenTelemetry SDK adapter supporting OTLP, Console, and custom exporters.
+
+    Notes/Architectural Intent:
+        Implements TracingPort using opentelemetry-sdk. Supports W3C TraceContext
+        header injection and extraction across distributed service boundaries.
+    """
+
+    def __init__(
+        self,
+        service_name: str = "hexastack-app",
+        tracer_provider: TracerProvider | None = None,
+        exporter: SpanExporter | None = None,
+    ) -> None:
+        self._service_name = service_name
+        self._propagator = TraceContextTextMapPropagator()
+
+        if tracer_provider is not None:
+            self._provider = tracer_provider
+        else:
+            resource = Resource.create({"service.name": service_name})
+            self._provider = TracerProvider(resource=resource)
+            if exporter is not None:
+                self._provider.add_span_processor(SimpleSpanProcessor(exporter))
+
+        self._tracer = self._provider.get_tracer("hexastack", "0.1.0")
+
+    def extract_context(self, carrier: dict[str, str]) -> SpanContext | None:
+        ctx = self._propagator.extract(carrier)
+        current = trace.get_current_span(ctx)
+        span_ctx = current.get_span_context()
+        if span_ctx.is_valid:
+            return SpanContext(
+                trace_id=f"{span_ctx.trace_id:032x}",
+                span_id=f"{span_ctx.span_id:016x}",
+                trace_flags=int(span_ctx.trace_flags),
+            )
+        return None
+
+    def get_current_span(self) -> OtelSpan | None:
+        raw = trace.get_current_span()
+        if raw and raw.is_recording():
+            return OtelSpan(raw)
+        return None
+
+    def inject_context(self, carrier: dict[str, str]) -> None:
+        self._propagator.inject(carrier)
+
+    def start_span(
+        self,
+        name: str,
+        *,
+        attributes: dict[str, Any] | None = None,
+        parent_context: SpanContext | None = None,
+    ) -> OtelSpan:
+        context = None
+        if parent_context:
+            otel_span_context = trace.SpanContext(
+                trace_id=int(parent_context.trace_id, 16),
+                span_id=int(parent_context.span_id, 16),
+                is_remote=True,
+                trace_flags=TraceFlags(parent_context.trace_flags),
+                trace_state=TraceState.from_header([parent_context.trace_state])
+                if parent_context.trace_state
+                else None,
+            )
+            context = trace.set_span_in_context(NonRecordingSpan(otel_span_context))
+
+        raw = self._tracer.start_span(name, attributes=attributes, context=context)
+        return OtelSpan(raw)
+
+    @contextmanager
+    def trace_scope(
+        self,
+        name: str,
+        *,
+        attributes: dict[str, Any] | None = None,
+    ) -> Iterator[OtelSpan]:
+        with self._tracer.start_as_current_span(name, attributes=attributes) as raw:
+            yield OtelSpan(raw)
+
+
+__all__ = [
+    "OtelSpan",
+    "OtelTracingAdapter",
+]

hexastack_otel-0.0.0/src/hexastack_otel/domain/__init__.py

@@ -0,0 +1,11 @@
+from hexastack_otel.domain.context import SpanContext
+from hexastack_otel.domain.exceptions import (
+    OtelError,
+    TracingConfigurationError,
+)
+
+__all__ = [
+    "OtelError",
+    "SpanContext",
+    "TracingConfigurationError",
+]

hexastack_otel-0.0.0/src/hexastack_otel/domain/context.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SpanContext:
+    """Immutable representation of a distributed trace context.
+
+    Notes/Architectural Intent:
+        Standardized representation of W3C TraceContext headers (traceparent)
+        for cross-service context propagation. Represents pure domain context.
+    """
+
+    trace_id: str
+    span_id: str
+    trace_flags: int = 1
+    trace_state: str = ""
+
+
+__all__ = [
+    "SpanContext",
+]

hexastack_otel-0.0.0/src/hexastack_otel/domain/exceptions.py

@@ -0,0 +1,20 @@
+from hexastack_core.domain.exceptions import HexastackError
+
+
+class OtelError(HexastackError):
+    """Base exception for all OpenTelemetry telemetry and tracing errors.
+
+    Notes/Architectural Intent:
+        Extends HexastackError to allow telemetry failures to be caught uniformly
+        without leaking OpenTelemetry SDK internals into the core domain.
+    """
+
+
+class TracingConfigurationError(OtelError):
+    """Exception raised when OpenTelemetry tracer initialization or endpoint config fails."""
+
+
+__all__ = [
+    "OtelError",
+    "TracingConfigurationError",
+]

hexastack_otel-0.0.0/src/hexastack_otel/infra/__init__.py

@@ -0,0 +1,10 @@
+from hexastack_otel.infra.bootstrap import OtelBootstrapper
+from hexastack_otel.infra.config import HexastackOtelConfig, register_otel_config
+from hexastack_otel.infra.middleware import TracingMiddleware
+
+__all__ = [
+    "HexastackOtelConfig",
+    "OtelBootstrapper",
+    "register_otel_config",
+    "TracingMiddleware",
+]

hexastack_otel-0.0.0/src/hexastack_otel/infra/bootstrap.py

@@ -0,0 +1,96 @@
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SpanExporter
+
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_otel.adapters.tracing.in_memory import InMemoryTracingAdapter
+from hexastack_otel.adapters.tracing.otel import OtelTracingAdapter
+from hexastack_otel.infra.config import HexastackOtelConfig, register_otel_config
+from hexastack_otel.infra.middleware import TracingMiddleware
+from hexastack_otel.ports.tracing import TracingPort
+
+
+class OtelBootstrapper(BootstrapperPort):
+    """Bootstrapper configuring OpenTelemetry tracing, exporters, and CQRS telemetry middleware.
+
+    Notes/Architectural Intent:
+        Executes at priority order=12 (after logging at 10, before auth at 16).
+        Registers TracingPort and TracingMiddleware into the rodi Container.
+    """
+
+    order: int = 12
+    name: str = "otel"
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Assemble TracingPort and TracingMiddleware into the DI container in Phase 2.
+
+        Args:
+            context: The active BootstrapContext containing DI Container.
+        """
+        di = context.container
+
+        # 1. Read OTel Configuration
+        if HexastackOtelConfig in di:
+            cfg = di.resolve(HexastackOtelConfig)
+        else:
+            cfg = context.get_config("otel", HexastackOtelConfig)
+
+        # 2. Instantiate TracingPort Adapter
+        tracer: TracingPort
+        if cfg.exporter == "memory":
+            tracer = InMemoryTracingAdapter()
+        elif cfg.exporter == "console":
+            tracer = OtelTracingAdapter(
+                service_name=cfg.service_name,
+                exporter=ConsoleSpanExporter(),
+            )
+        elif cfg.exporter == "otlp_grpc":
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                OTLPSpanExporter as GrpcOTLPExporter,
+            )
+
+            grpc_exporter: SpanExporter = GrpcOTLPExporter(
+                endpoint=cfg.endpoint, insecure=True
+            )
+            tracer = OtelTracingAdapter(
+                service_name=cfg.service_name,
+                exporter=grpc_exporter,
+            )
+        elif cfg.exporter == "otlp_http":
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+                OTLPSpanExporter as HttpOTLPExporter,
+            )
+
+            http_exporter: SpanExporter = HttpOTLPExporter(
+                endpoint=f"{cfg.endpoint}/v1/traces"
+            )
+            tracer = OtelTracingAdapter(
+                service_name=cfg.service_name,
+                exporter=http_exporter,
+            )
+        else:
+            tracer = InMemoryTracingAdapter()
+
+        # 3. Register TracingPort in DI Container
+        di.add_instance(tracer, declared_class=TracingPort)
+
+        # 4. Instantiate & Register TracingMiddleware
+        middleware = TracingMiddleware(tracer=tracer, enabled=cfg.enabled)
+        di.add_instance(middleware, declared_class=TracingMiddleware)
+
+        # 5. Store in context properties
+        context.properties["tracing_port"] = tracer
+        context.properties["otel_config"] = cfg
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Register the OpenTelemetry configuration section in Phase 1.
+
+        Args:
+            registry: The active ConfigRegistry instance.
+        """
+        register_otel_config(registry)
+
+
+__all__ = [
+    "OtelBootstrapper",
+]

hexastack_otel-0.0.0/src/hexastack_otel/infra/config.py

@@ -0,0 +1,52 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+
+
+@config_section("otel")
+class HexastackOtelConfig(BaseModel):
+    """Pydantic configuration model for OpenTelemetry tracing subsystem.
+
+    Notes/Architectural Intent:
+        Configured via `[hexastack.otel]` in pyproject.toml or hexastack.toml.
+        Supports in-memory, console, and gRPC/HTTP OTLP exporters.
+    """
+
+    service_name: str = Field(
+        default="hexastack-app",
+        description="Logical service name identifier attached to all telemetry spans.",
+    )
+    endpoint: str = Field(
+        default="http://localhost:4317",
+        description="OTLP collector endpoint URL (e.g. 'http://localhost:4317' or 'http://tempo:4317').",
+    )
+    exporter: Literal["memory", "console", "otlp_grpc", "otlp_http"] = Field(
+        default="memory",
+        description="Target span exporter backend ('memory', 'console', 'otlp_grpc', 'otlp_http').",
+    )
+    sample_rate: float = Field(
+        default=1.0,
+        description="Sampling probability ratio between 0.0 and 1.0.",
+    )
+    enabled: bool = Field(
+        default=True,
+        description="Master switch to activate or bypass tracing middleware.",
+    )
+
+
+__all__ = [
+    "HexastackOtelConfig",
+    "register_otel_config",
+]
+
+
+def register_otel_config(registry: ConfigRegistry) -> None:
+    """Register the OpenTelemetry config section schema in ConfigRegistry.
+
+    Args:
+        registry: Target ConfigRegistry instance.
+    """
+    registry.register_config_section("otel", HexastackOtelConfig)

hexastack_otel-0.0.0/src/hexastack_otel/infra/middleware.py

@@ -0,0 +1,112 @@
+import inspect
+from collections.abc import Callable
+from typing import Any, cast
+
+from hexastack_core.domain import Command, Generic, Query
+from hexastack_core.domain.feature_flags import EvaluationContext
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+from hexastack_core.utils.context import get_correlation_id, get_user_context
+from hexastack_otel.ports.tracing import TracingPort
+
+
+class TracingMiddleware:
+    """CQRS middleware wrapping Command and Query execution in OpenTelemetry spans.
+
+    Notes/Architectural Intent:
+        Automatically creates distributed telemetry spans with correlation ID,
+        message type, tenant ID, and user ID attributes, recording execution
+        failures without altering domain handler logic.
+        Respects dynamic feature flag evaluation via FeatureFlagPort.
+    """
+
+    def __init__(
+        self,
+        tracer: TracingPort,
+        enabled: bool = True,
+        flags: FeatureFlagPort | None = None,
+    ) -> None:
+        """Initialize tracing middleware with a TracingPort implementation.
+
+        Args:
+            tracer: TracingPort instance (Otel or InMemory).
+            enabled: Whether span creation is active.
+            flags: Optional FeatureFlagPort to dynamically evaluate tracing activation.
+        """
+        self._tracer = tracer
+        self._enabled = enabled
+        self._flags = flags
+
+    def __call__[G: Generic, R](
+        self,
+        instance: G,
+        next_call: Callable[[G], R],
+    ) -> R:
+        """Execute handler within a scoped telemetry span.
+
+        Args:
+            instance: Dispatched message instance.
+            next_call: Downstream handler or next middleware in chain.
+
+        Returns:
+            The handler result of type R.
+        """
+        if not self._enabled:
+            return next_call(instance)
+
+        if self._flags is not None:
+            eval_ctx = EvaluationContext.from_current_context()
+            if not self._flags.is_enabled(
+                "features.otel.tracing", default=True, context=eval_ctx
+            ):
+                return next_call(instance)
+
+        span_name = f"cqrs.{instance.__class__.__name__}"
+        attrs = self._build_attributes(instance)
+
+        with self._tracer.trace_scope(span_name, attributes=attrs) as span:
+            result = next_call(instance)
+
+            if inspect.isawaitable(result):
+
+                async def _async_wrap() -> Any:
+                    try:
+                        return await result
+                    except BaseException as exc:
+                        span.record_exception(exc)
+                        raise
+
+                return cast("R", _async_wrap())
+
+            return result
+
+    def _build_attributes(self, instance: Generic) -> dict[str, Any]:
+        """Construct standard telemetry attributes from message context."""
+        msg_name = instance.__class__.__name__
+        msg_type = (
+            "command"
+            if isinstance(instance, Command)
+            else ("query" if isinstance(instance, Query) else "event")
+        )
+
+        attributes: dict[str, Any] = {
+            "message.name": msg_name,
+            "message.type": msg_type,
+        }
+
+        cid = get_correlation_id()
+        if cid:
+            attributes["correlation.id"] = cid
+
+        user_ctx = get_user_context()
+        if user_ctx:
+            if user_ctx.tenant_id:
+                attributes["tenant.id"] = user_ctx.tenant_id
+            if user_ctx.user_id:
+                attributes["user.id"] = user_ctx.user_id
+
+        return attributes
+
+
+__all__ = [
+    "TracingMiddleware",
+]

hexastack_otel-0.0.0/src/hexastack_otel/ports/__init__.py

@@ -0,0 +1,11 @@
+from hexastack_otel.ports.tracing import (
+    SpanContext,
+    SpanPort,
+    TracingPort,
+)
+
+__all__ = [
+    "SpanContext",
+    "SpanPort",
+    "TracingPort",
+]

hexastack_otel-0.0.0/src/hexastack_otel/ports/tracing.py

@@ -0,0 +1,133 @@
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from hexastack_otel.domain.context import SpanContext
+
+
+class SpanPort(ABC):
+    """Abstract port representing an in-flight or completed telemetry span.
+
+    Notes/Architectural Intent:
+        Decouples span instrumentation from underlying tracing backends.
+    """
+
+    @abstractmethod
+    def end(self) -> None:
+        """Complete the span recording."""
+
+    @abstractmethod
+    def record_exception(self, exception: BaseException) -> None:
+        """Record an exception on the span as a telemetry error event.
+
+        Args:
+            exception: The caught exception instance.
+        """
+
+    @abstractmethod
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set a single key-value attribute on the span.
+
+        Args:
+            key: Attribute name string.
+            value: Attribute value (primitive or list).
+        """
+
+    @abstractmethod
+    def set_attributes(self, attributes: dict[str, Any]) -> None:
+        """Set multiple attributes on the span in a single call.
+
+        Args:
+            attributes: Dictionary of key-value attributes.
+        """
+
+    @abstractmethod
+    def set_status(self, status: str, description: str | None = None) -> None:
+        """Set the span status ('OK', 'ERROR', 'UNSET').
+
+        Args:
+            status: Status string identifier.
+            description: Optional diagnostic message.
+        """
+
+
+class TracingPort(ABC):
+    """Primary abstract port contract for distributed tracing and context propagation.
+
+    Notes/Architectural Intent:
+        Wraps OpenTelemetry tracer primitives into a clean hexagonal port interface.
+        Allows switching between OTel SDK, console exporter, or mock in-memory
+        recorders seamlessly.
+    """
+
+    @abstractmethod
+    def extract_context(self, carrier: dict[str, str]) -> SpanContext | None:
+        """Extract a SpanContext from an inbound dictionary carrier.
+
+        Args:
+            carrier: Inbound dictionary containing traceparent headers.
+
+        Returns:
+            Parsed SpanContext instance or None if no valid headers exist.
+        """
+
+    @abstractmethod
+    def get_current_span(self) -> SpanPort | None:
+        """Retrieve the currently active span in the current context/thread.
+
+        Returns:
+            Active SpanPort instance or None if no span is active.
+        """
+
+    @abstractmethod
+    def inject_context(self, carrier: dict[str, str]) -> None:
+        """Inject current trace context into an outbound dictionary carrier (e.g. HTTP headers).
+
+        Args:
+            carrier: Mutable dictionary to receive traceparent headers.
+        """
+
+    @abstractmethod
+    def start_span(
+        self,
+        name: str,
+        *,
+        attributes: dict[str, Any] | None = None,
+        parent_context: SpanContext | None = None,
+    ) -> SpanPort:
+        """Start a new telemetry span.
+
+        Args:
+            name: Span operation name.
+            attributes: Optional key-value attributes to attach.
+            parent_context: Optional parent SpanContext for remote linking.
+
+        Returns:
+            Active SpanPort instance.
+        """
+
+    @abstractmethod
+    @contextmanager
+    def trace_scope(
+        self,
+        name: str,
+        *,
+        attributes: dict[str, Any] | None = None,
+    ) -> Iterator[SpanPort]:
+        """Context manager creating a scoped span that automatically ends on exit.
+
+        Args:
+            name: Span operation name.
+            attributes: Optional key-value attributes to attach.
+
+        Yields:
+            Active SpanPort instance within the context block.
+        """
+
+
+__all__ = [
+    "SpanContext",
+    "SpanPort",
+    "TracingPort",
+]