Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat(scripts/metricsdocgen): support merging static and generated metrics files - #21464

Merged
ssncferreira merged 4 commits into
mainfrom
ssncferreira/metricsdocgen-merge-metrics-files
Feb 13, 2026
Merged

feat(scripts/metricsdocgen): support merging static and generated metrics files#21464
ssncferreira merged 4 commits into
mainfrom
ssncferreira/metricsdocgen-merge-metrics-files

Conversation

@ssncferreira

@ssncferreira ssncferreira commented Jan 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Description

This PR refactors scripts/metricsdocgen/main.go to support merging static and generated metrics files for documentation generation.

The static metrics file remains necessary for metrics not defined in the coder codebase (go_*, process_*, promhttp_*, coder_aibridged_*), as well as edge cases the scanner cannot handle (e.g., such as metrics with runtime-determined labels or function-local variable references for fields, ...). Handling these edge cases in the scanner would make it significantly more complex, so we keep this hybrid approach to accommodate them. This means that in such cases, developers need to update the metrics file directly, meaning there is still a risk of out-of-date information in the documentation. However, this solution should already encompass most cases.

Static metrics take priority over generated metrics when both files contain the same metric name, allowing manual overrides without modifying the scanner. Some of these edge cases could be easily fixed by updating the codebase to use one of the supported patterns.

Changes

  • Update scripts/metricsdocgen/main.go to read from two separate metrics files:
    • metrics: static, manually maintained metrics (e.g., go_*, process_*, promhttp_*, coder_aibridged_*)
    • generated_metrics: auto-generated by the AST scanner
  • Update metrics file to contain only static and edge-case metrics
  • Skip metrics with empty HELP descriptions in the scanner
  • Update generated_metrics to reflect skipped metrics
  • Update docs/admin/integrations/prometheus.md with merged metrics

Related to: #13223

Disclosure: This PR was mainly developed with Claude Sonnet 4, with iterative review and refinement by @ssncferreira

This was referenced Jan 8, 2026
Merged
Merged
Merged
@ssncferreira Graphite App

ssncferreira commented Jan 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

This stack of pull requests is managed by Graphite. Learn more about stacking.

This was referenced Jan 8, 2026
Merged
Merged
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from 290834d to c5a36c6 Compare January 8, 2026 21:22
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch 2 times, most recently from 403a3c5 to 65a7c50 Compare January 9, 2026 08:51
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from c5a36c6 to 0a2e6a5 Compare January 9, 2026 08:51
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from 65a7c50 to c64eacf Compare January 9, 2026 08:52
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from 0a2e6a5 to 0b325ff Compare January 9, 2026 08:52
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from c64eacf to debcf77 Compare January 9, 2026 09:29
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch 2 times, most recently from 3ee81f5 to d39d62e Compare January 9, 2026 09:42
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from debcf77 to dac0195 Compare January 9, 2026 09:42
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from d39d62e to 316234e Compare January 9, 2026 09:47
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch 2 times, most recently from b53a4eb to 556e481 Compare January 9, 2026 10:04
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch 2 times, most recently from 07b917e to b43e7ff Compare January 9, 2026 10:37
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from 556e481 to 7f37f96 Compare January 9, 2026 10:37
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from b43e7ff to fbec171 Compare January 9, 2026 10:38
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch 2 times, most recently from 519ac0a to f251035 Compare January 9, 2026 10:39
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from fbec171 to ad22659 Compare January 9, 2026 10:39
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from f251035 to da49da0 Compare January 9, 2026 10:40
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch 2 times, most recently from d5993fc to 669ef40 Compare January 9, 2026 10:41
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch 2 times, most recently from 1fba71b to b5fdd68 Compare February 12, 2026 17:23
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch 2 times, most recently from 23d403e to 10d83e9 Compare February 12, 2026 17:54
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch 2 times, most recently from 16db381 to f4acd97 Compare February 12, 2026 18:33
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from 10d83e9 to 0c10e4e Compare February 12, 2026 18:33
@coderagents

coderagents Bot commented Feb 12, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

This PR refactors the metrics documentation generator to support merging static and generated metrics files. The following documentation updates are needed:

