TRUSTWEAVE SDK · 8 SEPTEMBER 2026
Observability and diagnosability improved
Runtime instrumentation and verified diagnostics now replace the earlier reliance on a test-only metric implementation.
What changed
- Runtime ledger metrics. Schema initialization, reservation, reconciliation and health reads now emit bounded counts, cumulative latency histograms and in-flight gauges. Six fixed outcomes distinguish normal rejection, invalid input, SQL failure, unexpected failure and cancellation from success. Identifiers and exception text never become labels.
- Outage-safe export. The metrics snapshot makes no database calls. SQL failure does not disable scraping. Failed health polling removes stale pending/age gauges; a successful-poll timestamp detects a polling job that stops. Unknown legacy ages stay unknown.
- HTTP-to-log correlation. Both status-list routes generate a random request ID, return it in response headers and error bodies, and include it in redacted failure events. Incoming IDs are ignored. Configuration, storage, timeout and internal failures have fixed diagnostic codes.
- Actionable alerts. Nine rules cover SQL errors, backlog, latency, stale/failed health polls, unknown/old pending ages, failed scrapes, disappeared targets and missing instrumentation. Each points to an operator procedure.
- Repeatable checks. CI and release workflows validate real metric exposition with promtool and retain the metrics and correlation artifacts.
Executed evidence
| Affected-module tests | 96 passed; 0 failures, errors or skips (92 intent + 4 status-list server) |
|---|---|
| Concurrency and bounds | 80,000 observations on 8 workers; fixed series count, coherent cumulative buckets and no leaked in-flight work |
| Correlation | 20 concurrent HTTP failures; 20 unique generated IDs; exactly one matching redacted log event each |
| Fault and recovery | Real PostgreSQL stopped; authorization returned 503 while metrics stayed available; failed health gauges cleared and recovered after independent restore |
| Alert rules | 31 assertions passed, including firing/recovery and cancellation/rejection exclusion |
| Prometheus exposition | Fresh runtime scrape passed promtool check metrics |
| Lint and API | Both modules passed; additive diagnostics API; existing one-argument ledger constructor retained |
Source hashes and validation · Final build log · Actual correlation events · Actual metrics · Alert vectors · Rule result
Why this earns 9.0, and what remains for 10
The previous 8.0 score credited guidance, component metrics and three tested alerts. The implementation now instruments actual library operations, preserves diagnostic access during storage failure, verifies response-to-log correlation through a real logging backend, and detects gaps in the monitoring pipeline itself.
The remaining point requires evidence from the intended deployed host: agreed SLO thresholds and dashboards; queue, pool and distributed-trace coverage; configured log retention/access controls; and a notification delivered and resolved through the real Alertmanager/pager route. Instrumentation across other SDK/provider paths also remains broader work. No external notification was sent and no deployment qualification is claimed.
The collector starts no listeners or background threads. Hosts must wire protected metrics export, bounded periodic health polling and their SLF4J backend. The local component exercise uses pre-authorized requests and a quiesced restore; it does not qualify production throughput, PITR or payment-journal authentication.
Reassessment using the unchanged rubric
| Category | Previous | Current |
|---|---|---|
| Security and access control | 9.0 | 9.0 |
| Observability and diagnosability | 8.0 | 9.0 |
| Reliability and scale | 9.0 | 9.0 |
| Configuration and data | 9.0 | 9.0 |
| Deployment and release | 8.5 | 8.5 |
| Testing and documentation | 8.5 | 8.5 |
Only observability was reassessed; other categories are carried forward. 53 / 6 = 8.8333, rounded half-up to 8.8 / 10. This is engineering judgment, not certification. No full-SDK coverage increase is claimed.
Operator handoff
Share one diagnostics collector among ledger instances for the same database. Poll health using a monitoring role and a bounded scheduler; export the cached snapshot on the host's protected metrics route. Use Prometheus rate/increase for process-local counters and check health freshness before interpreting gauges. Do not treat a timeout as confirmed payment non-execution.
Logging and telemetry contract · Wiring and alert runbooks · Scores JSON · Previous payment validation report
SLF4J log capture uses its documented SimpleLogger configuration in tests only. The runtime library does not select the application's backend.