Add use cases to README and expand Prometheus metrics

[jamengual]

Summary

• Add Use Cases section to README — Explains core functionality with 6 real-world scenarios (domain migrations, SEO preservation, vanity URLs, API deprecation, bot mitigation, multi-team config at scale) so visitors immediately understand what the-redirector does
• Expand Prometheus metrics coverage across 4 stages — Adds build info, uptime, config metadata, rate limiter observability, standard Go/process collectors, and full syncer instrumentation
• Add Prometheus usage guide to README — Scrape config examples, key metrics to watch, and example Grafana/PromQL alerts

Details

New metrics (redirector)

Metric	Type	Description
redirector_build_info	Gauge	Version/commit/go_version/build_time as labels (set to 1)
redirector_uptime_seconds	Gauge	Seconds since server started
redirector_config_info	Gauge	Current config version/hash/source as labels
redirector_rate_limited_total	Counter	Rate-limited requests by scope (global, per_ip, path)
go_*	Various	Standard Go runtime metrics (GC, memstats, etc.)
process_*	Various	Standard process metrics (CPU, FDs, resident memory)

New metrics (redirector-sync)

Metric	Type	Description
redirector_sync_sync_total	Counter	Sync operations by status
redirector_sync_sync_duration_seconds	Histogram	Sync operation duration
redirector_sync_last_sync_timestamp_seconds	Gauge	Last sync attempt time
redirector_sync_last_sync_success	Gauge	Whether last sync succeeded (1/0)
redirector_sync_fetch_total	Counter	Source fetch operations by source/status
redirector_sync_fetch_duration_seconds	Histogram	Source fetch duration
redirector_sync_push_total	Counter	Config push operations by target/status
redirector_sync_push_duration_seconds	Histogram	Config push duration
redirector_sync_rules_fetched	Gauge	Rules from last successful fetch
redirector_sync_lint_errors_total	Counter	Lint errors during sync by source

Design decisions

• Rate limiter uses a callback pattern (OnLimitedFunc) to stay decoupled from the metrics package — dependency injection, not a direct import
• Build info uses functional options (server.WithBuildInfo(...)) to avoid breaking the existing server.New() API
• Syncer metrics reuse the existing webhook HTTP mux — /metrics is added alongside /health and /status, no new listener required
• Standard Go/process collectors are registered via collectors.NewGoCollector() and collectors.NewProcessCollector() for full runtime visibility

Files changed

File	Change
README.md	Added Use Cases section + Prometheus usage guide
docs/MANAGEMENT_API.md	Updated metrics reference table with new metrics + syncer metrics section
internal/metrics/metrics.go	Added BuildInfo, uptime, config_info, rate_limited_total; standard collectors
internal/metrics/syncer_metrics.go	New file — syncer-specific Prometheus metrics
internal/metrics/metrics_test.go	7 new tests covering all new metric types
internal/metrics/syncer_metrics_test.go	New file — 5 tests for syncer metrics
internal/ratelimit/ratelimit.go	Added OnLimitedFunc callback, instrumented Allow()
internal/server/server.go	Added WithBuildInfo option, wired config_info + rate limiter callback
cmd/redirector/main.go	Pass build info to server
cmd/redirector-sync/main.go	Create metrics registry, instrument SyncOnce/push, add /metrics endpoint

Test plan

• All 19 new metrics tests pass (go test ./internal/metrics/ -v)
• Full test suite passes (go test ./... — 15 packages, 0 failures)
• go vet ./... clean
• go build ./... compiles without errors
• Manual verification: start redirector, curl localhost:8081/metrics shows new metrics
• Manual verification: start redirector-sync with webhook enabled, curl localhost:9090/metrics shows syncer metrics

🤖 Generated with Claude Code

[github-actions]

📊 Go Benchmark Results

Summary

Metric	Status
Benchmarks compared	42
Regressions (>10% slower)	0
Improvements	2

✅ No significant performance regressions detected.

📊 Full benchstat output

goos: linux
goarch: amd64
pkg: github.com/jamengual/the-redirector/internal/router
cpu: AMD EPYC 7763 64-Core Processor                
                            │ benchmark-results/old.txt │     benchmark-results/new.txt      │
                            │          sec/op           │    sec/op     vs base              │
