Skip to main content

Monitoring and Observability

Design status: This page includes earlier planning assumptions. The current CLI contract and ADR-011 govern the CLI-first agent integration; MCP, SQLite preview handles, and server-side confirmation described below are not shipped.

AttributeValue
ProjectDevWorkWire
Version0.1
StatusDraft

Table of Contents​

1. Monitoring Strategy​

The user is the monitor. Every operation is initiated by a person or their agent, who is present for its outcome. There is no unattended process to watch, no availability to measure, and no on-call rotation.

ConcernApproachRationale
Error trackingNone. Errors are surfaced to the user at the point of useA Sentry DSN in a local CLI would ship users' tracker content and stack traces to a third party without meaningful consent
MetricsNone collected or exportedNothing runs unattended; there is no aggregate to compute
Log aggregationNone. Logs stay on the user's machine, on stderrAggregating them would require exfiltration
Usage analyticsNone, and none plannedUsers of a credential-holding developer tool should be able to verify it makes no unexpected network connections
Release healthCommunity reports, GitHub issues, dependency alertsThe realistic detection channel for open-source software

The one outbound connection DevWorkWire makes is to the configured Jira base URL. No update checks, no phone-home, no crash reporting. This claim should be verifiable by anyone watching the process, and it should be stated in the README — it is a feature.

What this costs, stated honestly: there is no way to know how many users are on a broken version, no aggregate error rates to spot a regression, and no signal that a release is bad until someone reports it. That is the accepted price of not instrumenting users, and it is why the pre-release gates in CI/CD Pipeline carry the weight that post-deploy monitoring would carry elsewhere.

2. Logging Approach​

  • Destination: stderr, always. stdout is the MCP protocol channel — anything else written there corrupts the JSON-RPC stream. This is enforced by a test, not by convention, because a stray print() breaks the server (Interface Design Standards).

  • Format: human-readable by default; --log-format=json for structured output when attaching logs to a bug report. Fields: timestamp, level, message, run_id, version.

  • Levels:

    LevelUse
    ERRORThe operation failed. Always shown
    WARNINGProceeding, but the user should know — drift detected, item skipped, Jira retry
    INFODefault: what is being done and what happened
    DEBUG--verbose: Jira request/response metadata (method, path, status, timing — never headers or bodies), parse and validation detail, timing

  • Verbosity is user-controlled (--quiet / --verbose), defaulting to a level that reports outcomes without narrating internals.

  • Retention is the user's. Nothing is written to a log file unless the user redirects output; DevWorkWire creates no log files of its own to grow unbounded on their disk.

  • Redaction is enforced by a logging filter, not by call-site discipline — see §8.

3. Correlation Instead of Distributed Tracing​

There are no services to trace across: one process, one call stack, one outbound host.

What is needed instead is correlation within a single run, so a user reporting a problem can hand over one identifier that ties everything together:

  • run_id — generated per CLI invocation or per MCP tool call. Logged on every record, returned in every result and error, and stored on commit_run (Database Design).
  • preview_handle — ties a commit back to the plan that authorized it, which is the correlation that matters most when investigating an unexpected write.
  • idempotency_key — ties retries of the same commit together.

Practical goal: a user pastes a run_id and the --verbose output into an issue, and the maintainer can reconstruct what happened without asking follow-up questions. That is the entire observability requirement.

4. What "Good" Looks Like Locally​

These are qualities verified by tests and review, not measured in production:

PropertyWhat it meansHow it is verified
Errors identify the itemA validation failure names the Story and the problem, not "validation failed" (FR-001-02)Tests asserting error message content
Errors identify the fixA config error names the missing field (FR-008-03); a Jira 403 says which permissionTests + review
All problems reported at onceA document with three faults produces three errors, not the first oneTest with a multi-fault document
Commit outcome is unambiguousCommitted / failed / untried are distinct (FR-001-06); result_type distinguishes preview from write (NFR-004-01)Schema tests
Preview is readable at 80 columns(NFR-003-01)Manual review against a representative document
State is signalled by text, not colorErrors and warnings carry text prefixes (NFR-X06)Manual review; non-TTY output check
Retries are visibleA Jira 429 backoff says so rather than appearing as a hangTest with a mocked 429
Failures are never silentNo operation exits 0 having partially failed; exit code 4 exists specifically for partial commitsExit-code tests

