feat(btrblocks): add tracing entry span, drop stray zigzag debug

Instrument `BtrBlocksCompressor::compress` with a
`#[tracing::instrument]` on the `vortex_compressor::cascade` target so
downstream trace consumers (tracing-perfetto, tracing-opentelemetry)
get a distinct BtrBlocks entry frame nested above the generic
`CascadingCompressor::compress` pipeline span.

Also delete the stray `tracing::debug!("zigzag output: {}", ...)` line
in `schemes/integer.rs` — it predates the centralized
`scheme.compress_result` event and is now redundant.

Add a short `# Observability` section to the crate docs pointing at
`vortex_compressor`'s full reference, plus one recipe.

Signed-off-by: Claude <noreply@anthropic.com>

Author: claude

vortex-btrblocks/Cargo.toml

@@ -20,7 +20,7 @@ num-traits = { workspace = true }
 pco = { workspace = true, optional = true }
 rand = { workspace = true }
 rustc-hash = { workspace = true }
-tracing = { workspace = true }
+tracing = { workspace = true, features = ["std", "attributes"] }
 vortex-alp = { workspace = true }
 vortex-array = { workspace = true }
 vortex-buffer = { workspace = true }

vortex-btrblocks/src/canonical_compressor.rs

@@ -38,6 +38,24 @@ pub struct BtrBlocksCompressor(
 
 impl BtrBlocksCompressor {
     /// Compresses an array using BtrBlocks-inspired compression.
+    ///
+    /// This call is instrumented with a `vortex_compressor::cascade` span named
+    /// `BtrBlocksCompressor::compress` so that downstream tracing consumers
+    /// (e.g. `tracing-perfetto`) have a distinct entry frame to pivot on, nested
+    /// above the generic [`CascadingCompressor::compress`] span that actually
+    /// runs the pipeline. See the `Observability` section of the
+    /// [`vortex_compressor`] crate docs for the full tracing reference.
+    #[tracing::instrument(
+        target = "vortex_compressor::cascade",
+        name = "BtrBlocksCompressor::compress",
+        level = "trace",
+        skip_all,
+        fields(
+            len = array.len(),
+            nbytes = array.nbytes(),
+            dtype = %array.dtype(),
+        ),
+    )]
     pub fn compress(&self, array: &ArrayRef) -> VortexResult<ArrayRef> {
         self.0.compress(array)
     }

vortex-btrblocks/src/lib.rs

@@ -52,6 +52,23 @@
 //!     .build();
 //! ```
 //!
+//! # Observability
+//!
+//! [`BtrBlocksCompressor`] participates in the [`vortex_compressor`] tracing target system.
+//! See the [`vortex_compressor` crate docs](vortex_compressor#observability) for the full
+//! reference on targets, spans, and events.
+//!
+//! The top-level [`BtrBlocksCompressor::compress`] call adds its own
+//! `vortex_compressor::cascade` span (named `BtrBlocksCompressor::compress`) that nests
+//! above the generic cascading-compressor pipeline, giving downstream trace consumers a
+//! distinct entry frame.
+//!
+//! Quick start — one line per leaf with scheme, estimated ratio, actual ratio, accepted?:
+//!
+//! ```text
+//! RUST_LOG=vortex_compressor::encode=debug cargo test -p vortex-btrblocks
+//! ```
+//!
 //! [BtrBlocks]: https://www.cs.cit.tum.de/fileadmin/w00cfj/dis/papers/btrblocks.pdf
 
 mod builder;

vortex-btrblocks/src/schemes/integer.rs

@@ -294,7 +294,9 @@ impl Scheme for ZigZagScheme {
 
         let compressed = compressor.compress_child(&encoded.into_array(), &ctx, self.id(), 0)?;
 
-        tracing::debug!("zigzag output: {}", compressed.encoding_id());
+        // NOTE: scheme-level compression results are emitted centrally as the
+        // `scheme.compress_result` event on the `vortex_compressor::encode`
+        // target. See the `Observability` section of the `vortex_compressor` crate docs.
 
         Ok(ZigZag::try_new(compressed)?.into_array())
     }