Skip to main content

spectra_core/
lib.rs

1//! Shared ports and types for Spectra metrics and structured event logs.
2//!
3//! Applications usually depend on the `spectra` crate, which re-exports this surface.
4//! The binary wires a [`SpectraSink`] at boot via [`set_sink`].
5//!
6//! # Features
7//!
8//! - **Emit entry points** — [`try_record_counter`], [`try_record_gauge`], [`try_log_event`]
9//!   (and `*_now` / `*_at` variants) with emit gating and optional buffering.
10//! - **Emit gate / config** — [`SpectraConfig`], [`install_config`]; env `SPECTRA_GATE` /
11//!   `SPECTRA_GATE_FORCE_OFF`, level, and sampling overrides.
12//! - **Query DTOs** — [`MetricsQuery`], [`EventQuery`], grid filters, and map helpers.
13//! - **Input validation** — [`validate_spectra_ident`] for metric/table/field tokens;
14//!   [`clamp_event_paging`] bounds event query `limit`/`offset`.
15//! - **Field classification** — [`FieldClassification`] plus [`mask_field_value`] for host/UI
16//!   display (PII / console safety). Query authz remains a host concern.
17//!
18//! # Entry points
19//!
20//! | Concern | API |
21//! |---------|-----|
22//! | Wire sink | [`set_sink`] |
23//! | Emit | [`try_record_counter`], [`try_log_event`], … |
24//! | Gate | [`install_config`], [`SpectraConfig::from_env`] |
25//! | Mask PII | [`mask_field_value`] |
26//! | Validate names | [`validate_spectra_ident`] |
27//! | Page bounds | [`clamp_event_paging`], [`MAX_EVENT_QUERY_LIMIT`] |
28//!
29//! # Re-entrancy
30//!
31//! [`try_record_counter`] and [`try_log_event`] no-op when called while already inside sink
32//! dispatch, preventing loops when a sink handler re-emits telemetry.
33//!
34//! # Notes
35//!
36//! Spectra does not implement session auth or Gauge permissions. Invalid emit names are
37//! dropped (debug log); invalid query identifiers return [`Error::Config`] from backends
38//! that validate before SQL.
39
40mod aggregate;
41mod classification;
42mod config;
43mod dispatcher;
44mod emit_buffer;
45mod entry;
46mod error;
47mod event_filter;
48mod gate;
49mod query;
50mod query_map;
51mod registry;
52mod rootcause;
53mod router;
54mod schema;
55mod sink;
56mod sinks;
57mod storage;
58mod test_util;
59mod topic;
60mod types;
61mod validate;
62
63pub use classification::{mask_field_value, FieldClassification, PII_MASK};
64pub use config::{install_config, EmitPolicy, NameOverride, SpectraConfig};
65pub use emit_buffer::{
66    current_emit_ts, drain, is_active, job_enabled, request_enabled, request_scope, with_emit_ts,
67    worker_scope, BufferedEmit,
68};
69pub use entry::{
70    set_sink, try_log_event, try_log_event_at, try_log_event_now, try_record_counter,
71    try_record_counter_at, try_record_counter_now, try_record_gauge, try_record_gauge_at,
72    try_record_gauge_now,
73};
74pub use error::{Error, Result};
75pub use event_filter::{
76    finalize_event_rows, matches_filter_item, paginate_event_rows, row_matches_filter,
77    row_matches_partition, sort_event_rows,
78};
79pub use query::{
80    EventAggregateRequest, EventAggregateResult, EventAggregationSpec, EventExploreView,
81    EventGridRow, EventMeasure, EventQuery, EventQueryResult, GridColumnDto, GridFilterItem,
82    GridFilterModel, GridFilterOperator, GridLogicOperator, GridPaginationModel, GridSortDirection,
83    GridSortItem, LabelMatcher, MetricPointDto, MetricsQuery, MetricsQueryResult, PartitionKind,
84    SchemaDetailDto, SchemaFieldDto, SchemaListItem, SliceDto, StatCardDto, TimeSeriesDto,
85};
86pub use query_map::{
87    aggregate_request_to_filter, aggregate_rows_to_result, event_query_to_filter, list_schemas,
88    metrics_query_to_range, points_to_metrics_result, rows_to_event_result, schema_detail,
89};
90pub use registry::{
91    collect_distinct_spectra_store_names, LoggingKind, SchemaFieldMetadata, SchemaMetadata,
92    SchemaMetadataInit, SchemaRegistry, SpectraLevel,
93};
94pub use rootcause::{
95    elapsed_ms, enabled as rootcause_enabled, persist_queue_drop_count, record_ndjson_append,
96    record_persist_queue_drop, record_storage_batch_write_events,
97    record_storage_batch_write_metrics, record_storage_write_events, record_storage_write_metrics,
98    RootcauseSnapshot,
99};
100pub use router::SpectraRouter;
101pub use schema::{EVENTS_TABLE, METRICS_TABLE};
102pub use sink::SpectraSink;
103pub use sinks::{ChainedSink, CountingSink, NdjsonFileSink, NoOpSink, RecordingSink};
104pub use storage::{
105    EventRow, EventStorageBackend, EventWriteRow, EventsAggregateFilter, EventsQueryFilter,
106    MetricPoint, MetricWriteRow, MetricsQueryRange, MetricsStorageBackend, NoOpEventBackend,
107    NoOpMetricsBackend, SharedEventBackend, SharedMetricsBackend, StorageEngineType,
108};
109pub use test_util::{reset_config_and_sink_for_test, GLOBAL_TEST_LOCK};
110pub use topic::{event_topic, metric_topic};
111pub use types::{MetricEmit, MetricKind, SpectraEvent};
112pub use validate::{
113    clamp_event_paging, is_valid_spectra_ident, validate_spectra_ident, MAX_EVENT_QUERY_LIMIT,
114    MAX_EVENT_QUERY_OFFSET, MAX_SPECTRA_IDENT_LEN,
115};
116
117/// Re-export for macro `inventory::submit!` in downstream crates.
118pub use quark::inventory;