Tracing event reference

Use this reference when consuming structured events or integrating tracing with an application framework. For ordinary logging and error handling, start with Rust diagnostics, Python logging, or CLI diagnostics.

Levels

A WARN or ERROR filter retains the failure's context without requiring INFO or DEBUG spans. The stable lifecycle contract below permits additive fields; consumers ignore fields they do not recognize. Detailed profiling records and human message wording are outside that contract.

Error fields

Terminal failures and existing internal failure events contain:

The source kind helps distinguish failures that share a reader code and reason. For example, a snapshot failure can identify missing_metadata, not_found, or permission_denied. These categories describe observed failures; they do not establish a retry policy or explain causes that the dependency did not expose.

Consumers should ignore additional fields and handle unfamiliar source kinds. The application controls the rendered text. Raw dependency messages, source chains, paths, URLs, credential values, and panic payloads are not diagnostic fields. Programmatic access to the original source is preserved. The host's panic hook and events emitted by dependencies have their own output policies.

See Source classification for category values and limits.

Returned errors expose these fields without logging; see Inspect a returned error.

Hosts can also use error_source_kind(&error) to classify their own I/O or Arrow failures. It does not emit an event or transfer diagnostic ownership to the core.

Public operation events

The following boundaries own their diagnostic outcome on the delta_arrow_reader target. Each invocation emits INFO started, then one terminal event: INFO completed, ERROR failed, or INFO abandoned. The event name is the family in the table followed by that outcome, for example table_load.failed.

Async operations start on their first poll. Creating and dropping an unpolled future emits nothing. Dropping a pending operation records abandoned; it does not mean that its blocking work has stopped. Only the public caller's operation can emit its terminal event. Blocking work that finishes later cannot report that abandoned operation as successful. Worker panic or unexpected worker cancellation returned to the caller is an ERROR failure. Internal DEBUG phases can finish after the caller abandons the public operation; their completion describes that phase only. The drop handler does not invoke subscribers during panic unwinding. Delivery is not guaranteed after a subscriber panic or process abort.

Internal schema conversion and metadata preparation during loading belong to the load operation. Their DEBUG phase events do not emit another terminal ERROR. Pure helpers such as validate_protocol, predicate_column_type, and fallible option setters return errors without an automatic ERROR event. An application that treats a helper failure as a failed command can use the error fields.

Unavailable fields are not recorded as zero or the string None. A failed request for version 99 can carry requested_snapshot_version = 99 with no resolved snapshot_version. A refresh failure after resolving version 4 can carry both previous_snapshot_version = 3 and snapshot_version = 4.

Event names and the field meanings in these tables form the lifecycle contract. Required failure context is on the ERROR event itself.

Ordinary stream execution

DeltaBatchStream owns one scan_execution operation across all calls to next_batch or Stream::poll_next. Its first poll emits INFO scan_execution.started. It then emits one terminal event:

These events use the same target and identity/time types as public operation events. Each stream gets a fresh operation_id; plan_id identifies the plan that created it. Every event carries snapshot_version, backend, and partition_count. ERROR events also carry the error fields, so filtering out INFO still leaves a self-contained failure.

Elapsed time starts at the first poll and includes consumer waiting between polls. It is wall time, not CPU time. Reaching a zero-row limit completes without reading data. Reaching a positive limit completes with the final returned batch; otherwise, returning the last batch alone does not prove EOF. The caller must poll again to observe completion.

Dropping an unpolled stream emits nothing. Dropping only a pending next_batch future leaves its borrowed stream alive and resumable. Dropping a started stream requests cleanup, but does not prove blocking producers have stopped. Their late completion cannot emit success for the dropped stream. Once terminal, further polling and cleanup emit no additional terminal event.

Only the explicit scan_execution_cancelled error reason or the scheduler's cancellation state produces a normal cancellation outcome. Unexpected worker abort/panic and internal capacity failures remain ERROR failures, even when their compatibility error code is cancelled. Returned errors and cleanup behavior are unchanged.

Recoverable network warmup

Optional network sampling can fail while the load or plan succeeds. A timed-out or failed sample emits WARN network_warmup.degraded, with the owning operation, operation_id, available version/backend, and operation elapsed time. phase is initialization or recovery; status is timeout or read_failed. Failure to construct the optional partial-read transport uses transport_unavailable. Read and transport failures include error_source_kind when a typed source is available. The previous estimator remains usable.

There is at most one warning per attempt: initialization and, if sampling started, the table's one deferred recovery attempt. Concurrent eligible scans share that recovery result. Insufficient samples, unsupported sampling, and disabled warmup are expected fallbacks, not warnings. Required metadata preparation is different: its failure fails the owning operation and emits ERROR.

DataFusion provider operations

Provider events require the datafusion feature. They use the same delta_arrow_reader target, levels, safe error fields, and operation identities as ordinary reader events. provider_scan.completed means a physical plan was returned. It does not report execution or whole-query success. Repeated and concurrent calls to scan receive distinct operation and plan IDs.

