Observability Guide

This guide defines the minimum observability model SQLQueryHelperjs should expose once tracing for planReflect(...) and reflect(...) is implemented.

Why Observability Matters

Teams can already inspect plans and schema history, but that is not the same as operational observability.

Observability should answer:

• what the reflector decided
• why it decided that
• how long each phase took
• what execution boundary was crossed
• which engine-specific path was used

Without that, schema automation is harder to trust in shared environments.

Minimum Event Model

The first implementation should stay small and structured.

Recommended event families:

• plan.start
• plan.table
• plan.complete
• reflect.start
• reflect.table
• reflect.statement
• reflect.complete
• reflect.error

The goal is not verbose logging by default. The goal is a stable event schema that higher-level tooling can consume.

Recommended Base Event Shape

type ReflectorEventName =
  | "plan.start"
  | "plan.table"
  | "plan.complete"
  | "reflect.start"
  | "reflect.table"
  | "reflect.statement"
  | "reflect.complete"
  | "reflect.error";

interface ReflectorTraceEvent {
  timestamp: string;
  engine: "sqlite" | "postgres" | "mysql";
  event: ReflectorEventName;
  environment?: string;
  table?: string;
  phaseDurationMs?: number;
  details?: Record<string, unknown>;
}
Copy

This shape is intentionally generic so every engine can emit the same envelope first.

Recommended Event Payloads

plan.start

Should include:

• number of requested entities
• environment
• schema or database target when known

plan.table

Should include:

• table name
• computed action such as create, alter, rebuild, noop, or destructive-blocked
• destructive reasons when present
• dependency count
• rename hint count when present

plan.complete

Should include:

• total table count
• action counts
• total duration
• whether destructive approval or change tickets are required

reflect.start

Should include:

• entity count
• whether the run is expected to execute additive or destructive work
• environment and engine context

reflect.table

Should include:

• table name
• action taken
• whether dependency orchestration was used
• whether approvals or policies affected the path
• table-level duration when available

reflect.statement

Should include:

• statement classification such as create-table, alter-table, drop-index, recreate-view
• whether the statement is exact or approximate in relation to plan output
• execution duration when available

The first version does not need to emit every SQL string by default. Classification and duration are the minimum useful layer.

reflect.complete

Should include:

• total duration
• counts by action type
• whether history or audit hooks were active

reflect.error

Should include:

• table if known
• operation phase
• error class or code
• whether execution had already crossed into destructive work

Logging Policy

The runtime should separate structured events from human-readable logs.

• structured events are for automation, dashboards, CI summaries, and audit pipelines
• human-readable logs are for local debugging

Do not force teams to parse console strings if the runtime already knows the event type.

Relationship To Existing History And Audit Features

Schema change history and onSchemaChange are still useful, but they answer a narrower question:

• history says what change happened
• audit hook says a schema change event was emitted
• observability explains the decision flow around planning and execution

That distinction matters when debugging why a rollout was blocked or why a rebuild path was chosen.

First Safe Rollout

The minimum safe first rollout of observability would be:

• one generic event envelope
• plan and reflect lifecycle events
• durations for phase-level events
• table-level action and destructive reason summaries

That is enough to improve operational trust before exposing detailed SQL traces.

Future Extensions

Once the base event model exists, likely next steps are:

• correlation ids across plan and reflect runs
• explicit policy-evaluation events
• structured SQL payloads for debug mode
• benchmark correlation for schema-heavy releases
• exporters for log pipelines or CI summaries

Use semantic-change-detection.md as the design reference for future semantic fields such as semanticCategory, renameHintCount, equivalenceNotes, and uncertaintyReason.