DataExcept 1.6.0__tar.gz → 1.7.0__tar.gz

{dataexcept-1.6.0 → dataexcept-1.7.0}/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-09-17
+
+### Added
+
+- **A product-neutral observability context.** `OperationContext` carries
+  stable system, component and operation labels separately from request, job,
+  correlation, trace and span identifiers. `exception_to_observability_event()`
+  combines that context with the existing redacted exception envelope without
+  coupling DataExcept to a framework or telemetry SDK.
+- **Dependency-free OpenTelemetry support.** Exception conversion exposes the
+  standard `exception.*` attributes plus `dataexcept.failure.*` recovery
+  metadata and can record an exception through the minimal span interface
+  without importing OpenTelemetry.
+- **Dependency-free Sentry enrichment.** Sentry events can carry the redacted
+  DataExcept envelope and operation context while only low-cardinality fields
+  become tags.
+- **W3C Trace Context continuity.** `traceparent` can be parsed without a
+  tracing runtime, with `tracestate` and `baggage` preserved for forwarding.
+  Invalid or all-zero identifiers are rejected rather than replaced with
+  invented provenance, and an incoming parent span ID is never mislabelled as
+  a local span ID.
+- **Framework-neutral execution-boundary adapters** for HTTP requests,
+  background workers and workflow/orchestrator steps. They map stable operation
+  names and correlation identifiers onto the common context while keeping raw
+  request paths, payloads and task arguments out of indexed telemetry. The
+  adapters depend only on plain mappings and therefore fit ASGI/WSGI services,
+  serverless gateways, Celery/RQ/Arq/Dramatiq-style workers, Airflow/Dagster/
+  Prefect/Argo-style orchestrators and custom runtimes without importing them.
+
+### Changed
+
+- Logging helpers can attach `OperationContext` separately from free-form
+  application context, keeping filterable operation identity distinct from
+  arbitrary payload-shaped values.
+- OpenTelemetry and Sentry now project the same operation context so logs,
+  traces and error trackers can correlate one failure consistently.
+- The documentation home page and the README now link every guide the site
+  publishes. Each release had added its guide to the navigation and stopped
+  there, leaving cause-aware exceptions, failure metadata, parsing context,
+  message brokers and the Pino profile reachable only from the sidebar. A test
+  now fails when a page in the navigation is linked from neither landing page,
+  so the two cannot drift apart again.
+
 ## [1.6.0] - 2026-09-06
 
 ### Added
@@ -21,13 +64,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Structured broker context — `broker`, `topic`, `partition`, `offset`,
   `consumer_group`, `operation` and `timeout_seconds` — with `broker` redacted
   when it is a URL, since a bootstrap address routinely carries credentials.
-  All six take `cause=` on the canonical contract and set `__cause__`.
-
-The hierarchy is about the operation rather than the product, so it fits Kafka,
-RabbitMQ, Pulsar and NATS alike, and the package depends on no broker client.
-Retryability is left unclassified: a rejected publish may be a leader election
-or a missing topic, and the exception cannot tell which.
-
+  The five concrete classes take `cause=` on the canonical contract and set
+  `__cause__`; `MessageBrokerError` itself is a plain base, for catching.
 - **A published Pino profile for the exception envelope.** `exception_to_pino()`
   and `envelope_to_pino()` project an envelope onto the value Pino logs under
   its error key, and `pino_profile_schema()`, `PINO_PROFILE_VERSION` and
@@ -46,21 +84,37 @@ or a missing topic, and the exception cannot tell which.
 - Documented JavaScript and TypeScript usage, including the projection restated
   in JavaScript and a contract test over the fixture pairs.
 
