spectra (`uf-spectra`)

Typed metrics, structured event logs, and pluggable storage for Rust services.

Audience

Reader	Use this crate for
App developers	Primary dependency; enable backend features explicitly
Integrators	`Spectra::builder()` and prelude re-exports

Role

Re-exports spectra-core, spectra-runtime, and feature-gated backends
default = ["mem"]; optional sqlite, tensorbase, clickhouse, telemetry-console
CI demo schemas (platform_smoke_*) register via inventory; macros emit typed helpers and topics in linked modules

Configuration

Spectra has no global config file loader. Settings merge in this order (highest wins):

Explicit builder calls — .config(SpectraConfig { ... }), .sink(...), .persist_disabled(), backend constructors
SpectraConfig — programmatic overrides passed to .config()
Environment variables — read by SpectraConfig::from_env() when .config() is omitted
Schema defaults — per-metric/event levels and sample rates from the DSL
Library defaults — documented below

Cargo features

Enable backends at compile time on your spectra dependency. See the root README.

Builder composition

Mode	Calls	Role
Direct persist (default)	`.metrics_backend(..).events_backend(..).build()`	Emit process writes storage
Transport + persist	`.sink(transport).build()`	Dual-path: bus mirror + local persist
Publish only (distributed)	`.sink(transport).persist_disabled().build()`	Publisher — consumers write storage

Publisher/consumer setup: cargo doc -p uf-spectra --open → Getting started → Mode 2, then SpectraSink, topics, and examples quickstart_publish_only / quickstart_consume_forward.

Emit gate and sampling

Loaded by SpectraConfig::from_env() unless .config(...) overrides.

Variable	Default	Effect
`SPECTRA_GATE`	on	Set `0`/`false`/`no` to disable the emit gate (fail-open)
`SPECTRA_LEVEL`	`info`	Global minimum verbosity (`error` … `trace`)
`SPECTRA_SAMPLE_RATE`	`1.0`	Global sample floor after level check
`SPECTRA_SAMPLE_<NAME>`	—	Per metric/event name override (`0.0`–`1.0`)
`SPECTRA_CONFIG`	—	Path to TOML file with a `[spectra]` table

Emit buffer (embedded profile)

Variable	Default	Effect
`SPECTRA_REQUEST_BUFFER`	on	Buffer emits for web request scopes
`SPECTRA_JOB_BUFFER`	on	Buffer emits for worker scopes
`SPECTRA_COUNTER_AGGREGATE`	on	Coalesce counter deltas while buffering

Set any of these to 0/false/no to disable.

Web note: prefer try_record_*_now / generated helpers (L2 enqueue) over request_scope. request_scope drops undrained emits on panic or early exit — avoid if you need failure telemetry.

Async storage persist (builder)

Configure L2 queue/batch on Spectra::builder() — not environment variables:

use std::time::Duration;
use spectra::{PersistConfig, Spectra};

Spectra::builder()
    // …backends…
    .persist(PersistConfig {
        queue_max: 8192,                      // overflow policy applies when full
        batch_max: 2048,                      // raise for DW firehose
        batch_wait: Duration::from_millis(5), // coalesce delay
        batch_enabled: true,                  // use batch insert APIs
    })
    .build()?;

Field	Default	Role
`queue_max`	8192	Bound L2 mpsc; see `overflow`
`overflow`	`Drop`	`Drop` (lossy, default) or `Block` (backpressure)
`batch_max`	32	Max jobs per batch insert
`batch_wait`	5ms	Coalesce delay when batch still size 1
`batch_enabled`	true	Use `record_*_batch` APIs

After fire-and-forget *_now emits, scripts that need durability before exit call spectra.flush_persist().await.

Telemetry console (`telemetry-console` feature)

Variable	Default	Effect
`SPECTRA_CONSOLE`	off	Mirror safe fields to stderr
`SPECTRA_SYNC_HOT_PATH`	off	Invoke transport sink on emit thread

Use .telemetry_ndjson(dir) on the builder to write {dir}/metrics.ndjson and {dir}/events.ndjson.

Remote backends

Variable	Used by
`SPECTRA_TENSORBASE_URL`	`tensorbase` feature — integration tests and adapters
`SPECTRA_CLICKHOUSE_URL`	`clickhouse` feature — integration tests and adapters

Debug

Variable	Effect
`COUNTER_ROOTCAUSE`	Enable internal persist-path counters (debugging)

Backend wiring

In-memory (default)

use spectra::{MemEventsBackend, MemMetricsBackend, Spectra};

let _spectra = Spectra::builder()
    .metrics_backend(std::sync::Arc::new(MemMetricsBackend::new()))
    .events_backend(std::sync::Arc::new(MemEventsBackend::new()))
    .embedded()
    .build()?;

SQLite (durable embedded)

use spectra::{SqliteEventsBackend, SqliteMetricsBackend, Spectra};

let metrics = SqliteMetricsBackend::new("/tmp/spectra-metrics.db")?;
let events = SqliteEventsBackend::new("/tmp/spectra-events.db")?;
let _spectra = Spectra::builder()
    .metrics_backend(std::sync::Arc::new(metrics))
    .events_backend(std::sync::Arc::new(events))
    .embedded()
    .build()?;

Requires features = ["sqlite"].

Remote (ClickHouse / TensorBase)

See spectra-backend-clickhouse/README.md and spectra-backend-tensorbase/README.md.

Schema collection

Your application owns telemetry DSL modules and links them with an explicit mod list. This repository demonstrates the contract with CI demo schemas under schemas/ and re-exports smoke helpers and topics from those expansions.

Examples

export CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target-spectra-extract
cargo run -p uf-spectra --example quickstart --features mem
cargo run -p uf-spectra --example quickstart_transport --features mem
cargo run -p uf-spectra --example quickstart_publish_only --features mem
cargo run -p uf-spectra --example quickstart_consume_forward --features mem
cargo run -p uf-spectra --example quickstart_sqlite --features sqlite
cargo run -p uf-spectra --example quickstart_schema_emit --features mem
cargo run -p uf-spectra --example quickstart_telemetry --features mem,telemetry-console
# Remote (requires live ClickHouse):
SPECTRA_REMOTE_URL=http://localhost:8123 cargo run -p uf-spectra --example quickstart_remote --features clickhouse

Status

Shipped in tag v0.1.0.

uf-spectra 0.1.0

spectra (uf-spectra)