Split streams by what differs
Create a separate stream only when the data needs a different contract: another retention, another access rule, another schema, or a separate query range limit. Otherwise keep data together and tell it apart with fields.
MoleSignal creates a stream on its first write, so a typo in a sender creates a new stream silently.
Check the stream list after connecting each source, and create the
important streams in advance with their retention and encrypted fields.
Agree on field names before sending
Use the OpenTelemetry names wherever they exist, and the same name for the same thing in every signal. Cross-signal jumps and APM depend on them.
Keep the type of a field the same across all senders: a field that arrives as a number from one
service and as text from another is rejected with
type mismatch on field. Normalize such fields in a
pipeline with Convert type before they are stored. Never reuse an existing field name for a new
meaning; add a new field instead.
Index what is filtered
The index type decides how fast a filter is. New fields get none, except a few well-known names. Review the fields that dashboards and alerts filter on:- Exact match for identifiers that are compared as a whole:
trace_id,user_id,order_id,service.name. - Full text search for prose such as
message, searched by words. - Skip index for numbers and times that are compared with
<and>, such asduration_ms. - Nothing for fields that are only displayed.
Keep cardinality out of labels
A metric label with an unbounded value, such as a user ID, a request ID, or a full URL, creates a new series for every value. The cardinality limits then refuse new series for the whole organization. Put such values in logs or span attributes, where they cost nothing per value, and keep metric labels to bounded sets such as service, route template, method, and status class. Reference data that would otherwise be copied into every event, such as the team of a service or the plan of a customer, belongs in an extend table: a pipeline looks it up while processing.Protect sensitive values from the start
Prefer removing a value in the sender or the collector. A value that never leaves the source cannot
leak from MoleSignal.
Acceptance criteria
- Every stream has an owner, a reason to exist, and a retention set on purpose.
- A known request can be followed from its log line to its trace with one click.
- Fields filtered by dashboards and rules have a suitable index.
- No metric label carries an unbounded value, and Cardinality on Metrics shows stable series counts.
- Test events with sensitive markers arrive redacted, masked, or encrypted as planned.