-No Node.js or Pino dependency is added, in either direction: the Python package
-gains a JSON document and a function that renames one field.
+Neither addition brings a dependency. The broker hierarchy describes the
+operation rather than the product, so it fits Kafka, RabbitMQ, Pulsar and NATS
+without any broker client; retryability is left unclassified, because a
+rejected publish may be a leader election or a missing topic and the exception
+cannot tell which. The Pino profile adds a JSON document and a function that
+renames one field — no Node.js or Pino, in either direction.
+
+### Changed
+
+- Pull requests now run the release gate's wheel verification: the built wheel
+  is installed, the source tree is deleted, and the suite runs against the
+  installed distribution. A test that quietly depends on the source tree used
+  to surface only at the last job before publication, which is where it
+  surfaced for 1.5.0.
+- The pre-commit hooks are pinned to the versions `poetry.lock` pins, and a
+  test derives one from the other. They had drifted to isort 8 and ruff 0.16.4
+  against a lock on isort 9 and ruff 0.16.5, which is enough to format a commit
+  differently from what CI then checks.
 
 ## [1.5.0] - 2026-09-06
 
 ### Added
 
 - **Redaction-safe source context for parsing failures.** `ParsingError` and
-  `DeserializationError` accept keyword-only `source`, `format`, `preview` and
-  `cause`, so a failure on untrusted content can be described without keeping
-  the content. `source` is redacted when it is a URL and left alone when it is
-  a file path; `preview` is bounded to 200 characters including its truncation
-  marker, decodes bytes as UTF-8
-  with any undecodable byte shown as `\xNN`, and is redacted like any other
-  public attribute.
+  `DeserializationError` take keyword-only `source`, `preview` and `cause`, and
+  `ParsingError` gains a keyword-only `format` that `DeserializationError`
+  already took positionally — so a failure on untrusted content can be
+  described without keeping the content. `source` is redacted when it is a URL
+  and left alone when it is a file path; `preview` is bounded to 200 characters
+  including its truncation marker, decodes bytes as UTF-8 with any undecodable
+  byte shown as `\xNN`, and is redacted like any other public attribute.
 - `cause=` on both classes, following the canonical 1.4.0 contract: recorded as
   `.cause` and set as `__cause__`.
 - **A published JSON Schema for the structured envelope.** The payload
@@ -708,7 +762,8 @@ First public release.
 - Published to PyPI via OIDC trusted publishing; no long-lived API token is
   involved in a release.
 
