Skip to main content

Crate spectra_core

Crate spectra_core 

Source
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

§Entry points

§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§

ChainedSink
Forwards each emit to every sink in the chain, synchronously and in registration order.
CountingSink
Forwards to an inner sink while incrementing process-global emit counters.
EmitPolicy
Resolved emit policy for a single metric/event name (schema defaults + runtime overrides).
EventAggregateRequest
Event chart aggregate request.
EventAggregationSpec
Aggregation parameters for event chart queries.
EventGridRow
One row in an event log grid response.
EventQuery
Row-oriented event log query (DataGrid / event log view).
EventQueryResult
Event log query response payload.
EventRow
Event row for query results.
EventWriteRow
One event write row for batch insert.
EventsAggregateFilter
Aggregate query for chart views (adapter input).
EventsQueryFilter
Row filter for event log queries (adapter input).
FieldClassification
Per-field GDPR-oriented metadata for Spectra event schemas.
GridColumnDto
Column descriptor for event log grids.
GridFilterItem
One filter predicate on a grid column.
GridFilterModel
Full filter model for event log queries.
GridPaginationModel
Mirrors MUI GridPaginationModel.
GridSortItem
Single column sort specification.
LabelMatcher
Label key-value equality matcher for metric queries.
MetricEmit
Metric emit envelope for transport publish wrappers.
MetricPoint
Metric point for query results.
MetricPointDto
Single metric sample in a time series.
MetricWriteRow
One metrics write row for batch insert (counter or gauge).
MetricsQuery
Metric explore request (host server fn boundary).
MetricsQueryRange
Time-series query parameters.
MetricsQueryResult
Metric explore response payload.
NameOverride
Per-name runtime override merged on top of schema defaults.
NdjsonFileSink
Append-only NDJSON sink for monolithic observability.
NoOpEventBackend
No-op event backend (default before host wiring).
NoOpMetricsBackend
No-op metrics backend (default before host wiring).
NoOpSink
Sink that discards all records (default before host wiring).
RecordingSink
Append-only in-memory sink for assertions in unit and integration tests.
RootcauseSnapshot
Snapshot of all process-global rootcause counters.
SchemaDetailDto
Full schema detail for the explore UI.
SchemaFieldDto
Field metadata in a schema detail response.
SchemaFieldMetadata
Field metadata for registry / UI (macros populate this).
SchemaListItem
Schema catalog DTO for spectra-app UI.
SchemaMetadata
Runtime metadata for a Spectra schema (event table or metric family).
SchemaMetadataInit
Function-pointer wrapper collected by inventory.
SchemaRegistry
Registry of metric and event schema metadata linked into the current binary.
SliceDto
One slice in a pie or bar chart response.
SpectraConfig
Host boot configuration for the emit gate.
SpectraEvent
Structured event envelope for transport publish wrappers.
SpectraRouter
Resolves event tables and metric names to storage backends.
StatCardDto
Headline stat card shown above charts.
TimeSeriesDto
One labeled time series returned to the explore UI.

Enums§

BufferedEmit
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.
EventAggregateResult
Event aggregate query response (shape depends on view).
EventExploreView
Event explore view selection.
EventMeasure
Aggregation measure for chart views.
GridFilterOperator
Filter operator for a single grid column.
GridLogicOperator
Logic operator combining multiple grid filters.
GridSortDirection
Sort direction for grid columns.
LoggingKind
Event vs metric schema registration.
MetricKind
Metric kind written to NDJSON / storage adapters.
PartitionKind
Time partition granularity for event queries.
SpectraLevel
Verbosity / sampling tier for a Spectra schema (more verbose = greater ordinal).
StorageEngineType
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§

EventStorageBackend
Event storage: subscribers call append_row; explore UI calls query_rows.
MetricsStorageBackend
Metrics storage: subscribers call record_*; explore UI calls query_range.
SpectraSink
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 / offset to 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_ident would succeed (no allocation / error construction).
job_enabled
SPECTRA_JOB_BUFFER (1/true/yes). Default on for worker scopes; set 0 to 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_count rows and one statement flush.
record_storage_batch_write_metrics
One batched metrics INSERT: counts row_count rows 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; set 0 to 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 (or true/yes).
row_matches_filter
Whether row matches the full grid filter model (items + quick filter).
row_matches_partition
Whether row matches optional partition against fields.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 (None or "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 f with super::current_emit_ts returning ts for 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.
SharedEventBackend
Shared handle to an event storage backend.
SharedMetricsBackend
Shared handle to a metrics storage backend.