Module logd 

Wire contracts for the local logging and telemetry service.

The agent records logs from every process, telemetry history, discrete events, and hardware samples into one durable local store. This module carries the shared types that travel between the producers (Rust services, the Python agent) and the writer, plus the request/response envelope the read API and its clients share.

All ingest frames are msgpack with short field-rename keys and a v version byte, so a producer and a writer on different versions stay forward compatible: a reader that sees an unknown v can skip the frame, and new fields ride in the open fields/tags/extra maps without a schema change. The frames travel over the same 4-byte big-endian length framing the other sockets use (crate::frame); this module reuses that codec and does not duplicate it.

Redaction (redact) replaces any field whose key looks secret-bearing with its length only. It mirrors the agent’s structured-logging redaction so no value is ever written to the store in the clear, regardless of which producer emitted it.

Modules

emitter

The reusable event emitter that ships discrete EventFrame records from a service to the ingest socket. Unlike the log layer, events are a first-class capture path, so this module is always available (not gated on tracing-layer). A reusable, non-blocking emitter that ships discrete EventFrame records from any Rust service to the logging daemon’s ingest socket.

Structs

ApiError

The error body returned for a failed request.

ErrorEnvelope

The error envelope: { "error": { "code", "message" } }.

EventFrame

One discrete event: a state transition, a radio lock change, a sidecar drop, a pairing change, a transport error. kind is a dotted classifier.

HwSnapshot

A periodic hardware sample: temperatures, per-core frequency, power rails, pressure-stall, per-iface counters, USB speed, throttle flags. Every reading rides in the open s map so a new signal does not need a schema bump.

LogFrame

One log record from any producer (Rust service, Python agent, subprocess tap). The src is the emitting process or component; tgt is the module or logger target. Structured fields ride in the open f map.

Meta

Response metadata: which plane served it, the envelope version, the server time, and how far the writer is behind real time.

Page

Pagination block: the cursor for the next page and the count in this page.

QueryRequest

A read request against the query API. All fields are optional; an empty request returns the most recent page.

QueryResponse

The success envelope shared by every read endpoint. data is the typed payload (rows, buckets, sessions, stats), page carries pagination, meta carries serving metadata.

SyncRequest

The window selector a mark-synced request carries. An exported window is flipped from unsynced to synced over exactly this selector, so it shares the vocabulary of the export filter: an optional session, a half-open [from_us, to_us) microsecond window, and an optional table list. An empty tables means all four. All fields absent marks every unsynced row.

SyncResponse

The result of a mark-synced request: the count flipped per requested table, and the remaining unsynced count per table after the flip (always all four, so a caller sees the whole store’s pending-push watermark in one response).

TelemetryFrame

One telemetry sample: a single dotted metric key with a numeric value and an open tags map. Replaces the per-field history arrays sampled in the GCS.

Enums

IngestFrame

The kind tag on an ingest frame, so the writer can dispatch one stream of mixed frames to the right table.

Level

Severity levels, matching the integer encoding stored in the log table. Trace/Debug are the high-volume levels dropped first under backpressure; Warn and above are always kept.

LogdError

Errors raised encoding or decoding an ingest frame.

SyncTable

One of the four durable tables a window export and its mark-synced selector can name. Serializes to its lowercase table name so the wire vocabulary matches the kind query parameter the read API already speaks.

Value

The msgpack value type carried in the open field/detail/tag maps. Re-exported so a downstream producer can build an EventFrame detail without taking a direct dependency on rmpv. Represents any valid MessagePack value.

Constants

ENVELOPE_VERSION

The current read-envelope version reported in Meta::v.

LOGD_MAX_FRAME

Maximum ingest frame payload. Log records and hardware snapshots are small; the cap is generous headroom and guards against a runaway producer.

REDACT_PREFIX

Idempotency sentinel: a value already prefixed with this has been redacted and is passed through unchanged.

SECRET_SUFFIXES

Key suffixes (and exact keys, case-insensitive) that mark a field as secret-bearing. Kept in lockstep with the agent’s logging redaction.

WIRE_VERSION

The current wire version stamped on every ingest frame.

Functions

is_secret_key

True when key marks a secret-bearing field: a case-insensitive match where the lower-cased key ends with, or exactly equals, one of SECRET_SUFFIXES.

redact

Redact one string value for the given key.

redact_map

Redact every secret-bearing string field of an open map in place. Non-string values, empty strings, and already-redacted values are left untouched. Returns true if at least one field value was changed.

Type Aliases

Fields

An open msgpack map of extra fields. Values are arbitrary so new telemetry round-trips without a schema change (mirrors the open-state pattern).