-[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.6.0...HEAD
+[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.7.0...HEAD
+[1.7.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.6.0...v1.7.0
 [1.6.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.3.0...v1.4.0

{dataexcept-1.6.0 → dataexcept-1.7.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it using the following metadata."
 title: "DataExcept"
-version: "1.6.0"
+version: "1.7.0"
 authors:
   - family-names: "Ribeiro"
     given-names: "Diogo"
@@ -11,4 +11,4 @@ authors:
 type: software
 url: "https://github.com/DiogoRibeiro7/DataExcept"
 repository-code: "https://github.com/DiogoRibeiro7/DataExcept"
-date-released: "2026-09-06"
+date-released: "2026-09-17"

{dataexcept-1.6.0 → dataexcept-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DataExcept
-Version: 1.6.0
+Version: 1.7.0
 Summary: A Python package providing structured, easily-extendable custom exception types.
 License-Expression: MIT
 License-File: LICENSE
@@ -45,7 +45,7 @@ Description-Content-Type: text/markdown
 - **🏗️ Hierarchical Structure**: Catch one specific error, a whole domain, or every operational error via `DataExceptError`
 - **📦 One Import**: Every exception is available from `dataexcept` directly, or from its domain module — same objects either way
 - **📊 Data Science Focused**: 106 exception classes covering ML pipelines, feature engineering, model training
-- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives
+- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives, or read it through the [Pino projection](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **🔧 Production Ready**: Logging helpers, error context, and exceptions that pickle — so they cross a process boundary with their message, attributes and cause intact
 - **📚 Academic Quality**: Proper documentation, type hints, and citation support
 - **🐍 Python 3.10 – 3.14**: Every supported version tested in CI, with full type safety
@@ -394,14 +394,21 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
 - **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
+- **Cause-aware Exceptions**: [Wrapping a third-party failure](https://diogoribeiro7.github.io/DataExcept/causes/)
+- **Failure Metadata**: [Transient, permanent, or unclassified](https://diogoribeiro7.github.io/DataExcept/failure_metadata/)
+- **Parsing Context**: [Reporting a failure without keeping the payload](https://diogoribeiro7.github.io/DataExcept/parsing_context/)
+- **Message Brokers**: [Publish, consume and acknowledgement failures](https://diogoribeiro7.github.io/DataExcept/brokers/)
 - **Envelope Schema**: [The published envelope contract](https://diogoribeiro7.github.io/DataExcept/envelope_schema/)
+- **Pino Interoperability**: [Consuming envelopes from Node.js](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ## 🎓 Citation
 
 If you use DataExcept in your research, please cite the exact release you used.
-The canonical release metadata is maintained in [CITATION.cff](CITATION.cff).
+The canonical release metadata is maintained in [CITATION.cff](CITATION.cff), and
+the [citation guide](https://diogoribeiro7.github.io/DataExcept/citation/)
+explains how to get the APA and BibTeX forms from it.
 
 ## 📄 License
 

{dataexcept-1.6.0 → dataexcept-1.7.0}/README.md

@@ -18,7 +18,7 @@
 - **🏗️ Hierarchical Structure**: Catch one specific error, a whole domain, or every operational error via `DataExceptError`
 - **📦 One Import**: Every exception is available from `dataexcept` directly, or from its domain module — same objects either way
 - **📊 Data Science Focused**: 106 exception classes covering ML pipelines, feature engineering, model training
-- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives
+- **🧭 Language-neutral envelopes**: exceptions export to strict JSON against a published, versioned schema — so a non-Python consumer can validate what it receives, or read it through the [Pino projection](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **🔧 Production Ready**: Logging helpers, error context, and exceptions that pickle — so they cross a process boundary with their message, attributes and cause intact
 - **📚 Academic Quality**: Proper documentation, type hints, and citation support
 - **🐍 Python 3.10 – 3.14**: Every supported version tested in CI, with full type safety
@@ -367,14 +367,21 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
 - **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
+- **Cause-aware Exceptions**: [Wrapping a third-party failure](https://diogoribeiro7.github.io/DataExcept/causes/)
+- **Failure Metadata**: [Transient, permanent, or unclassified](https://diogoribeiro7.github.io/DataExcept/failure_metadata/)
+- **Parsing Context**: [Reporting a failure without keeping the payload](https://diogoribeiro7.github.io/DataExcept/parsing_context/)
+- **Message Brokers**: [Publish, consume and acknowledgement failures](https://diogoribeiro7.github.io/DataExcept/brokers/)
 - **Envelope Schema**: [The published envelope contract](https://diogoribeiro7.github.io/DataExcept/envelope_schema/)
+- **Pino Interoperability**: [Consuming envelopes from Node.js](https://diogoribeiro7.github.io/DataExcept/pino/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
 ## 🎓 Citation
 
 If you use DataExcept in your research, please cite the exact release you used.
-The canonical release metadata is maintained in [CITATION.cff](CITATION.cff).
+The canonical release metadata is maintained in [CITATION.cff](CITATION.cff), and
+the [citation guide](https://diogoribeiro7.github.io/DataExcept/citation/)
+explains how to get the APA and BibTeX forms from it.
 
 ## 📄 License
 

{dataexcept-1.6.0 → dataexcept-1.7.0}/dataexcept/__init__.py

@@ -121,24 +121,15 @@ from .exceptions import (
     WebhookError,
 )
 from .failure_metadata import FailureKind, FailureMetadata
-from .io_exceptions import (
-    CustomIOError,
-    FileLockError,
-    FileReadError,
-    FileWriteError,
-)
-from .logging_helpers import (
-    Context,
-    log_and_raise,
-    log_exception,
-    log_then_raise,
-)
+from .io_exceptions import CustomIOError, FileLockError, FileReadError, FileWriteError
+from .logging_helpers import Context, log_and_raise, log_exception, log_then_raise
 from .network_exceptions import (
     ConnectionTimeoutError,
     HostUnreachableError,
     NetworkError,
     ProtocolError,
 )
+from .observability import OperationContext, exception_to_observability_event
 from .pandas_exceptions import (
     DtypeMismatchError,
     IndexAlignmentError,
@@ -178,6 +169,7 @@ from .security_exceptions import (
     InvalidTokenError,
     SecurityError,
 )
+from .sentry import enrich_sentry_event
 from .serialization import exception_to_dict, exception_to_json
 from .wrapping import wrap, wrapping
 
@@ -295,6 +287,8 @@ __all__ = [
     "wrapping",
     "exception_to_dict",
     "exception_to_json",
+    "exception_to_observability_event",
+    "OperationContext",
     "ENVELOPE_SCHEMA_ID",
     "ENVELOPE_SCHEMA_VERSION",
     "envelope_schema",
@@ -303,6 +297,7 @@ __all__ = [
     "pino_profile_schema",
     "envelope_to_pino",
     "exception_to_pino",
+    "enrich_sentry_event",
     "Context",
     "log_and_raise",
     "log_exception",

dataexcept-1.7.0/dataexcept/http_context.py

@@ -0,0 +1,136 @@
+"""Framework-neutral HTTP request context for DataExcept observability.
+
+The adapter works with plain header mappings and route templates, so ASGI,
+WSGI, serverless and RPC gateways can use the same logic without becoming
+runtime dependencies of DataExcept.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+
+from .observability import OperationContext
+from .trace_context import W3CTraceContext, trace_context_from_mapping
+
+__all__ = ["HttpContext", "http_context_from_request"]
+
+_METHOD = re.compile(r"^[A-Z][A-Z0-9!#$%&'*+.^_`|~-]*$")
+_DEFAULT_REQUEST_ID_HEADERS = ("x-request-id", "request-id")
+_DEFAULT_CORRELATION_ID_HEADERS = ("x-correlation-id", "correlation-id")
+
+
+def _safe_header_text(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    if not value or "\r" in value or "\n" in value:
+        return None
+    return value
+
+
+def _normalized_headers(headers: Mapping[str, object]) -> dict[str, object]:
+    normalized: dict[str, object] = {}
+    for key, value in headers.items():
+        if isinstance(key, str):
+            normalized[key.lower()] = value
+    return normalized
+
+
+def _first_header(
+    headers: Mapping[str, object],
+    names: Sequence[str],
+) -> str | None:
+    for name in names:
+        value = _safe_header_text(headers.get(name.lower()))
+        if value is not None:
+            return value
+    return None
+
+
+def _validate_header_names(names: Sequence[str], field: str) -> tuple[str, ...]:
+    if isinstance(names, (str, bytes)):
+        raise TypeError(f"{field} must be a sequence of header names")
+    result: list[str] = []
+    for name in names:
+        if not isinstance(name, str):
+            raise TypeError(f"{field} entries must be strings")
+        stripped = name.strip().lower()
+        if not stripped:
+            raise ValueError(f"{field} entries must not be empty")
+        result.append(stripped)
+    return tuple(result)
+
+
+def _operation_name(method: str, route: str | None) -> str:
+    if route is None:
+        return method
+    if not isinstance(route, str):
+        raise TypeError("route must be a string or None")
+    if not route.strip():
+        raise ValueError("route must not be empty")
+    if "?" in route or "#" in route:
+        raise ValueError("route must be a route template without query or fragment")
+    return f"{method} {route}"
+
+
+class HttpContext:
+    """Request operation context plus optional W3C propagation context."""
+
+    __slots__ = ("operation_context", "trace_context")
+
+    def __init__(
+        self,
+        operation_context: OperationContext,
+        trace_context: W3CTraceContext | None,
+    ) -> None:
+        self.operation_context = operation_context
+        self.trace_context = trace_context
+
+
+def http_context_from_request(
+    method: str,
+    *,
+    route: str | None = None,
+    headers: Mapping[str, object] | None = None,
+    system: str | None = "http",
+    component: str | None = None,
+    request_id_headers: Sequence[str] = _DEFAULT_REQUEST_ID_HEADERS,
+    correlation_id_headers: Sequence[str] = _DEFAULT_CORRELATION_ID_HEADERS,
+) -> HttpContext:
+    """Build request observability context from plain HTTP-style inputs.
+
+    ``route`` should be a low-cardinality route template such as
+    ``/users/{id}``, never a raw request path. Request and correlation IDs are
+    read from configurable headers. W3C trace context is propagated when
+    present, but no trace or span identifiers are generated when it is absent.
+    """
+    if not isinstance(method, str):
+        raise TypeError("method must be a string")
+    normalized_method = method.strip().upper()
+    if not _METHOD.fullmatch(normalized_method):
+        raise ValueError("method must be a valid HTTP method token")
+    if headers is None:
+        headers = {}
+    if not isinstance(headers, Mapping):
+        raise TypeError("headers must be a mapping or None")
+
+    normalized = _normalized_headers(headers)
+    request_names = _validate_header_names(request_id_headers, "request_id_headers")
+    correlation_names = _validate_header_names(
+        correlation_id_headers,
+        "correlation_id_headers",
+    )
+
+    operation_context = OperationContext(
+        system=system,
+        component=component,
+        operation=_operation_name(normalized_method, route),
+        request_id=_first_header(normalized, request_names),
+        correlation_id=_first_header(normalized, correlation_names),
+    )
+
+    trace_context = trace_context_from_mapping(normalized)
+    if trace_context is not None:
+        operation_context = trace_context.to_operation_context(operation_context)
+
+    return HttpContext(operation_context, trace_context)

{dataexcept-1.6.0 → dataexcept-1.7.0}/dataexcept/logging_helpers.py

@@ -8,6 +8,7 @@ import logging
 import traceback
 from typing import Any, Iterator, Mapping, Optional
 
+from .observability import OperationContext
 from .redaction import redact_urls_in_text
 
 Context = Mapping[str, Any]
@@ -80,13 +81,25 @@ def _normalize_context_value(value: Any) -> Any:
     return _described(value)
 
 
-def _build_extra(context: Context | None) -> dict[str, Any] | None:
-    if not context:
-        return None
-    serialized = {
-        key: _normalize_context_value(value) for key, value in context.items()
-    }
-    return {"dataexcept_context": serialized}
+def _build_extra(
+    context: Context | None,
+    operation_context: OperationContext | None = None,
+) -> dict[str, Any] | None:
+    extra: dict[str, Any] = {}
+
+    if context:
+        extra["dataexcept_context"] = {
+            key: _normalize_context_value(value) for key, value in context.items()
+        }
+
+    if operation_context is not None:
+        if not isinstance(operation_context, OperationContext):
+            raise TypeError("operation_context must be an OperationContext or None")
+        serialized = operation_context.to_dict()
+        if serialized:
+            extra["dataexcept_operation"] = serialized
+
+    return extra or None
 
 
 def _chain_mentions_a_url(exc: BaseException) -> bool:
@@ -113,11 +126,16 @@ def log_exception(
     logger: Optional[logging.Logger] = None,
     level: int = logging.ERROR,
     context: Context | None = None,
+    operation_context: OperationContext | None = None,
 ) -> None:
     """Log *exc* at the given log *level* using *logger*.
 
     If *logger* is ``None`` a module level logger is used.
 
+    ``context`` remains the free-form application context. ``operation_context``
+    carries the stable request/job/tool-call identifiers shared with tracing and
+    error-tracker integrations.
+
     DataExcept redacts what it renders, but a wrapped third-party exception
     renders itself: an HTTP client's error may quote the credential-bearing URL
     it was called with, and ``exc_info`` makes logging print that whole chain.
@@ -127,7 +145,7 @@ def log_exception(
     """
     if logger is None:
         logger = logging.getLogger(__name__)
-    extra = _build_extra(context)
+    extra = _build_extra(context, operation_context)
 
     if _chain_mentions_a_url(exc):
         formatted = "".join(
@@ -147,12 +165,19 @@ def log_and_raise(
     logger: Optional[logging.Logger] = None,
     level: int = logging.ERROR,
     context: Context | None = None,
+    operation_context: OperationContext | None = None,
 ) -> Iterator[None]:
     """Context manager that logs and re-raises exceptions preserving traceback."""
     try:
         yield
     except Exception as exc:
-        log_exception(exc, logger=logger, level=level, context=context)
+        log_exception(
+            exc,
+            logger=logger,
+            level=level,
+            context=context,
+            operation_context=operation_context,
+        )
         raise
 
 
@@ -161,6 +186,7 @@ def log_then_raise(
     logger: Optional[logging.Logger] = None,
     level: int = logging.ERROR,
     context: Context | None = None,
+    operation_context: OperationContext | None = None,
 ) -> None:
     """Log *exc* and immediately raise it.
 
@@ -168,5 +194,11 @@ def log_then_raise(
     ``with`` block would be too intrusive. Prefer :func:`log_and_raise` whenever
     possible so tracebacks remain untouched.
     """
-    log_exception(exc, logger=logger, level=level, context=context)
+    log_exception(
+        exc,
+        logger=logger,
+        level=level,
+        context=context,
+        operation_context=operation_context,
+    )
     raise exc

dataexcept-1.7.0/dataexcept/observability.py

@@ -0,0 +1,107 @@
+"""Product-neutral observability context for failures crossing boundaries.
+
+Frameworks call the same concepts by different names: request, task, job,
+workflow step, tool call, invocation.  DataExcept keeps the shared part small
+and explicit so adapters can project it into logs, traces, error trackers or
+protocol-specific metadata without making those frameworks runtime
+requirements.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Any
+
+from .redaction import redact_urls_in_text
+from .serialization import exception_to_dict
+
+__all__ = ["OperationContext", "exception_to_observability_event"]
+
+
+@dataclass(frozen=True, slots=True)
+class OperationContext:
+    """Identifiers that describe where an operation is executing.
+
+    ``system``, ``component`` and ``operation`` are intended to stay
+    low-cardinality and are suitable for filtering.  Request, job, correlation,
+    trace and span identifiers are correlation data and should not normally be
+    turned into metric dimensions or indexed tags.
+
+    Every value is optional because inventing provenance is worse than omitting
+    it.  URL-shaped values are redacted before they can leave this object.
+    """
+
+    system: str | None = None
+    component: str | None = None
+    operation: str | None = None
+    request_id: str | None = None
+    job_id: str | None = None
+    correlation_id: str | None = None
+    trace_id: str | None = None
+    span_id: str | None = None
+
+    def __post_init__(self) -> None:
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if value is None:
+                continue
+            if not isinstance(value, str):
+                raise TypeError(f"{field.name} must be a string or None")
+            if not value.strip():
+                raise ValueError(f"{field.name} must not be empty")
+            object.__setattr__(
+                self,
+                field.name,
+                redact_urls_in_text(value, keep_path=False),
+            )
+
+    def to_dict(self) -> dict[str, str]:
+        """Return only the identifiers that are actually present."""
+        return {
+            field.name: value
+            for field in fields(self)
+            if (value := getattr(self, field.name)) is not None
+        }
+
+    def index_fields(self) -> dict[str, str]:
+        """Return only low-cardinality fields suitable for filtering."""
+        return {
+            key: value
+            for key in ("system", "component", "operation")
+            if (value := getattr(self, key)) is not None
+        }
+
+
+def exception_to_observability_event(
+    exc: BaseException,
+    *,
+    operation_context: OperationContext | None = None,
+    include_attributes: bool = True,
+    max_depth: int = 8,
+) -> dict[str, Any]:
+    """Return a strict-JSON-safe failure event shared by observability adapters.
+
+    The exception payload is the canonical DataExcept envelope.  Operation
+    metadata is separate so adapters can index stable fields while retaining
+    high-cardinality correlation identifiers without flattening them into tags.
+    """
+    if operation_context is not None and not isinstance(
+        operation_context, OperationContext
+    ):
+        raise TypeError("operation_context must be an OperationContext or None")
+
+    event: dict[str, Any] = {
+        "event": "exception",
+        "exception": exception_to_dict(
+            exc,
+            include_attributes=include_attributes,
+            max_depth=max_depth,
+        ),
+    }
+
+    if operation_context is not None:
+        operation = operation_context.to_dict()
+        if operation:
+            event["operation"] = operation
+
+    return event