dataexcept 0.1.0-alpha.2

Structured errors and failure observability for data, ML, and data-engineering systems
Documentation

dataexcept-rs

CI License: MIT

Rust implementation of the DataExcept structured error and failure-observability model.

The project is a companion to the Python DataExcept package. It is not a line-by-line port. The Rust API remains idiomatic while preserving the language-neutral failure metadata and serialized error-envelope contract used across service and process boundaries.

Status: experimental alpha. APIs may change before the first stable release.

Installation

For the alpha release:

[dependencies]
dataexcept = "0.1.0-alpha.2"

Optional observability integrations are feature-gated:

[dependencies]
dataexcept = { version = "0.1.0-alpha.2", features = ["tracing", "opentelemetry", "sentry"] }

Current scope

The alpha includes:

  • transient, permanent, and unknown failure classification;
  • retryability and optional retry-after metadata;
  • JSON-safe structured error envelopes with cause, context, and grouped errors;
  • canonical JSON Schema validation and cross-language fixtures;
  • credential-bearing URL redaction;
  • idiomatic DataError plus conversions from common Rust errors;
  • ingestion, validation, schema, transformation, database, network, broker, and ML error types;
  • product-neutral operation context;
  • W3C Trace Context parsing and propagation;
  • optional tracing, OpenTelemetry, and Sentry integrations;
  • framework-neutral HTTP, worker, broker, and orchestrator boundary adapters.

Example

use dataexcept::{DataError, FailureMetadata};
use serde_json::json;

fn validate() -> dataexcept::Result<()> {
    let error = DataError::new(
        "missing_column",
        "customer_id is required",
    )
    .with_module("pipeline::validation")
    .with_attribute("column", json!("customer_id"))
    .with_failure(FailureMetadata::permanent());

    Err(error)
}

fn main() {
    if let Err(error) = validate() {
        let envelope = error.to_envelope();
        println!("{}", envelope.to_json_pretty().expect("valid JSON"));
    }
}

The resulting envelope contains stable machine-readable fields such as:

{
  "type": "missing_column",
  "module": "pipeline::validation",
  "message": "customer_id is required",
  "attributes": {
    "column": "customer_id"
  },
  "failure": {
    "kind": "permanent",
    "retryable": false,
    "retry_after_seconds": null
  }
}

Runnable examples

The repository includes examples that are compiled in CI:

cargo run --example core_error
cargo run --example observability
cargo run --example boundaries

They cover structured error envelopes, trace-aware observability events, and framework-neutral HTTP/broker boundary context.

Design principles

Rust errors and wire-format errors are separate concerns. Existing domain-specific Rust enums should remain domain-specific; they can be converted to ErrorEnvelope values at process, API, worker, or broker boundaries.

The serialized envelope is a separate language-neutral contract. Compatibility with the canonical DataExcept JSON Schema is protected by cross-language fixtures and contract tests rather than by forcing Python implementation details into Rust.

Observability integrations do not own application runtime configuration. Subscriber setup, OpenTelemetry providers/exporters, and Sentry SDK initialization remain application concerns.

Development

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features

See CONTRIBUTING.md, ROADMAP.md, and CHANGELOG.md.

License

MIT. See LICENSE.