Crate microsandbox_metrics_collector 

Metrics collector orchestrator. Polls the microsandbox shared-memory metrics registry, buffers per-exporter, and fans batches out to registered exporters.

See docs/observability/msb-metrics.mdx for the user-facing overview and the msb-metrics binary that ships in this crate’s bin/main.rs.

Lifecycle

Encoded in types — calling MetricsCollector::start consumes the collector and returns a RunningCollector; calling RunningCollector::shutdown consumes the handle. Both are compile-time errors to call twice.

  [Builder] ─build()?─► [MetricsCollector] ─start().await?─► [RunningCollector]
                                                                         │
                                                         flush()  (fire-and-forget)
                                                         shutdown(self).await

Architecture

  handle.flush() / handle.shutdown(self).await
                  │
                  ▼  mpsc<CollectorCmd>
  ┌─ run loop ─────────────────────────────────────────────┐
  │  collect_ticker → collect_fn → broadcast::send(data)   │
  │  cmd Flush      → broadcast::send(())   (flush signal) │
  │  cmd Shutdown   → drop senders → drain JoinSet         │
  └────┬───────────────────────────────────────┬───────────┘
       │                                       │
       ▼ broadcast<Arc<MetricsCollection>>     ▼ broadcast<()>
         (drop-oldest; lag = drop count)         (cap 1)
       │                                       │
       ▼                                       ▼
  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  │  worker 1   │ │  worker 2   │…│  worker N   │
  │  VecDeque   │ │  VecDeque   │ │  VecDeque   │
  │  + flush    │ │  + flush    │ │  + flush    │
  │    ticker   │ │    ticker   │ │    ticker   │
  │  → export() │ │  → export() │ │  → export() │
  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
         │               │               │
         └─── JoinSet (results aggregated by run loop) ──┘

Two broadcast channels carry two different reliability contracts:

• Data is intentionally lossy. When a worker can’t keep up, the ring rotates and that worker sees RecvError::Lagged(n) — the count flows into its next MetricsExportBatch::dropped_collection_count.
• Flush signal is a single-slot broadcast — explicit RunningCollector::flush just bumps it; coalesced flushes are fine.

Shutdown is structural: dropping the broadcast Senders signals every worker via RecvError::Closed. Each worker runs a final flush, calls exporter.shutdown(), and returns the result. The collector’s run loop collects every result from its JoinSet and aggregates the first error.

Re-exports

pub use core::CatalogLabelSource;

pub use core::DEFAULT_COLLECT_INTERVAL;

pub use core::DEFAULT_EXPORT_TIMEOUT;

pub use core::DEFAULT_FLUSH_INTERVAL;

pub use core::DEFAULT_MAX_BUFFERED_COLLECTIONS;

pub use core::LabelSource;

pub use core::MetricsCollection;

pub use core::MetricsCollector;

pub use core::MetricsCollectorBuilder;

pub use core::MetricsErrorPolicy;

pub use core::MetricsExportBatch;

pub use core::MetricsExporter;

pub use core::MetricsExporterConfig;

pub use core::RunningCollector;

pub use core::SandboxLabels;

Modules

core

Core machinery of the metrics collector orchestrator: builder, run-loop driver, per-exporter worker, the shm reader, and the data types passed between the collector and registered exporters.

exporters

Built-in MetricsExporter implementations.

Structs

SandboxMetricSnapshot

Metrics plus shared-memory identity metadata for one active sandbox slot.

SandboxMetrics

Point-in-time metrics for a running sandbox (no identity fields).

Enums

MetricsCollectorError

Errors raised by the metrics collector.

Type Aliases

MetricsCollectorResult

Result alias for collector operations.