26. Platform Observability¶

Platform Observability is a local diagnostics surface for CodeClone development. It explains the cost and shape of CodeClone's own execution. It does not describe repository quality and must never affect analysis truth, gates, baselines, cache compatibility, findings, or edit authorization.

Trust boundary¶

flowchart LR
    A["CLI / MCP / projection worker"] --> B["Operation and span instrumentation"]
    B --> C["Local SQLite store<br/>.codeclone/db/platform_observability.sqlite3"]
    C --> D["CLI JSON / self-contained HTML"]
    C --> E["Bounded MCP diagnostics"]
    D --> F["Human diagnosis"]
    E --> F
    B -. " must not influence " .-> G["Analysis, findings, gates,<br/>baseline, cache, permissions"]

The observer:

• is disabled by default;
• stores data locally only;
• records metadata, counters, durations, bounded payload sizes, and normalized literal-free SQL fingerprints;
• never records prompt or MCP payload bodies;
• exposes telemetry hints, not findings or vulnerabilities;
• remains inert when disabled or when no store exists.

Enabling instrumentation¶

Configuration is environment-only. There is no [tool.codeclone] observability table.

An explicit CODECLONE_OBSERVABILITY_ENABLED=1 is sufficient in CI. CODECLONE_OBSERVABILITY_FORCE never enables observation by itself and is reserved as an explicit CI-gate override.

Configuration fields for retention and row caps are reserved in the internal model but are not automatic pruning guarantees in the current release.

Data model¶

The local schema version is 1.1. A completed operation and its spans are written in one transaction.

An operation records stable identifiers, parent/correlation IDs, surface, operation name, timestamps, duration, status, bounded error classification, session and root digests, request/response sizes, token estimates, and optional process metrics (rss_mb, rss_delta_mb, peak_rss_mb, peak_rss_delta_mb, CPU time, thread count, open file descriptors when codeclone[perf] is installed).

A span records its parent, duration, reason kind, deduplication state, numeric counters, the same optional process metrics, and at most eight normalized SQL fingerprints. SQL literals are removed before persistence.

Engineering Memory and semantic rebuild spans¶

When observability is enabled, codeclone memory … commands record a CLI operation (cli.memory.{command} or cli.memory.semantic.{action}) and nested product spans:

The rebuild span carries counters such as indexed, embedded, skipped_unchanged, deleted, embedding_dimensions, embedding_batch_size, and lane_{source} tallies.

Semantic rebuild reasons are classified as:

• content_changed — rows were embedded and/or stale ids pruned
• manual_rebuild — full reconcile but index already current (hash-skip only)
• schema_version_changed
• model_changed
• first_index
• unknown

Memory pipeline cost rows include memory.* product spans regardless of whether they ran under a memory, cli, or mcp operation surface.

CLI projection¶

codeclone observability trace --root .
codeclone observability trace --root . --last 50 --html /tmp/codeclone-observer.html
codeclone observability trace --root . --operation OPERATION_ID --json /tmp/trace.json
codeclone observability trace --root . --correlation CORRELATION_ID

Without --json or --html, the command writes JSON to stdout. A missing store is an informational empty state and exits successfully.

The HTML cockpit is self-contained and includes operation chains, a span waterfall, pipeline and Engineering Memory costs, MCP tool aggregates, database costs, normalized SQL fingerprints, agent context, and costly no-op signals. It has no external assets or JavaScript dependency.

MCP projection¶

query_platform_observability returns one bounded section per call:

• summary
• slow_operations
• memory_pipeline_cost
• db_cost
• agent_context
• mcp_tool_matrix
• correlated_chains
• costly_noops
• pipeline

detail_level=compact returns at most five rows. normal honors limit, clamped to 1..50; full currently downgrades to normal. window accepts latest or a correlation ID. operation_id and span_id are reserved and reported as ignored parameters.

The response explicitly declares a CodeClone-development audience and states that it is not user-facing quality evidence. See MCP determinism and tests for the bounded-projection contract.

Privacy and lifecycle¶

The SQLite database is optional local diagnostic state. It is outside the canonical report, baseline, and analysis cache contracts. Deleting it only removes diagnostics; it does not alter analysis results.

There is no network exporter. Automatic retention pruning is not currently enforced, so operators who enable persistence own local database lifecycle. See Security model and Plans and retention.