Skip to content

docs(analytics): document transaction-commit-time metric #572

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
kriszyp wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs(analytics): document transaction-commit-time metric #572

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
38b14bb
docs(analytics): document transaction-commit-time metric
kriszyp Jul 7, 2026
3408176
fix(analytics): satisfy prettier table formatting
kriszyp Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions reference/analytics/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,25 @@ Harper automatically tracks the following metrics for all services. Applications
| `bytes-received` | node.database | `replication` | `blob` | bytes | Bytes received for blob replication |
| `replication-latency` | node.database.table | | `ingest` | ms | Time difference from source commit timestamp to local time |

### Storage Metrics

| `metric` | `path` | `method` | `type` | Unit | Description |
| ------------------------- | ------ | -------- | ------ | ---- | ----------------------------------------------------------------- |
| `transaction-commit-time` | | | | ms | Time a write transaction is outstanding (submit → durable commit) |

`transaction-commit-time` is recorded as a distribution (`mean`, `median`, `p90`, `p95`, `p99`,
`p999`, `count`) per write commit. It measures the same interval the storage engine's overload guard
uses: when the oldest outstanding commit exceeds `storage.maxTransactionQueueTime` (default 45s),
Harper rejects new write transactions with `Outstanding write transactions have too long of queue,
please try again later` (HTTP 503).
Comment on lines +181 to +182

@gemini-code-assist gemini-code-assist Bot Jul 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The documented error message contains a grammatical typo: too long of queue should be too long of a queue (or too long a queue). Please verify if the actual database implementation has this typo and correct it there as well, while updating the documentation here to match.

Suggested change
Harper rejects new write transactions with `Outstanding write transactions have too long of queue,
please try again later` (HTTP 503).
Harper rejects new write transactions with `Outstanding write transactions have too long of a queue,
please try again later` (HTTP 503).


Because it is measured on that same clock, it is the leading indicator for that rejection: a rising
`p99`/`p999` means commits are taking longer to drain — from write volume, large transactions, or a
saturated storage volume — and is the signal to shed or throttle write load before commits start
timing out. Unlike an in-flight transaction count, this reflects transaction size and the shared
write path rather than per-thread submission concurrency, so alert on the upper percentiles trending
toward `maxTransactionQueueTime`. Tune the threshold against a baseline for your workload.

@gemini-code-assist gemini-code-assist Bot Jul 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The configuration option storage.maxTransactionQueueTime should be enclosed in backticks for consistency with its earlier mention on line 180 and to maintain proper markdown formatting for configuration parameters.

Suggested change
toward `maxTransactionQueueTime`. Tune the threshold against a baseline for your workload.
toward `storage.maxTransactionQueueTime`. Tune the threshold against a baseline for your workload.


### Resource Usage Metrics

| `metric` | Key attributes | Other | Unit | Description |
Expand Down