Telemetry

Structured, stage‑aware observability for real systems — without affecting decisions or performance.

Telemetry is the fourth and final part of Jane’s analysis layer. If Diff shows you what changed, Explain shows you why it changed, and Replay shows you how it changed, Telemetry answers a different question entirely: How do I capture what happened — reliably, consistently, and without changing the pipeline’s behavior?

Telemetry is Jane’s observability surface. It emits structured, stage‑aware records to a sink you control. It never mutates values, never affects decisions, and never slows down the pipeline. It’s designed for real systems: production services, compliance environments, audit logs, debugging tools, and analytics pipelines.

Telemetry is the bridge between Jane and the rest of your infrastructure.

Why Telemetry Exists

Most validation libraries are black boxes. They tell you whether something passed or failed, but they don’t give you:

• A structured record of what happened.
• Stage‑by‑stage event logs.
• Timestamps.
• Diff/explain/replay outputs.
• Decision metadata.
• Pipeline and boundary names.
• A consistent format for observability tools.

Telemetry exists because real systems need more than true or false. They need traceability.

Telemetry gives you a complete, structured record of the pipeline run — without changing the pipeline itself.

What Telemetry Does

Telemetry collects structured records for each stage of the pipeline:

• Scan events.
• Normalize events.
• Parse events.
• Validate events.
• Diff (if enabled).
• Explain (if enabled).
• Replay (if enabled).
• Decide (final decision metadata).

Each record includes:

• Boundary name.
• Pipeline name.
• Timestamp.
• Stage.
• Events or analysis output.

Telemetry then sends these records to a sink — a function you provide.

This could be:

• A logger
• A database writer
• A metrics collector
• A message queue
• A file writer
• A monitoring system

Telemetry doesn’t care. It just emits structured data.

When Telemetry Runs

Telemetry is optional and lazy. It only runs if:

• The policy enables telemetry analysis
• You call it using withTelemetry().

Example:

await jane.value(input)
  .telemetry()
  .withTelemetry()

If telemetry is disabled, Jane doesn’t compute or emit anything. This keeps the pipeline fast by default.

What Telemetry Never Does

Telemetry is intentionally limited. It does not:

• Validate.
• Parse.
• Normalize.
• Scan.
• Mutate values.
• Affect the pipeline decision.
• Change event severity.
• Rewrite event codes.
• Slow down the pipeline.
• Throw errors.

Telemetry is purely observational. It emits — it never influences.

How Telemetry Works

Telemetry receives the final JaneResult and extracts:

• Stage‑specific event group:
• scanEvents
• normalizeEvents
• parseEvents
• validateEvents
• Analysis outputs:
• diff
• explain
• replay
• Decision metadata
• Decision code
• Mode
• Event count
• Context
• Boundary name
• Pipeline name
• Timestamp

Each of these becomes a structured record. Telemetry then calls your sink with the full list.

Example Telemetry Output

Imagine a pipeline that:

• trims a string
• parses it as a number
• validates it
• rejects it

Telemetry might emit:

[
    {
        stage: "normalize",
        events: [...],
        timestamp: "...",
        boundary: "UserInput",
        pipeline: "age"
    },
    {
        stage: "parse",
        events: [...],
        timestamp: "...",
        boundary: "UserInput",
        pipeline: "age"
    },
    {
        stage: "validate",
        events: [...],
        timestamp: "...",
        boundary: "UserInput",
        pipeline: "age"
    },
    {
        stage: "decide",
        decision: "reject",
        mode: "moderate",
        eventCount: 3,
        timestamp: "...",
        boundary: "UserInput",
        pipeline: "age"
    }
]

This is perfect for logs, dashboards, or audit trails.

Why Telemetry Matters

Telemetry is the layer that makes Jane observable:

• Compliance: You can see exactly what happened in each pipeline.
• Debugging: You can store structured records for audits.
• Monitoring: You can trace issues across boundaries and pipelines.
• Analytics: You can build dashboards around event counts, decision rates, and more.

You can measure how often certain issues occur.