DataFusion physical-plan preparation

with_new_children and repartitioned use the public operation lifecycle above. Each call gets a fresh operation_id and retains the original plan_id, snapshot version, and backend. partition_count starts with the input plan's count and records the returned plan's count after successful repartitioning. completed means the callback returned successfully, including an unchanged plan or Ok(None) when repartitioning is unsupported or unnecessary. It does not mean that reading started or a query completed.

DataFusion partition execution

Each DeltaScanExec::execute(partition, context) call starts a fresh datafusion_partition_execution operation. It owns setup and the returned partition stream. Cloning, repartitioning, and reusing a physical plan preserve plan_id; every execution receives its own operation_id, including concurrent calls for the same partition. A reusable plan stores no execution outcome or subscriber.

These records use the ordinary stream's levels, safe error fields, and output_started semantics. Every record also carries plan_id, snapshot_version, backend, partition_count, and the requested partition. Elapsed time starts at execute and includes consumer waiting between polls.

An empty plan still has one executable partition. Its stream completes on the first poll without reading data. Returning the last batch alone does not report EOF. An upstream DataFusion LIMIT may drop the partition stream after receiving enough rows; that records dropped, even when the query succeeds.

Failure is recorded before wrapping the original DeltaReaderError in DataFusionError::External. Source chains, including task JoinError values, remain available. Each execution reports at most one terminal failure. Separate partitions that fail each report their own failure. Re-polling a terminal stream returns EOF without another event, and releasing execution resources does not require another poll after an error.

The lifecycle guard records through the caller captured at execute, including out-of-scope drop. Detailed work still uses the active polling context described below. A partition outcome does not report whole-query success or failures in other DataFusion operators. The host owns those query-level outcomes.

Task propagation and streaming

When using a scoped subscriber, keep it active while consuming the stream and performing cleanup. into_stream and DataFusion execute without a task-context extension do not bind later polling to their creation scope. Native span nesting and filtering rules apply; the reader does not reset the caller's span stack. Lifecycle records carry operation_id and stream plan_id independently of span filtering.

use delta_arrow_reader::{DeltaReaderError, DeltaTable, DeltaTableBuilder};
use tracing::Subscriber;

fn configure_diagnostics(
    subscriber: impl Subscriber + Send + Sync + 'static,
) -> Result<(), Box<dyn std::error::Error>> {
    tracing::subscriber::set_global_default(subscriber)?;
    Ok(())
}

async fn load_table() -> Result<DeltaTable, DeltaReaderError> {
    DeltaTableBuilder::new("/tmp/table").load_table().await
}

#[cfg(feature = "datafusion")]
async fn execute_with_current_subscriber(
    frame: datafusion::dataframe::DataFrame,
) -> datafusion::common::Result<datafusion::physical_plan::SendableRecordBatchStream> {
    use std::sync::Arc;

    let task = frame.task_ctx();
    let config = task.session_config().clone().with_extension(Arc::new(
        tracing::dispatcher::get_default(Clone::clone),
    ));
    let task = Arc::new(task.with_session_config(config));
    let plan = frame.create_physical_plan().await?;
    datafusion::physical_plan::execute_stream(plan, task)
}

Source classification

Classification follows typed errors through up to 16 wrappers without formatting or parsing their messages. It handles Delta Kernel wrappers explicitly because some omit the wrapped value from std::error::Error::source(). Arrow, Parquet, object-store, I/O, task, and optional DataFusion wrappers retain the useful category they contain. A specific storage status takes precedence over its underlying message. General HTTP connection/request context is used only if no more specific typed cause is found.

When a dependency wraps another DeltaReaderError, classification follows that reader error's source. If it has no source, its stable reader code supplies the category, such as invalid_projection.

unknown means a source exists but exposes no recognized classification. For example, Kernel 0.25 reports an empty log as Generic(String). Classification does not infer a type from these messages. The reader's bounded-version adapter returns typed MissingVersion (missing_version) when it loads a snapshot whose version differs from the requested version.

Categories such as parquet, arrow, and worker_failed can also reflect a dependency that retained a broad category but converted its detailed cause into a string. multiple_errors identifies a DataFusion collection without presenting its first member as the entire cause.

source_chain_limit means the traversal reached its depth bound, including a cyclic source implementation. It is distinct from an error with no source.

Scheduler task failures use DeltaReaderError::ExecutionTaskFailed and preserve their JoinError. Their phase, code, and reason remain execution, cancelled, and partition_scheduler_task_failed for compatibility. Use source_kind() to distinguish worker_panicked from worker_cancelled; the cancelled code alone does not identify a normal caller cancellation. A failure encountered during cleanup does not replace an earlier data error.

Diagnostic coverage

This map connects diagnostic owners with their regression coverage. Use it when changing an operation or adding an adapter.