s1d3sw1ped/steamcache2
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 32 Wiki Activity

metrics: Prometheus/OpenMetrics exposition for /metrics #49

New Issue
Closed
opened 2026-09-07 23:04:16 -05:00 by eva · 1 comment
eva commented 2026-09-07 23:04:16 -05:00
Owner
Copy Link
Copy Source

Problem

/metrics today is Prometheus-ish: plain name value lines and a few {service=…} labels via WriteText, but it is missing # HELP / # TYPE, the standard Prometheus/OpenMetrics Content-Type, and may fail strict scrapers (Prometheus, Grafana Alloy, etc.).

Why it matters

Jerry is standing up lab Prometheus + Grafana to scrape steamcache.lab.rrd/metrics. Custom Grafana panels are fine; the scrape format needs to be clean so dashboards work without brittle parsers.

Goal

Make /metrics OpenMetrics / Prometheus text-format compatible for Prometheus scrape + Grafana dashboards.

Scope

  • Emit proper Prometheus exposition (or OpenMetrics text) for existing metrics: # HELP, # TYPE, correct types (counter/gauge/histogram as applicable), stable metric names, and labels.
  • Set the standard scrape Content-Type (Prometheus text 0.0.4 or OpenMetrics).
  • Keep /lancache-heartbeat as-is for health (do not change that endpoint for this issue).
  • Do not block Jerry's Prometheus/Grafana stack — this is format polish on the app side.

Acceptance

  • A Prometheus (or compatible) scraper can pull /metrics without parse errors.
  • Each exported series has # HELP and # TYPE (or OpenMetrics equivalents).
  • Content-Type matches the chosen exposition format.
  • Existing metric meanings are preserved (rename only if documented in the PR).
  • /lancache-heartbeat unchanged.
  • README or ops note mentions scrape path + format if install/ops docs claim metrics today.

Out of scope

  • Standing up lab Prometheus/Grafana (Jerry).
  • Redesigning which metrics exist (unless a name must change for Prometheus conventions — call that out in the PR).
## Problem `/metrics` today is Prometheus-*ish*: plain `name value` lines and a few `{service=…}` labels via `WriteText`, but it is missing `# HELP` / `# TYPE`, the standard Prometheus/OpenMetrics `Content-Type`, and may fail strict scrapers (Prometheus, Grafana Alloy, etc.). ## Why it matters Jerry is standing up lab Prometheus + Grafana to scrape `steamcache.lab.rrd/metrics`. Custom Grafana panels are fine; the scrape format needs to be clean so dashboards work without brittle parsers. ## Goal Make `/metrics` OpenMetrics / Prometheus text-format compatible for Prometheus scrape + Grafana dashboards. ## Scope - Emit proper Prometheus exposition (or OpenMetrics text) for existing metrics: `# HELP`, `# TYPE`, correct types (counter/gauge/histogram as applicable), stable metric names, and labels. - Set the standard scrape `Content-Type` (Prometheus text 0.0.4 or OpenMetrics). - Keep `/lancache-heartbeat` as-is for health (do not change that endpoint for this issue). - Do not block Jerry's Prometheus/Grafana stack — this is format polish on the app side. ## Acceptance - [ ] A Prometheus (or compatible) scraper can pull `/metrics` without parse errors. - [ ] Each exported series has `# HELP` and `# TYPE` (or OpenMetrics equivalents). - [ ] `Content-Type` matches the chosen exposition format. - [ ] Existing metric meanings are preserved (rename only if documented in the PR). - [ ] `/lancache-heartbeat` unchanged. - [ ] README or ops note mentions scrape path + format if install/ops docs claim metrics today. ## Out of scope - Standing up lab Prometheus/Grafana (Jerry). - Redesigning which metrics exist (unless a name must change for Prometheus conventions — call that out in the PR).
pike was assigned by eva 2026-09-07 23:04:16 -05:00
eva commented 2026-09-07 23:07:54 -05:00
Author
Owner
Copy Link
Copy Source

FYI from lab scrape (Jerry Prom/Grafana live) — do not block on this:

  • Missing # HELP / # TYPE today; Prometheus still scrapes OK.
  • service label collides with Prometheus reserved/exported naming → Prom renames to exported_service. Prefer a non-colliding label (e.g. job/instance elsewhere, or rename our label) when polishing exposition.
  • Counters are cumulative (rate/increase in Grafana, not raw).

Dashboard (lab): http://dockge.lab.rrd:3000/d/steamcache2-lab/steamcache2

FYI from lab scrape (Jerry Prom/Grafana live) — do not block on this: - Missing `# HELP` / `# TYPE` today; Prometheus still scrapes OK. - `service` label collides with Prometheus reserved/exported naming → Prom renames to `exported_service`. Prefer a non-colliding label (e.g. `job`/`instance` elsewhere, or rename our label) when polishing exposition. - Counters are cumulative (rate/increase in Grafana, not raw). Dashboard (lab): http://dockge.lab.rrd:3000/d/steamcache2-lab/steamcache2
eva closed this issue 2026-09-08 14:57:22 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Something is not working
 draft
Draft for review — do not merge without Eva review
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 wontfix
This won't be fixed
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
ash blake eva linus moss pike s1d3sw1ped
No Assignees pike
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: s1d3sw1ped/steamcache2#49
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?