New Documentation Needed

  • docs/about/contributing/backend.md - Add section explaining the dual-file metrics system

    • Document the split between scripts/metricsdocgen/metrics (static) and scripts/metricsdocgen/generated_metrics (auto-generated)
    • Explain when developers should add metrics to the static file vs letting the scanner generate them
    • Describe edge cases that require manual static entries (runtime-determined labels, function-local variable references)
    • Note that static metrics take priority over generated metrics for manual overrides

  • Makefile - Update the docs/admin/integrations/prometheus.md rule

    • Add scripts/metricsdocgen/generated_metrics as a dependency
    • Consider adding the scanner as a prerequisite build step if needed

Context

The tool now reads from two files:

  • Static metrics (scripts/metricsdocgen/metrics): Manually maintained for external metrics (go_, process_, promhttp_, coder_aibridged_) and edge cases the scanner can't handle
  • Generated metrics (scripts/metricsdocgen/generated_metrics): Auto-generated by AST scanner from coder codebase

Without documentation, developers won't know:

  • Which file to update when adding new metrics
  • How the merge/priority system works
  • What edge cases require manual entries
  • How to run the generation workflow

Automated review via Coder Tasks

@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from f4acd97 to 7e10dcf Compare February 12, 2026 18:41
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch 2 times, most recently from d9d6977 to ca4d6a7 Compare February 12, 2026 18:43
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from 7e10dcf to 65028be Compare February 12, 2026 18:43
@coderagents

coderagents Bot commented Feb 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Documentation Check

This PR refactors the metrics documentation generator to support merging static and generated metrics files. The documentation needs identified in the previous review are being addressed in the upstack PR.

Updates Deferred to Upstack PR #21465

Recent Updates in This PR

  • ✅ Scanner now skips metrics without HELP descriptions (commit: 90fb69d)
  • ✅ Documentation generated with the merged metrics (auto-generated)
  • ✅ Scanner now supports skipPaths to exclude specific files (commit: 75e1683)
    • Adds ability to skip files like enterprise/aibridgeproxyd/metrics.go that use WrapRegistererWithPrefix
    • Includes TODO for future enhancement to resolve these automatically

Optional Enhancement

  • Consider documenting the skipPaths feature in upstack PR's scripts/metricsdocgen/README.md
    • Explain when developers need to add files to the skip list
    • Note that skipped file metrics must be maintained in the static metrics file
    • Currently documented only via inline code comments and TODO

This is optional since the code includes clear inline comments explaining the feature.

No Action Required

The PR correctly defers Makefile integration and developer documentation to upstack PR #21465. The core refactoring is complete, and the skipPaths feature added in commit 75e1683 is adequately documented in code comments for developers working directly with the scanner.

Automated review via Coder Tasks

@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch 5 times, most recently from eb7475b to ef089f3 Compare February 13, 2026 10:20
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-ast-scanner-promauto branch from b35a400 to c7d424c Compare February 13, 2026 10:20
@ssncferreira Graphite App

ssncferreira commented Feb 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Merge activity

  • Feb 13, 10:48 AM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Feb 13, 11:26 AM UTC: Graphite rebased this pull request as part of a merge.
  • Feb 13, 11:37 AM UTC: Graphite couldn't merge this PR because it was not satisfying all requirements (Failed CI: 'required', 'test-go-pg (windows-2022)').
  • Feb 13, 12:19 PM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Feb 13, 12:19 PM UTC: @ssncferreira merged this pull request with Graphite.

@ssncferreira
ssncferreira changed the base branch from ssncferreira/metricsdocgen-ast-scanner-promauto to graphite-base/21464 February 13, 2026 11:14
@ssncferreira
ssncferreira changed the base branch from graphite-base/21464 to main February 13, 2026 11:24
@ssncferreira
ssncferreira force-pushed the ssncferreira/metricsdocgen-merge-metrics-files branch from 7211224 to 7fdcd5a Compare February 13, 2026 11:25
@ssncferreira
ssncferreira merged commit df84cea into main Feb 13, 2026
55 of 57 checks passed
@ssncferreira
ssncferreira deleted the ssncferreira/metricsdocgen-merge-metrics-files branch February 13, 2026 12:19
@github-actions github-actions Bot locked and limited conversation to collaborators Feb 13, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@mtojek mtojek mtojek approved these changes

Assignees

@ssncferreira ssncferreira

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ssncferreira @mtojek