67 lines
4.7 KiB
Markdown
67 lines
4.7 KiB
Markdown
# Development observability
|
|
|
|
Run `npm run debug:collector` and verify `http://127.0.0.1:4318/health`.
|
|
Start the management service with `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318`.
|
|
Enable browser diagnostics through a normally published signed policy: `enabled: true`,
|
|
`mode: debug`, endpoint above, and debug sampling of 1 for controlled reproduction.
|
|
Administrators can disable diagnostics centrally; mandatory review still applies.
|
|
|
|
Reproduce the feature, inspect `/api/summary` for slow stages and inspect
|
|
`/api/trace/<traceId>` for parent/child timings. Browser management requests carry
|
|
W3C trace context into backend HTTP spans. AI inspection, provider requests,
|
|
response reading/decoding and library organization have separate backend stages.
|
|
Use the native tabs smoke fixture to verify real Electron exports and correlation.
|
|
|
|
The receiver listens only on numeric loopback, rejects foreign origins and hosts,
|
|
and stores encrypted batches under ignored `data/observability`. AES-256-GCM keys
|
|
are protected by Windows DPAPI. The summary contains bounded timing metadata;
|
|
it is a local developer tool accessible to the same machine's users, not a
|
|
production SIEM or an authenticated remote service. Recent trace lookup is held
|
|
in memory and resets on restart. Each encrypted segment has a 50 MiB development
|
|
limit. The collector retains an active segment and at most two generated retired
|
|
segments, plus a separately pinned previous archive. Inspect `activeBytes`,
|
|
`legacyBytes`, `retiredBytes` and `rejectedWrites`; investigate collection failures
|
|
instead of assuming exports succeeded. See [retention](development-collector-retention.md).
|
|
|
|
Ordinary traces never contain passwords, tokens, prompt bodies or document text.
|
|
Security audit and restricted encrypted forensic evidence are separate pipelines.
|
|
Debug mode now exports eight internal inspector stages: inspect, parse, OCR, OCR model initialization, YARA, macro extraction, semantic inference and semantic model initialization. The worker sends bounded in-memory timing records through its existing private pipe; it gains no network capability. Browser/backend import creates child spans with original timestamps under the active request trace. Invalid/off/stale metadata is discarded without changing the verdict. These named stages do not trace every function or native-model kernel. Add named stages when investigating further gaps, without weakening DLP or retrying protected actions.
|
|
|
|
The repository's AGENTS.md requires this workflow for subsequent development.
|
|
|
|
## Coverage verification, 2026-10-13
|
|
|
|
The live collector reported 3,147 spans, 2,482 log records and 36 metric records,
|
|
with zero rejected storage writes. Twenty focused diagnostics, OTLP export,
|
|
inspector timing, collector validation/retention and failure-path tests passed.
|
|
These counts are a process snapshot, not a completeness claim.
|
|
|
|
Agent RPC instrumentation now wraps each request in `agent.request`; decrypt,
|
|
authorization, audit, dispatch, projection and encryption run beneath that parent.
|
|
The browser diagnostic operation allowlist accepts the new name. A real protected
|
|
RPC test verifies asynchronous parent/child nesting without recording arguments
|
|
or response content. The combined transport/diagnostics suite passes 38 tests;
|
|
A subsequent actual Electron run verifies exported parent/child phases linked to an attributable durable agent event; Windows packaged verification remains a separate gate.
|
|
|
|
The actual native agent audit proof links `browser.agent` to
|
|
`browser.management` and `server.request` under trace
|
|
`f8e35fd442e718995d9274c646fb8e08`. The native upload helper-failure proof links a
|
|
recording `browser.upload.fault` span, its lease parent, two logs and the durable
|
|
audit event under trace `e6d26d4edf738a7b4f6f562ab2112f5b`. Older traces may be in
|
|
the protected pinned archive rather than the current in-memory index.
|
|
|
|
A sampled slow `browser.parser` scan lasted 1,049 ms but contained only the outer
|
|
span in the live index. Do not infer which parser or model stage caused that
|
|
duration from an outer span alone: reproduce with signed debug mode enabled and
|
|
verify the expected inspector children before attributing a performance issue.
|
|
|
|
The current individual native proof links principal `reader-a` to
|
|
trace `3a0c31cbf53d7808e39a91daf2aaa3d7`. Its request took 81.019 ms,
|
|
the two durable audit phases totaled 77.598 ms and adapter dispatch took
|
|
0.313 ms. This single local run points to audit persistence as the dominant
|
|
stage; it is not a throughput benchmark. Preserve pre-execution durable audit
|
|
when investigating latency. Do not optimize by removing an audit gate or retrying
|
|
an action. The proof is in `artifacts/individual-agent-native-proof.json`.
|
|
The final Windows package verifier checks current source and runs both shipped
|
|
legacy and individual DPAPI/PQ clients successfully.
|