[RUN-2904] Missing documentation on metrics#1809
Merged
Merged
Conversation
Jesus-Osuna-M
force-pushed
the
docs/run-2904-metrics-field-reference
branch
from
b518772 to
2d49f95
Compare
Jesus-Osuna-M
force-pushed
the
docs/run-2904-metrics-field-reference
branch
from
2d49f95 to
0e2bc3b
Compare
…description - Document the `histograms` top-level key (previously undocumented despite always being present in the response) - Replace hardcoded `seconds` unit in Timer duration fields with `see duration_units`; actual instances return `nanoseconds`, not `seconds` - Update Timer intro to mention both `"seconds"` and `"nanoseconds"` as possible values for `duration_units` - Merge Duration/Rate subtables into a single Timer table for clarity; `duration_units` and `rate_units` are metadata for the full timer, not exclusively rate fields - Fix `mean_rate` description in Meter: replace "it decays toward 0 as the server runs longer without new events" with the more precise "as uptime increases without proportional new events, this value decreases toward 0" - Update intro sentence to reflect five top-level keys (was four) Co-authored-by: Cursor <cursoragent@cursor.com>
Replace `> **Tip:**` blockquote and bare ::: tip blocks (missing blank lines) with the standard VitePress container syntax used throughout the file. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “Metric Types Reference” section to the Metrics API documentation to explain the fields returned for each Dropwizard metrics type, helping readers interpret gauges/counters/meters/timers (and histograms) in the /metrics/metrics response.
Changes:
- Introduces a Metric Types Reference section with per-type field tables (Gauge, Counter, Histogram, Meter, Timer).
- Adds a performance-analysis tip explaining how to interpret percentiles vs mean, and EWMA rates vs mean rate.
|
|
||
| ### Metric Types Reference | ||
|
|
||
| Rundeck exposes metrics via [Dropwizard Metrics](https://metrics.dropwizard.io/). The response from `GET /api/V/metrics/metrics` contains five top-level keys — `gauges`, `counters`, `histograms`, `meters`, and `timers` — each holding a map of named metrics. The following tables describe every field for each metric type. |
Comment on lines
+1373
to
+1385
| | Field | Type | Unit | Description | | ||
| |----------|---------|------------------------|---------------------------------------------------------------------------------------------| | ||
| | `count` | integer | samples | Total number of values recorded since the server started. | | ||
| | `min` | number | see `duration_units` | Minimum recorded value. | | ||
| | `max` | number | see `duration_units` | Maximum recorded value. | | ||
| | `mean` | number | see `duration_units` | Arithmetic mean of all recorded values. | | ||
| | `stddev` | number | see `duration_units` | Standard deviation of recorded values. | | ||
| | `p50` | number | see `duration_units` | 50th percentile (median): 50% of values were at or below this. | | ||
| | `p75` | number | see `duration_units` | 75th percentile: 75% of values were at or below this. | | ||
| | `p95` | number | see `duration_units` | 95th percentile: 95% of values were at or below this. | | ||
| | `p98` | number | see `duration_units` | 98th percentile: 98% of values were at or below this. | | ||
| | `p99` | number | see `duration_units` | 99th percentile: 99% of values were at or below this. | | ||
| | `p999` | number | see `duration_units` | 99.9th percentile: 99.9% of values were at or below this. | |
- Clarify intro sentence: response has a top-level `version` string plus five metric map keys, not just five top-level keys - Fix Histogram unit column: replace "see \`duration_units\`" with "—" since \`duration_units\` is a Timer-only field and histograms do not expose a units key in the API response Co-authored-by: Cursor <cursoragent@cursor.com>
fdevans
approved these changes
May 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Jira ticket
RUN-2904
Description
Adds a Metric Types Reference section to the API docs immediately after the
GET /api/V/metrics/metricsJSON example. Explains every field for all four Dropwizard Metrics types (Gauge, Counter, Meter, Timer), including percentile semantics (p50–p999), the difference between EWMA rates (m1/m5/m15_rate) and the historical mean_rate, and a performance analysis tip.Testing instructions
count,min,max,mean,stddev,p50–p999,m1_rate,m5_rate,m15_rate,mean_rate,duration_units,rate_units.