sincpro-framework 3.2.0__tar.gz → 3.3.0__tar.gz

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sincpro-framework
-Version: 3.2.0
+Version: 3.3.0
 Summary: Sincpro framework to use DDD, Clean architecture, Hexagonal architecture
 License: MIT
 License-File: LICENSE.md
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: opentelemetry
+Provides-Extra: sentry
 Requires-Dist: dependency-injector (>=4.48.3,<5.0.0)
 Requires-Dist: opentelemetry-api (>=1.20) ; extra == "opentelemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.20) ; extra == "opentelemetry"
@@ -20,7 +21,8 @@ Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.20) ; extra == "opent
 Requires-Dist: opentelemetry-sdk (>=1.20) ; extra == "opentelemetry"
 Requires-Dist: pydantic (>=2.12.5,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.1)
-Requires-Dist: sincpro-log (>=1.0.1,<2.0.0)
+Requires-Dist: sentry-sdk (>=2.0) ; extra == "sentry"
+Requires-Dist: sincpro-log (>=1.1.1,<2.0.0)
 Description-Content-Type: text/markdown
 
 # 🚀 Sincpro Framework: Application Layer Framework within Hexagonal Architecture
@@ -104,7 +106,7 @@ Now you are ready to explore more complex use cases! 🚀
     - [Example of Executing a Use Case](#example-of-executing-a-use-case)
 9. [Summary](#summary)
 10. [Middleware System](#middleware-system-1)
-11. [Observability & Tracing](#observability--tracing)
+11. [Observability](#observability) — tracing (OTLP) + errors (Sentry/GlitchTip)
 12. [Configuration or settings](#configuration-or-settings)
 13. [Variables](#variables)
 
@@ -214,6 +216,12 @@ class PaymentFeature(Feature):
 - Uses type hints to enhance code quality and support features like autocompletion and type checking.
 - Improves development efficiency and reliability.
 
+### Observability (tracing + errors)
+
+- **Tracing** (optional): OpenTelemetry spans on every DTO, export via OTLP (`sincpro-framework[opentelemetry]` + `OTEL_EXPORTER_OTLP_ENDPOINT`).
+- **Errors** (optional): Sentry/GlitchTip capture on bus exceptions (`sincpro-framework[sentry]` + `SENTRY_PYTHON_DSN` in conf). Isolated client — does not call `sentry_sdk.init()`, does not reuse Odoo's client.
+- Independent: you can enable traces, errors, both, or neither.
+
 ## ⚙️ Features vs. Application Service
 
 - **Feature**: Represents a discrete, self-contained use case focused on specific functionality, easy to develop and
@@ -1068,9 +1076,17 @@ The JSON schema format enables powerful AI integrations:
 - **Analysis**: AI can identify optimization opportunities and suggest improvements
 - **Migration**: AI can understand dependencies for migration planning
 
-## Observability & Tracing
+## Observability
+
+The bus always instruments. Extras and env vars only decide **where** data goes.
 
-The framework provides built-in log correlation out of the box and optional distributed tracing via OpenTelemetry.
+| Signal | Extra | Env | Backend |
+|---|---|---|---|
+| Logs (`trace_id` / `span_id`) | none | — | stdout / your logger |
+| Tracing (spans) | `[opentelemetry]` | `OTEL_EXPORTER_OTLP_ENDPOINT` | Tempo / Jaeger |
+| Errors (exceptions) | `[sentry]` | `SENTRY_PYTHON_DSN` (framework conf) | GlitchTip / Sentry |
+
+Missing extra or missing DSN in conf → no-op, the bus still raises. Framework events are independent from the host: Odoo may also capture the same exception with its own release. That is intended.
 
 ### What works without any extra install
 
@@ -1096,6 +1112,46 @@ This installs:
 - `opentelemetry-exporter-otlp-proto-grpc` (primary)
 - `opentelemetry-exporter-otlp-proto-http` (fallback)
 
+### Sentry / GlitchTip (errors)
+
+Same silent contract as OTel. The bus **always** tries to report exceptions; if `sentry-sdk` is missing or the DSN in conf is unset, it is a no-op.
+
+```bash
+pip install sincpro-framework[sentry]
+export SENTRY_PYTHON_DSN=https://KEY@glitchtip.sincpro.dev/1
+```
+
+Conf (`sincpro_framework/conf/sincpro_framework_conf.yml`) resolves `sentry_dsn` from `SENTRY_PYTHON_DSN`. If that env is set, `observability_status()["sentry"]` is `on:init`, not `off`. The framework does **not** call `sentry_sdk.init()` and does not reuse the host client.
+
+Each framework event uses an isolated Sentry `Client` whose `release` is computed once at `UseFramework` init: `{app_name}:{library_version}` (Poetry/installed dist). Not `APP_RELEASE`, not the Python version. Example: `payment-cybersource:5.0.3`. Framework-internal errors use `sincpro-framework:<framework version>`.
+
+Odoo may capture the same exception with Odoo's release. That second event is intended — two products, two releases, same traceback.
+
+The bus reports **before** the error handler runs. A handler that swallows an unexpected exception still produces a GlitchTip event. Expected domain errors can be excluded per instance:
+
+```python
+app = UseFramework("payment-cybersource")  # release auto-detected from the caller package
+app.ignore_sentry_exceptions(ValidationError, InsufficientFunds)
+```
+
+Pass `package="sincpro-payments-sdk"` to `UseFramework` when the caller is not the library itself (tests, a thin adapter).
+
+Observability is optional and must never break the bus. After `build_root_bus()` (or the first `app(dto)` call) every instance exposes a probe:
+
+```python
+status = app.observability_status()
+status["sentry"]  # {active, state, reason}  state: off | on | failed
+status["otel"]
+```
+
+- `off` — extra not installed or conf DSN missing (`sdk_missing`, `dsn_missing`)
+- `on` — isolated client ready (`init`)
+- `failed` — DSN present but client construction broke; the bus still runs. Logged as **warning**.
+
+The instance logger emits: `observability sentry=on:init otel=off:no_endpoint`.
+
+Do not send traces to GlitchTip (`traces_sample_rate=0`); Tempo stays on OTLP.
+
 ### What OpenTelemetry adds
 
 | Without OTel | With OTel |
@@ -1267,6 +1323,7 @@ where you can define some behavior currently we support the following settings:
 
 - `sincpro_framework_log_level`: Log level for the framework logger. Default: `DEBUG`.
 - `otlp_endpoint`: OTLP exporter endpoint for distributed tracing. Resolved from `OTEL_EXPORTER_OTLP_ENDPOINT` env var. Default: `null` (tracing disabled). Requires `sincpro-framework[opentelemetry]`.
+- `sentry_dsn`: GlitchTip/Sentry DSN. Resolved from `SENTRY_PYTHON_DSN`. Default: `null` (error reporting disabled). Requires `sentry-sdk` (or `sincpro-framework[sentry]`). The framework uses an isolated client with `release={app_name}:{library_version}` and never calls `sentry_sdk.init()`. Odoo may capture the same error separately. Use `UseFramework.ignore_sentry_exceptions(...)` for expected errors.
 
 Override the config file using another
 

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/README.md

@@ -79,7 +79,7 @@ Now you are ready to explore more complex use cases! 🚀
     - [Example of Executing a Use Case](#example-of-executing-a-use-case)
 9. [Summary](#summary)
 10. [Middleware System](#middleware-system-1)
-11. [Observability & Tracing](#observability--tracing)
+11. [Observability](#observability) — tracing (OTLP) + errors (Sentry/GlitchTip)
 12. [Configuration or settings](#configuration-or-settings)
 13. [Variables](#variables)
 
@@ -189,6 +189,12 @@ class PaymentFeature(Feature):
 - Uses type hints to enhance code quality and support features like autocompletion and type checking.
 - Improves development efficiency and reliability.
 
+### Observability (tracing + errors)
+
+- **Tracing** (optional): OpenTelemetry spans on every DTO, export via OTLP (`sincpro-framework[opentelemetry]` + `OTEL_EXPORTER_OTLP_ENDPOINT`).
+- **Errors** (optional): Sentry/GlitchTip capture on bus exceptions (`sincpro-framework[sentry]` + `SENTRY_PYTHON_DSN` in conf). Isolated client — does not call `sentry_sdk.init()`, does not reuse Odoo's client.
+- Independent: you can enable traces, errors, both, or neither.
+
 ## ⚙️ Features vs. Application Service
 
 - **Feature**: Represents a discrete, self-contained use case focused on specific functionality, easy to develop and
@@ -1043,9 +1049,17 @@ The JSON schema format enables powerful AI integrations:
 - **Analysis**: AI can identify optimization opportunities and suggest improvements
 - **Migration**: AI can understand dependencies for migration planning
 
-## Observability & Tracing
+## Observability
+
+The bus always instruments. Extras and env vars only decide **where** data goes.
 
-The framework provides built-in log correlation out of the box and optional distributed tracing via OpenTelemetry.
+| Signal | Extra | Env | Backend |
+|---|---|---|---|
+| Logs (`trace_id` / `span_id`) | none | — | stdout / your logger |
+| Tracing (spans) | `[opentelemetry]` | `OTEL_EXPORTER_OTLP_ENDPOINT` | Tempo / Jaeger |
+| Errors (exceptions) | `[sentry]` | `SENTRY_PYTHON_DSN` (framework conf) | GlitchTip / Sentry |
+
+Missing extra or missing DSN in conf → no-op, the bus still raises. Framework events are independent from the host: Odoo may also capture the same exception with its own release. That is intended.
 
 ### What works without any extra install
 
@@ -1071,6 +1085,46 @@ This installs:
 - `opentelemetry-exporter-otlp-proto-grpc` (primary)
 - `opentelemetry-exporter-otlp-proto-http` (fallback)
 
+### Sentry / GlitchTip (errors)
+
+Same silent contract as OTel. The bus **always** tries to report exceptions; if `sentry-sdk` is missing or the DSN in conf is unset, it is a no-op.
+
+```bash
+pip install sincpro-framework[sentry]
+export SENTRY_PYTHON_DSN=https://KEY@glitchtip.sincpro.dev/1
+```
+
+Conf (`sincpro_framework/conf/sincpro_framework_conf.yml`) resolves `sentry_dsn` from `SENTRY_PYTHON_DSN`. If that env is set, `observability_status()["sentry"]` is `on:init`, not `off`. The framework does **not** call `sentry_sdk.init()` and does not reuse the host client.
+
+Each framework event uses an isolated Sentry `Client` whose `release` is computed once at `UseFramework` init: `{app_name}:{library_version}` (Poetry/installed dist). Not `APP_RELEASE`, not the Python version. Example: `payment-cybersource:5.0.3`. Framework-internal errors use `sincpro-framework:<framework version>`.
+
+Odoo may capture the same exception with Odoo's release. That second event is intended — two products, two releases, same traceback.
+
+The bus reports **before** the error handler runs. A handler that swallows an unexpected exception still produces a GlitchTip event. Expected domain errors can be excluded per instance:
+
+```python
+app = UseFramework("payment-cybersource")  # release auto-detected from the caller package
+app.ignore_sentry_exceptions(ValidationError, InsufficientFunds)
+```
+
+Pass `package="sincpro-payments-sdk"` to `UseFramework` when the caller is not the library itself (tests, a thin adapter).
+
+Observability is optional and must never break the bus. After `build_root_bus()` (or the first `app(dto)` call) every instance exposes a probe:
+
+```python
+status = app.observability_status()
+status["sentry"]  # {active, state, reason}  state: off | on | failed
+status["otel"]
+```
+
+- `off` — extra not installed or conf DSN missing (`sdk_missing`, `dsn_missing`)
+- `on` — isolated client ready (`init`)
+- `failed` — DSN present but client construction broke; the bus still runs. Logged as **warning**.
+
+The instance logger emits: `observability sentry=on:init otel=off:no_endpoint`.
+
+Do not send traces to GlitchTip (`traces_sample_rate=0`); Tempo stays on OTLP.
+
 ### What OpenTelemetry adds
 
 | Without OTel | With OTel |
@@ -1242,6 +1296,7 @@ where you can define some behavior currently we support the following settings:
 
 - `sincpro_framework_log_level`: Log level for the framework logger. Default: `DEBUG`.
 - `otlp_endpoint`: OTLP exporter endpoint for distributed tracing. Resolved from `OTEL_EXPORTER_OTLP_ENDPOINT` env var. Default: `null` (tracing disabled). Requires `sincpro-framework[opentelemetry]`.
+- `sentry_dsn`: GlitchTip/Sentry DSN. Resolved from `SENTRY_PYTHON_DSN`. Default: `null` (error reporting disabled). Requires `sentry-sdk` (or `sincpro-framework[sentry]`). The framework uses an isolated client with `release={app_name}:{library_version}` and never calls `sentry_sdk.init()`. Odoo may capture the same error separately. Use `UseFramework.ignore_sentry_exceptions(...)` for expected errors.
 
 Override the config file using another
 

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sincpro-framework"
-version = "3.2.0"
+version = "3.3.0"
 description = "Sincpro framework to use DDD, Clean architecture, Hexagonal architecture"
 authors = ["Gutierrez Andres <andru1236@gmail.com>"]
 readme = "README.md"
@@ -17,11 +17,12 @@ python = "^3.12"
 dependency-injector = "^4.48.3"
 pydantic = "^2.12.5"
 pyyaml = ">=6.0.1"
-sincpro-log = "^1.0.1"
+sincpro-log = "^1.1.1"
 opentelemetry-api = {version = ">=1.20", optional = true}
 opentelemetry-sdk = {version = ">=1.20", optional = true}
 opentelemetry-exporter-otlp-proto-grpc = {version = ">=1.20", optional = true}
 opentelemetry-exporter-otlp-proto-http = {version = ">=1.20", optional = true}
+sentry-sdk = {version = ">=2.0", optional = true}
 
 [tool.poetry.extras]
 opentelemetry = [
@@ -30,6 +31,7 @@ opentelemetry = [
     "opentelemetry-exporter-otlp-proto-grpc",
     "opentelemetry-exporter-otlp-proto-http",
 ]
+sentry = ["sentry-sdk"]
 
 [tool.poetry.group.dev.dependencies]
 isort = "^8.0.0"
@@ -37,9 +39,9 @@ black = "^26.1.0"
 pytest = "^9.0.2"
 ipython = "^9.9.0"
 autoflake = "^2.3.1"
-pyright = "^1.1.407"
+pyright = "^1.1.411"
 jupyterlab = "^4.5.1"
-mypy = "^1.19.1"
+mypy = "^2.3.0"
 mkdocs = ">=1.6.1,<2.0.0"
 mkdocs-material = "^9.7.1"
 mkdocstrings = {extras = ["python"], version = "^1.0.0"}
@@ -52,6 +54,7 @@ opentelemetry-api = ">=1.20"
 opentelemetry-sdk = ">=1.20"
 opentelemetry-exporter-otlp-proto-grpc = ">=1.20"
 opentelemetry-exporter-otlp-proto-http = ">=1.20"
+sentry-sdk = ">=2.0"
 
 
 [build-system]
@@ -62,5 +65,7 @@ build-backend = "poetry.core.masonry.api"
 line-length = 94
 
 [tool.pyright]
+venvPath = "."
+venv = ".venv"
 reportInvalidTypeVarUse = "none"
 reportInvalidTypeForm = "none"

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/sincpro_framework/bus.py

@@ -1,5 +1,5 @@
 from logging import Logger
-from typing import Callable, Dict, Optional, Type
+from typing import Callable, Dict, Optional, Tuple, Type
 
 from .exceptions import DTOAlreadyRegistered, UnknownDTOToExecute
 from .sincpro_abstractions import (
@@ -11,7 +11,8 @@ from .sincpro_abstractions import (
     TypeDTOResponse,
 )
 from .sincpro_logger import is_logger_in_debug, logger
-from .tracing.instrumentation import observe_execution, record_observability_span_error
+from .tracing.instrumentation import observe_execution, record_observability_error
+from .tracing.sentry import record_sentry_error
 
 
 class FeatureBus(Bus):
@@ -22,6 +23,8 @@ class FeatureBus(Bus):
         self.handle_error: Optional[Callable] = None
         self.logger: Logger = logger_bus or logger  # type: ignore[assignment]
         self.service_name = ""
+        self.sentry_release = ""
+        self.ignored_sentry_exceptions: Tuple[Type[Exception], ...] = ()
 
     def register_feature(self, dto: Type[DataTransferObject], feature: Feature) -> bool:
         """Register a feature to the bus"""
@@ -54,7 +57,16 @@ class FeatureBus(Bus):
                 return response
 
             except Exception as error:
-                record_observability_span_error(span, error)
+                record_observability_error(
+                    span,
+                    error,
+                    dto_name,
+                    "feature",
+                    self.service_name,
+                    kind="instance",
+                    release=self.sentry_release,
+                    ignored_exceptions=self.ignored_sentry_exceptions,
+                )
                 if self.handle_error:
                     return self.handle_error(error)
                 raise error
@@ -70,6 +82,8 @@ class ApplicationServiceBus(Bus):
         self.handle_error: Optional[Callable] = None
         self.logger = logger_bus or logger
         self.service_name = ""
+        self.sentry_release = ""
+        self.ignored_sentry_exceptions: Tuple[Type[Exception], ...] = ()
 
     def register_app_service(
         self, dto: Type[DataTransferObject], app_service: ApplicationService
@@ -108,7 +122,16 @@ class ApplicationServiceBus(Bus):
                 return response
 
             except Exception as error:
-                record_observability_span_error(span, error)
+                record_observability_error(
+                    span,
+                    error,
+                    dto_name,
+                    "application_service",
+                    self.service_name,
+                    kind="instance",
+                    release=self.sentry_release,
+                    ignored_exceptions=self.ignored_sentry_exceptions,
+                )
                 if self.handle_error:
                     return self.handle_error(error)
                 raise error
@@ -138,6 +161,8 @@ class FrameworkBus(Bus):
         self.app_service_bus = app_service_bus
         self.handle_error: Optional[Callable] = None
         self.logger = logger_bus or logger
+        self.service_name = ""
+        self.sentry_release = ""
 
         registered_features = set(self.feature_bus.feature_registry.keys())
         registered_app_services = set(self.app_service_bus.app_service_registry.keys())
@@ -186,6 +211,15 @@ class FrameworkBus(Bus):
             )
 
         except Exception as error:
+            if isinstance(error, (UnknownDTOToExecute, DTOAlreadyRegistered)):
+                record_sentry_error(
+                    error,
+                    dto_name,
+                    "framework",
+                    self.service_name,
+                    kind="framework",
+                    release=self.sentry_release,
+                )
             if self.handle_error:
                 return self.handle_error(error)
 

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/sincpro_framework/bus.pyi

@@ -1,4 +1,4 @@
-from typing import Any, Callable, Dict, Optional, Type, overload
+from typing import Any, Callable, Dict, Optional, Tuple, Type, overload
 
 from sincpro_log.logger import LoggerProxy
 
@@ -23,6 +23,9 @@ class FeatureBus(Bus):
     feature_registry: Dict[str, Feature]
     handle_error: Optional[Callable[..., Any]]
     logger: LoggerProxy
+    service_name: str
+    sentry_release: str
+    ignored_sentry_exceptions: Tuple[Type[Exception], ...]
 
     def __init__(self, logger_bus: LoggerProxy = ...) -> None: ...
     def register_feature(self, dto: Type[DataTransferObject], feature: Feature) -> bool:
@@ -51,6 +54,9 @@ class ApplicationServiceBus(Bus):
     app_service_registry: Dict[str, ApplicationService]
     handle_error: Optional[Callable[..., Any]]
     logger: LoggerProxy
+    service_name: str
+    sentry_release: str
+    ignored_sentry_exceptions: Tuple[Type[Exception], ...]
 
     def __init__(self, logger_bus: LoggerProxy = ...) -> None: ...
     def register_app_service(
@@ -86,6 +92,8 @@ class FrameworkBus(Bus):
     handle_error: Optional[Callable[..., Any]]
     logger: LoggerProxy
     dto_registry: Dict[str, Any]
+    service_name: str
+    sentry_release: str
 
     def __init__(
         self,

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/sincpro_framework/conf/sincpro_framework_conf.yml

@@ -1,2 +1,3 @@
 sincpro_framework_log_level: DEBUG
 otlp_endpoint: $ENV:OTEL_EXPORTER_OTLP_ENDPOINT
+sentry_dsn: $ENV:SENTRY_PYTHON_DSN

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/sincpro_framework/sincpro_conf.py

@@ -65,6 +65,7 @@ class DefaultFrameworkConfig(SincproConfig):
 
     sincpro_framework_log_level: Literal["INFO", "DEBUG"] = "DEBUG"
     otlp_endpoint: str | None = None
+    sentry_dsn: str | None = None
 
 
 def build_config_obj(

{sincpro_framework-3.2.0 → sincpro_framework-3.3.0}/sincpro_framework/tracing/__init__.py

@@ -7,9 +7,12 @@ whether opentelemetry is installed or not.
 Public API:
   - FrameworkSpanContext   — returned by UseFramework.with_trace()
   - setup_otlp_provider    — called by UseFramework.build_root_bus()
+  - setup_sentry           — called by UseFramework.build_root_bus()
+  - UseFramework.observability_status() — probe off/on/failed, never raises
 """
 
 from .provider import setup_otlp_provider
+from .sentry import setup_sentry
 from .span_context import FrameworkSpanContext
 
-__all__ = ["FrameworkSpanContext", "setup_otlp_provider"]
+__all__ = ["FrameworkSpanContext", "setup_otlp_provider", "setup_sentry"]

sincpro_framework-3.3.0/sincpro_framework/tracing/instrumentation.py

@@ -0,0 +1,122 @@
+"""Bus-level observability: span creation, log correlation, and error recording."""
+
+from contextlib import contextmanager, nullcontext
+from typing import Any, Generator, Tuple, Type
+
+from .sentry import SentryKind, record_sentry_error
+
+try:
+    import opentelemetry  # noqa: F401 — existence check only
+
+    _OTEL_AVAILABLE = True
+except ImportError:
+    _OTEL_AVAILABLE = False
+
+
+@contextmanager
+def observe_execution(
+    dto_name: str, layer: str, instance: str, logger: Any
+) -> Generator[Any, None, None]:
+    """Observability context for a single DTO execution on a bus layer.
+
+    Combines two concerns that must always travel together:
+    - An OTel span named after the DTO, tagged with ``sincpro.layer`` and
+      ``sincpro.instance`` so spans from different bounded contexts are
+      distinguishable in the tracing backend.
+    - Logger binding so every log line emitted inside this block carries the
+      same ``trace_id`` / ``span_id`` as the exported OTel span.
+
+    Yields the active span so callers can record errors via
+    ``record_span_error(span, error)``.
+    """
+    with _dto_span(dto_name, layer, instance) as span:
+        with _bind_span_to_logger(logger, span):
+            yield span
+
+
+def record_observability_error(
+    span: Any,
+    error: Exception,
+    dto_name: str,
+    layer: str,
+    instance: str,
+    kind: SentryKind = "instance",
+    release: str = "",
+    ignored_exceptions: Tuple[Type[Exception], ...] = (),
+) -> None:
+    """Record the exception on the OTel span (if any) and in Sentry (if active).
+
+    Both backends are optional: missing SDK / unset DSN / unset OTLP endpoint
+    are silent no-ops. Callers always invoke this; they never check extras.
+
+    Sentry is invoked before the bus error handler. A handler that swallows
+    the error does not hide it from GlitchTip. Expected types in
+    ``ignored_exceptions`` skip Sentry only; the span is still marked ERROR.
+    """
+    try:
+        record_observability_span_error(span, error)
+        record_sentry_error(
+            error,
+            dto_name,
+            layer,
+            instance,
+            kind=kind,
+            release=release,
+            ignored_exceptions=ignored_exceptions,
+        )
+    except Exception:
+        return
+
+
+def record_observability_span_error(span: Any, error: Exception) -> None:
+    """Record an exception on the active span and mark its status as ERROR."""
+    try:
+        if _OTEL_AVAILABLE and span is not None:
+            from opentelemetry.trace import StatusCode
+
+            span.record_exception(error)
+            span.set_status(StatusCode.ERROR, str(error))
+    except Exception:
+        return
+
+
+# ---------------------------------------------------------------------------
+# Private helpers — implementation details of this module only
+# ---------------------------------------------------------------------------
+
+
+def _dto_span(dto_name: str, layer: str, instance: str):
+    """Return an OTel span CM tagged with sincpro attributes, or a no-op."""
+    try:
+        if _OTEL_AVAILABLE:
+            from .provider import get_framework_tracer
+
+            attrs: dict = {"sincpro.layer": layer}
+            if instance:
+                attrs["sincpro.instance"] = instance
+            tracer = get_framework_tracer("sincpro_framework")
+            if tracer is not None:
+                return tracer.start_as_current_span(dto_name, attributes=attrs)
+    except Exception:
+        pass
+    return nullcontext()
+
+
+def _bind_span_to_logger(logger: Any, span: Any):
+    """Bind the active OTel span's trace_id/span_id to the shared logger.
+
+    Works for any case: explicit with_trace(), inherited outer span (FastAPI,
+    Celery), or a fresh root span created by the bus itself.
+    Returns a context manager that restores the logger's previous fields on exit.
+    """
+    try:
+        if _OTEL_AVAILABLE and span is not None:
+            span_ctx = span.get_span_context()
+            if span_ctx.is_valid:
+                return logger.context(
+                    trace_id=format(span_ctx.trace_id, "032x"),
+                    span_id=format(span_ctx.span_id, "016x"),
+                )
+    except Exception:
+        pass
+    return nullcontext()

sincpro_framework-3.3.0/sincpro_framework/tracing/provider.py

@@ -0,0 +1,116 @@
+"""OTLP TracerProvider auto-configuration."""
+
+from typing import Any
+
+from sincpro_log.logger import LoggerProxy
+
+from ..sincpro_conf import settings
+from .status import ComponentStatus, component_status, status_from_exception
+
+# Private provider owned by sincpro. Kept separate from the global OTel provider
+# so sincpro spans carry their own service.name even when another framework
+# (Odoo, FastAPI, Celery) already registered the global provider first.
+_sincpro_provider: Any = None
+
+
+def _get_current_otel_context() -> dict:
+    """Return trace_id and span_id from the currently active OTel span, or {}."""
+    try:
+        from opentelemetry import trace
+
+        span_ctx = trace.get_current_span().get_span_context()
+        if span_ctx.is_valid:
+            return {
+                "trace_id": format(span_ctx.trace_id, "032x"),
+                "span_id": format(span_ctx.span_id, "016x"),
+            }
+    except Exception:
+        pass
+    return {}
+
+
+def _host_provider_is_real() -> bool:
+    try:
+        from opentelemetry import trace
+
+        current_type = type(trace.get_tracer_provider()).__name__
+        return current_type not in ("ProxyTracerProvider", "NoOpTracerProvider")
+    except Exception:
+        return False
+
+
+def setup_otlp_provider(
+    service_name: str, logger: LoggerProxy | None = None
+) -> ComponentStatus:
+    """Configure a dedicated TracerProvider for this bounded context.
+
+    Never raises. Missing SDK or endpoint is ``off``. A host that already
+    registered a real TracerProvider is ``on:host`` even without our endpoint.
+    """
+    global _sincpro_provider
+
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        from opentelemetry.sdk.trace.sampling import ALWAYS_ON, ParentBased
+    except ImportError:
+        return component_status(False, "off", "sdk_missing")
+    except Exception as exc:
+        return status_from_exception(exc)
+
+    endpoint: str | None = settings.otlp_endpoint
+    if not endpoint:
+        if _host_provider_is_real():
+            return component_status(True, "on", "host")
+        return component_status(False, "off", "no_endpoint")
+
+    try:
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+    except ImportError:
+        try:
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        except ImportError:
+            return component_status(False, "failed", "exporter_missing")
+        except Exception as exc:
+            return status_from_exception(exc)
+    except Exception as exc:
+        return status_from_exception(exc)
+
+    try:
+        provider = TracerProvider(
+            resource=Resource(attributes={SERVICE_NAME: service_name}),
+            sampler=ParentBased(root=ALWAYS_ON),
+        )
+        provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+        _sincpro_provider = provider
+
+        current_type: str = type(trace.get_tracer_provider()).__name__
+        if current_type in ("ProxyTracerProvider", "NoOpTracerProvider"):
+            trace.set_tracer_provider(provider)
+
+        if logger is not None:
+            logger.set_getter_context(_get_current_otel_context)
+        return component_status(True, "on", "init")
+    except Exception as exc:
+        return status_from_exception(exc)
+
+
+def get_framework_tracer(instrumentation_name: str) -> Any:
+    """Return a Tracer from sincpro's private provider, or the global fallback.
+
+    Using the private provider (when setup_otlp_provider was called) ensures spans
+    carry sincpro's own service.name rather than inheriting the host application's.
+    Falls back to the global provider when running without explicit OTel setup —
+    covers the case where the host already configured a provider that sincpro should
+    just piggyback on.
+    """
+    try:
+        if _sincpro_provider is not None:
+            return _sincpro_provider.get_tracer(instrumentation_name)
+        from opentelemetry import trace as otel_trace
+
+        return otel_trace.get_tracer(instrumentation_name)
+    except Exception:
+        return None