Router_IsAllowedHost-4                     55.54n ± ∞ ¹   55.23n ± ∞ ¹       ~ (p=1.000 n=5)
Router_ExactMatch-4                        15.08n ± ∞ ¹   15.08n ± ∞ ¹       ~ (p=0.810 n=5)
Router_PrefixMatch-4                       471.6n ± ∞ ¹   472.9n ± ∞ ¹       ~ (p=0.151 n=5)
Router_RegexMatch-4                        189.2n ± ∞ ¹   192.3n ± ∞ ¹  +1.64% (p=0.008 n=5)
Router_GlobMatch-4                         180.9n ± ∞ ¹   181.6n ± ∞ ¹       ~ (p=0.056 n=5)
Router_GlobDeepPath-4                      269.5n ± ∞ ¹   270.6n ± ∞ ¹       ~ (p=0.222 n=5)
Router_MixedRules-4                        161.9n ± ∞ ¹   162.1n ± ∞ ¹       ~ (p=0.270 n=5)
Router_LargeRuleSet-4                      65.09µ ± ∞ ¹   64.81µ ± ∞ ¹       ~ (p=0.421 n=5)
Router_NoMatch-4                           68.38n ± ∞ ¹   68.31n ± ∞ ¹       ~ (p=0.246 n=5)
Router_HostMatch-4                         37.72n ± ∞ ¹   37.16n ± ∞ ¹       ~ (p=0.175 n=5)
Router_NewRouter-4                         172.6µ ± ∞ ¹   182.5µ ± ∞ ¹  +5.72% (p=0.008 n=5)
Router_NewRouterWithRegex-4                4.470µ ± ∞ ¹   5.116µ ± ∞ ¹       ~ (p=0.095 n=5)
Router_ExactMatch_Allocs-4                 12.21n ± ∞ ¹   12.18n ± ∞ ¹       ~ (p=0.056 n=5)
Router_RegexMatch_Allocs-4                 190.6n ± ∞ ¹   191.4n ± ∞ ¹       ~ (p=0.206 n=5)
geomean                                    329.5n         334.1n        +1.40%
¹ need >= 6 samples for confidence interval at level 0.95

                            │ benchmark-results/old.txt │       benchmark-results/new.txt       │
                            │           B/op            │     B/op       vs base                │
Router_IsAllowedHost-4                      32.00 ± ∞ ¹     32.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_ExactMatch-4                         0.000 ± ∞ ¹     0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_PrefixMatch-4                        0.000 ± ∞ ¹     0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_RegexMatch-4                         32.00 ± ∞ ¹     32.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_GlobMatch-4                          16.00 ± ∞ ¹     16.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_GlobDeepPath-4                       16.00 ± ∞ ¹     16.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_MixedRules-4                         9.000 ± ∞ ¹     9.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_LargeRuleSet-4                       4.000 ± ∞ ¹     4.000 ± ∞ ¹       ~ (p=0.762 n=5)
Router_NoMatch-4                            0.000 ± ∞ ¹     0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_HostMatch-4                          0.000 ± ∞ ¹     0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NewRouter-4                        290.8Ki ± ∞ ¹   290.8Ki ± ∞ ¹  -0.00% (p=0.008 n=5)
Router_NewRouterWithRegex-4               20.55Ki ± ∞ ¹   20.55Ki ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_ExactMatch_Allocs-4                  0.000 ± ∞ ¹     0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_RegexMatch_Allocs-4                  32.00 ± ∞ ¹     32.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
geomean                                               ³                  -0.00%               ³
¹ need >= 6 samples for confidence interval at level 0.95
² all samples are equal
³ summaries must be >0 to compute geomean

                            │ benchmark-results/old.txt │      benchmark-results/new.txt      │
                            │         allocs/op         │  allocs/op   vs base                │
Router_IsAllowedHost-4                      1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_ExactMatch-4                         0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_PrefixMatch-4                        0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_RegexMatch-4                         1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_GlobMatch-4                          1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_GlobDeepPath-4                       1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_MixedRules-4                         0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_LargeRuleSet-4                       0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NoMatch-4                            0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_HostMatch-4                          0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NewRouter-4                          28.00 ± ∞ ¹   28.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NewRouterWithRegex-4                 15.00 ± ∞ ¹   15.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_ExactMatch_Allocs-4                  0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_RegexMatch_Allocs-4                  1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
geomean                                               ³                +0.00%               ³
¹ need >= 6 samples for confidence interval at level 0.95
² all samples are equal
³ summaries must be >0 to compute geomean

[github-actions]

📊 Go Benchmark Results

Summary

Metric	Status
Benchmarks compared	42
Regressions (>10% slower)	0
Improvements	2

✅ No significant performance regressions detected.

📊 Full benchstat output

goos: linux
goarch: amd64
pkg: github.com/jamengual/the-redirector/internal/router
cpu: AMD EPYC 7763 64-Core Processor                
                            │ benchmark-results/old.txt │     benchmark-results/new.txt      │
                            │          sec/op           │    sec/op     vs base              │
