Expand description
Shared ports and types for Spectra metrics and structured event logs.
Applications usually depend on the spectra crate, which re-exports this surface.
The binary wires a SpectraSink at boot via set_sink.
§Features
- Emit entry points —
try_record_counter,try_record_gauge,try_log_event(and*_now/*_atvariants) with emit gating and optional buffering. - Emit gate / config —
SpectraConfig,install_config; envSPECTRA_GATE/SPECTRA_GATE_FORCE_OFF, level, and sampling overrides. - Query DTOs —
MetricsQuery,EventQuery, grid filters, and map helpers. - Input validation —
validate_spectra_identfor metric/table/field tokens;clamp_event_pagingbounds event querylimit/offset. - Field classification —
FieldClassificationplusmask_field_valuefor host/UI display (PII / console safety). Query authz remains a host concern.
§Entry points
| Concern | API |
|---|---|
| Wire sink | set_sink |
| Emit | try_record_counter, try_log_event, … |
| Gate | install_config, SpectraConfig::from_env |
| Mask PII | mask_field_value |
| Validate names | validate_spectra_ident |
| Page bounds | clamp_event_paging, MAX_EVENT_QUERY_LIMIT |
§Re-entrancy
try_record_counter and try_log_event no-op when called while already inside sink
dispatch, preventing loops when a sink handler re-emits telemetry.
§Notes
Spectra does not implement session auth or Gauge permissions. Invalid emit names are
dropped (debug log); invalid query identifiers return Error::Config from backends
that validate before SQL.
Re-exports§
pub use quark::inventory;
Structs§
- Chained
Sink - Forwards each emit to every sink in the chain, synchronously and in registration order.
- Counting
Sink - Forwards to an inner sink while incrementing process-global emit counters.
- Emit
Policy - Resolved emit policy for a single metric/event name (schema defaults + runtime overrides).
- Event
Aggregate Request - Event chart aggregate request.
- Event
Aggregation Spec - Aggregation parameters for event chart queries.
- Event
Grid Row - One row in an event log grid response.
- Event
Query - Row-oriented event log query (DataGrid / event log view).
- Event
Query Result - Event log query response payload.
- Event
Row - Event row for query results.
- Event
Write Row - One event write row for batch insert.
- Events
Aggregate Filter - Aggregate query for chart views (adapter input).
- Events
Query Filter - Row filter for event log queries (adapter input).
- Field
Classification - Per-field GDPR-oriented metadata for Spectra event schemas.
- Grid
Column Dto - Column descriptor for event log grids.
- Grid
Filter Item - One filter predicate on a grid column.
- Grid
Filter Model - Full filter model for event log queries.
- Grid
Pagination Model - Mirrors MUI
GridPaginationModel. - Grid
Sort Item - Single column sort specification.
- Label
Matcher - Label key-value equality matcher for metric queries.
- Metric
Emit - Metric emit envelope for transport publish wrappers.
- Metric
Point - Metric point for query results.
- Metric
Point Dto - Single metric sample in a time series.
- Metric
Write Row - One metrics write row for batch insert (counter or gauge).
- Metrics
Query - Metric explore request (host server fn boundary).
- Metrics
Query Range - Time-series query parameters.
- Metrics
Query Result - Metric explore response payload.
- Name
Override - Per-name runtime override merged on top of schema defaults.
- Ndjson
File Sink - Append-only NDJSON sink for monolithic observability.
- NoOp
Event Backend - No-op event backend (default before host wiring).
- NoOp
Metrics Backend - No-op metrics backend (default before host wiring).
- NoOp
Sink - Sink that discards all records (default before host wiring).
- Recording
Sink - Append-only in-memory sink for assertions in unit and integration tests.
- Rootcause
Snapshot - Snapshot of all process-global rootcause counters.
- Schema
Detail Dto - Full schema detail for the explore UI.
- Schema
Field Dto - Field metadata in a schema detail response.
- Schema
Field Metadata - Field metadata for registry / UI (macros populate this).
- Schema
List Item - Schema catalog DTO for spectra-app UI.
- Schema
Metadata - Runtime metadata for a Spectra schema (event table or metric family).
- Schema
Metadata Init - Function-pointer wrapper collected by
inventory. - Schema
Registry - Registry of metric and event schema metadata linked into the current binary.
- Slice
Dto - One slice in a pie or bar chart response.
- Spectra
Config - Host boot configuration for the emit gate.
- Spectra
Event - Structured event envelope for transport publish wrappers.
- Spectra
Router - Resolves event tables and metric names to storage backends.
- Stat
Card Dto - Headline stat card shown above charts.
- Time
Series Dto - One labeled time series returned to the explore UI.
Enums§
- Buffered
Emit - A single emit captured in the buffer, with the timestamp taken at emit time.
- Error
- Errors returned by Spectra storage, routing, serialization, and I/O paths.
- Event
Aggregate Result - Event aggregate query response (shape depends on view).
- Event
Explore View - Event explore view selection.
- Event
Measure - Aggregation measure for chart views.
- Grid
Filter Operator - Filter operator for a single grid column.
- Grid
Logic Operator - Logic operator combining multiple grid filters.
- Grid
Sort Direction - Sort direction for grid columns.
- Logging
Kind - Event vs metric schema registration.
- Metric
Kind - Metric kind written to NDJSON / storage adapters.
- Partition
Kind - Time partition granularity for event queries.
- Spectra
Level - Verbosity / sampling tier for a Spectra schema (more verbose = greater ordinal).
- Storage
Engine Type - Storage engine identifier for query routing and UI.
Constants§
- EVENTS_
TABLE - Structured event log table name.
- MAX_
EVENT_ QUERY_ LIMIT - Maximum rows returned by a single event query (inclusive).
- MAX_
EVENT_ QUERY_ OFFSET - Maximum event query offset (inclusive).
- MAX_
SPECTRA_ IDENT_ LEN - Maximum length for metric, table, and JSON field identifier tokens.
- METRICS_
TABLE - Metrics time-series table name.
- PII_
MASK - Replacement shown when a field is classified as PII (or unsafe for console).
Statics§
- GLOBAL_
TEST_ LOCK - Cross-crate test lock for global sink / gate state (spectra-runtime integration tests).
Traits§
- Event
Storage Backend - Event storage: subscribers call
append_row; explore UI callsquery_rows. - Metrics
Storage Backend - Metrics storage: subscribers call
record_*; explore UI callsquery_range. - Spectra
Sink - Synchronous fan-out target for metrics and structured events.
Functions§
- aggregate_
request_ to_ filter - Converts an aggregate request DTO into a storage adapter filter.
- aggregate_
rows_ to_ result - Maps aggregate storage rows into a UI chart result for the requested view.
- clamp_
event_ paging - Clamp event-query
limit/offsetto documented maxima. - collect_
distinct_ spectra_ store_ names - Distinct Spectra store names from schema inventory (always includes
"default"). - current_
emit_ ts - Emit timestamp to stamp right now: the flush override if set, else wall-clock now.
- drain
- Replay buffered records through the public crate, stamping each with its captured emit timestamp. Safe to call while a scope is still bound: the replay guard makes the public-crate dispatch (not re-buffer) during the loop.
- elapsed_
ms - Returns elapsed milliseconds since
start. - event_
query_ to_ filter - Converts a UI event query DTO into a storage adapter filter.
- event_
topic - Typed event topic:
spectra.event.{table}. - finalize_
event_ rows - Apply grid filter, partition, sort, and pagination to table/time-scoped rows.
- install_
config - Install process-wide gate configuration (call once at host boot, before sink install).
- is_
active - True when the current async task is inside an active buffer scope.
- is_
valid_ spectra_ ident - Whether
validate_spectra_identwould succeed (no allocation / error construction). - job_
enabled SPECTRA_JOB_BUFFER(1/true/yes). Default on for worker scopes; set0to disable.- list_
schemas - Lists all registered schemas as catalog DTOs.
- mask_
field_ value - Mask a field value for display or console when classification requires it.
- matches_
filter_ item - Evaluate one filter item against a row.
- metric_
topic - Metric topic:
spectra.metric.{name}. - metrics_
query_ to_ range - Converts a UI metrics query DTO into a storage range filter.
- paginate_
event_ rows - Apply limit/offset pagination.
- persist_
queue_ drop_ count - Total persist jobs dropped because the bounded queue was full.
- points_
to_ metrics_ result - Maps storage metric points into a UI metrics query result.
- record_
ndjson_ append - Records one NDJSON append and its wall time.
- record_
persist_ queue_ drop - Persist job dropped because the bounded queue was full.
- record_
storage_ batch_ write_ events - One batched events INSERT: counts
row_countrows and one statement flush. - record_
storage_ batch_ write_ metrics - One batched metrics INSERT: counts
row_countrows and one statement flush. - record_
storage_ write_ events - Records one event storage write and its wall time.
- record_
storage_ write_ metrics - Records one metrics storage write and its wall time.
- request_
enabled SPECTRA_REQUEST_BUFFER(1/true/yes). Default on for embedded profile; set0to disable.- request_
scope - Web entry point: buffer everything, returning the future output plus the buffered
records for the caller to flush off the response path. Runs unbuffered (empty
Vec) when the gate is off or already inside a scope. - reset_
config_ and_ sink_ for_ test - Reset installed gate config and sink between integration tests in dependent crates.
- rootcause_
enabled - True when
COUNTER_ROOTCAUSE=1(ortrue/yes). - row_
matches_ filter - Whether
rowmatches the full grid filter model (items + quick filter). - row_
matches_ partition - Whether
rowmatches optionalpartitionagainstfields.partition. - rows_
to_ event_ result - Maps storage event rows into a UI event query result.
- schema_
detail - Returns full schema detail for a table or metric name.
- set_
sink - Install the process-wide sink (typically once at server boot).
- sort_
event_ rows - Sort rows by
sort_field(Noneor"ts"→ timestamp; else JSON field string). - try_
log_ event - Log a structured event when a sink is configured; no-op if unset or re-entrant.
- try_
log_ event_ at - Log a structured event immediately with an explicit emit timestamp.
- try_
log_ event_ now - Log a structured event immediately, bypassing any active emit buffer.
- try_
record_ counter - Record a counter when a sink is configured; no-op if unset or re-entrant.
- try_
record_ counter_ at - Record a counter immediately with an explicit emit timestamp.
- try_
record_ counter_ now - Record a counter immediately, bypassing any active emit buffer.
- try_
record_ gauge - Record a gauge when a sink is configured; no-op if unset or re-entrant.
- try_
record_ gauge_ at - Record a gauge immediately with an explicit emit timestamp.
- try_
record_ gauge_ now - Record a gauge immediately, bypassing any active emit buffer.
- validate_
spectra_ ident - Validate a metric name, event table name, or JSON field key used in SQL builders.
- with_
emit_ ts - Run
fwithsuper::current_emit_tsreturningtsfor the duration of the call. - worker_
scope - Worker entry point: buffer emits for the duration of a job, then drain them (blocking) before returning, so the worker does not pick up the next job until telemetry is replayed through the sink. No-op when the gate is off or nested.
Type Aliases§
- Result
- Result type returned by Spectra operations.
- Shared
Event Backend - Shared handle to an event storage backend.
- Shared
Metrics Backend - Shared handle to a metrics storage backend.