5. Failure Surfacing Instead of Alerting​

There is nobody to page and no channel to route to. The equivalent is making the right thing impossible to miss at the moment it happens:

ConditionSurfaced as
Validation failedBlocking error listing every problem; exit 1; no preview generated
Config or credentials invalidBlocking error naming the field; exit 2; before any Jira call
Drift detected on a matched itemWarning in the preview, and an explicit per-item overwrite/skip the user must answer (FR-002-04)
Jira rate limitedWarning during backoff, so a slow run is legible rather than looking hung
Jira permission deniedBlocking error naming the operation and issue; exit 3
Partial commit (fail-fast)Prominent summary of committed / failed / untried, with the retry instruction; exit 4, distinct from success and from total failure
Interrupted prior run detectedCOMMIT_INTERRUPTED with what is known — never a fabricated replay result

Exit code 4 is the closest thing to an alert this system has: "some of your items are now in Jira" is operationally different from "nothing happened", and a script or agent must be able to tell them apart without parsing prose (Interface Design Standards).

6. Performance Monitoring​

No frontend, no backend service, no database server — Core Web Vitals, endpoint latency distributions, connection pool stats, and query performance monitoring are all Not Applicable.

  • --verbose reports timings: parse, validation, per-Jira-call duration, and total run time. Enough for a user to see where a slow run went, and to include it in a report.
  • Latency is dominated by Jira round-trips, not local computation. A commit is N sequential REST calls; parsing is milliseconds (Technology Stack).
  • Retry counts are surfaced, so "Jira is throttling you" is distinguishable from "DevWorkWire is slow" — the distinction that determines whether a user files a bug.
  • NFR-X04 is still TBD. No latency target is committed. If one is set, the measurement point should be local processing time excluding Jira round-trips, since the latter is not something DevWorkWire controls.
  • CI tracks test-suite duration as the only ongoing performance signal, because that is the only environment the project can measure.

7. Observability in the Delivery Workflow​

  • The version is in every log line and in dwire --version. With no telemetry, the version a user reports is the only way to know what code produced a failure — so it must be trivially available.
  • run_id is in every result and error, so an issue report contains a correlatable identifier without the user knowing to ask for one.
  • A bug report template should request: dwire --version, the platform and Python version, the run_id, and --verbose output — with a reminder that output is safe to share because the token is redacted.
  • SECURITY.md and issue reporting must be easy to find. Community reporting is the actual detection channel for a bad release, so friction there is a monitoring gap, not a documentation nicety (Security Architecture).
  • CI is where signals are collected: test results, coverage trend, pip-audit findings, and CodeQL alerts. This is the project's real dashboard.
  • Release checklist includes a manual verification pass against a real Jira project, covering the gap that mocked adapter tests leave (CI/CD Pipeline).

8. Data Privacy and Security in Observability​

This section is short because the strongest privacy control is having no observability pipeline at all — there is no ingestion endpoint, no vendor, and no retention policy to get wrong.

  • Nothing leaves the user's machine. No error reports, no metrics, no analytics.
  • The Jira API token and Authorization header are redacted at every verbosity level, enforced by a logging filter rather than by remembering at each call site. A test asserts the token never appears in captured output at maximum verbosity (NFR-008-01).
  • Raw Jira request and response bodies are never logged, even under --debug. Metadata only: method, path, status, duration.
  • Issue content is logged only where the user needs to see it — a preview line, a validation error naming an item. Not dumped wholesale.
  • DevWorkWire creates no log files. Persisting logs is the user's explicit choice via shell redirection, so no unexpected file accumulates tracker content on their disk.
  • Output is safe to paste into a public issue. This should be true by construction, and the bug report template should say so — otherwise users either over-redact and file useless reports, or under-redact and leak.

9. Cost Management​

Zero, and structurally so. No observability vendor, no ingestion volume, no retention tier, no sampling to tune, no free-tier limit to approach, no spend alert to configure.

The only cost is maintainer attention on GitHub issues and dependency alerts — which is the project's genuinely scarce resource (Phased Roadmap single-developer risk), and the reason the tooling here stays deliberately minimal.

Source References​

Last Updated: 2026-09-01