Router_IsAllowedHost-4                     54.55n ± ∞ ¹   56.70n ± ∞ ¹  +3.94% (p=0.008 n=5)
Router_ExactMatch-4                        15.10n ± ∞ ¹   15.11n ± ∞ ¹       ~ (p=0.730 n=5)
Router_PrefixMatch-4                       471.5n ± ∞ ¹   471.9n ± ∞ ¹       ~ (p=0.135 n=5)
Router_RegexMatch-4                        189.1n ± ∞ ¹   188.9n ± ∞ ¹       ~ (p=0.175 n=5)
Router_GlobMatch-4                         180.5n ± ∞ ¹   180.9n ± ∞ ¹       ~ (p=0.254 n=5)
Router_GlobDeepPath-4                      268.7n ± ∞ ¹   268.1n ± ∞ ¹       ~ (p=0.151 n=5)
Router_MixedRules-4                        161.2n ± ∞ ¹   162.7n ± ∞ ¹       ~ (p=0.063 n=5)
Router_LargeRuleSet-4                      73.55µ ± ∞ ¹   73.94µ ± ∞ ¹       ~ (p=0.310 n=5)
Router_NoMatch-4                           68.40n ± ∞ ¹   68.39n ± ∞ ¹       ~ (p=0.984 n=5)
Router_HostMatch-4                         37.15n ± ∞ ¹   37.16n ± ∞ ¹       ~ (p=1.000 n=5)
Router_NewRouter-4                         169.9µ ± ∞ ¹   171.4µ ± ∞ ¹  +0.89% (p=0.008 n=5)
Router_NewRouterWithRegex-4                4.361µ ± ∞ ¹   4.358µ ± ∞ ¹       ~ (p=1.000 n=5)
Router_ExactMatch_Allocs-4                 12.16n ± ∞ ¹   12.17n ± ∞ ¹       ~ (p=0.762 n=5)
Router_RegexMatch_Allocs-4                 189.3n ± ∞ ¹   189.5n ± ∞ ¹       ~ (p=0.563 n=5)
geomean                                    330.2n         331.7n        +0.46%
¹ need >= 6 samples for confidence interval at level 0.95

                            │ benchmark-results/old.txt │       benchmark-results/new.txt        │
                            │           B/op            │     B/op       vs base                 │
Router_IsAllowedHost-4                      32.00 ± ∞ ¹     32.00 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_ExactMatch-4                         0.000 ± ∞ ¹     0.000 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_PrefixMatch-4                        0.000 ± ∞ ¹     0.000 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_RegexMatch-4                         32.00 ± ∞ ¹     32.00 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_GlobMatch-4                          16.00 ± ∞ ¹     16.00 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_GlobDeepPath-4                       16.00 ± ∞ ¹     16.00 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_MixedRules-4                         9.000 ± ∞ ¹     9.000 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_LargeRuleSet-4                       4.000 ± ∞ ¹     2.000 ± ∞ ¹  -50.00% (p=0.048 n=5)
Router_NoMatch-4                            0.000 ± ∞ ¹     0.000 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_HostMatch-4                          0.000 ± ∞ ¹     0.000 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_NewRouter-4                        290.8Ki ± ∞ ¹   290.8Ki ± ∞ ¹        ~ (p=1.000 n=5)
Router_NewRouterWithRegex-4               20.55Ki ± ∞ ¹   20.55Ki ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_ExactMatch_Allocs-4                  0.000 ± ∞ ¹     0.000 ± ∞ ¹        ~ (p=1.000 n=5) ²
Router_RegexMatch_Allocs-4                  32.00 ± ∞ ¹     32.00 ± ∞ ¹        ~ (p=1.000 n=5) ²
geomean                                               ³                   -4.83%               ³
¹ need >= 6 samples for confidence interval at level 0.95
² all samples are equal
³ summaries must be >0 to compute geomean

                            │ benchmark-results/old.txt │      benchmark-results/new.txt      │
                            │         allocs/op         │  allocs/op   vs base                │
Router_IsAllowedHost-4                      1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_ExactMatch-4                         0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_PrefixMatch-4                        0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_RegexMatch-4                         1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_GlobMatch-4                          1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_GlobDeepPath-4                       1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_MixedRules-4                         0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_LargeRuleSet-4                       0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NoMatch-4                            0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_HostMatch-4                          0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NewRouter-4                          28.00 ± ∞ ¹   28.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_NewRouterWithRegex-4                 15.00 ± ∞ ¹   15.00 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_ExactMatch_Allocs-4                  0.000 ± ∞ ¹   0.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
Router_RegexMatch_Allocs-4                  1.000 ± ∞ ¹   1.000 ± ∞ ¹       ~ (p=1.000 n=5) ²
geomean                                               ³                +0.00%               ³
¹ need >= 6 samples for confidence interval at level 0.95
² all samples are equal
³ summaries must be >0 to compute geomean