Add on-demand pprof profiling grouped by route

Expose pprof at /debug/pprof via -pprof flag, tag each handler with runtime/pprof route label, add handleRoute helper to avoid repeating patterns, and document UI workflow in README.

1 files changed, 43 insertions, 0 deletions

diff --git a/README.md b/README.md
index d49e761..ea6809f 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ mise run dev-watch
 | `-extract-osm` | Extract mountain passes from a France OSM PBF | `""` |
 | `-backfill` | Recompute and persist all ride computed values | `false` |
 | `-backtest` | Benchmark computed vs stored ride values | `false` |
+| `-pprof` | Expose pprof endpoints at `/debug/pprof` | `false` |
 
 Configuration is stored in `config.yaml`. Start from `config.example.yaml` and set the Strava credentials before launching the server.
 
@@ -106,6 +107,47 @@ mise run build
 
 TypeScript checks can also be run directly with `npm run check`, covering formatting, linting, compilation, type checking, and tests.
 
+## Profiling
+
+Answer "what slows the server" with function-level CPU profiles grouped by route.
+
+```bash
+# Start the server with pprof (exposes http://localhost:8080/debug/pprof/)
+go run . -pprof
+# or: mise run dev -- -pprof
+```
+
+```bash
+# Capture 10s CPU sample and open interactive UI at http://localhost:8081
+go tool pprof -http=:8081 http://localhost:8080/debug/pprof/profile?seconds=10
+```
+
+While it samples (10s), hit the routes you care about:
+
+```bash
+for _ in {1..50}; do curl -s http://localhost:8080/rides/1 >/dev/null; curl -s http://localhost:8080/ >/dev/null; done
+```
+
+In the UI: `VIEW > Flame Graph`, `Top`, `Source` (annotates `ride/ride.go:90` etc.). Each request is tagged with `route` via `runtime/pprof` labels (`GET /`, `GET /rides/{id}`, `GET /analytics`, …), so filter by route:
+
+```bash
+go tool pprof -http=:8081 -tagfocus='route:GET /rides/{id}' http://localhost:8080/debug/pprof/profile?seconds=10
+```
+
+Other endpoints:
+
+```bash
+go tool pprof -http=:8081 http://localhost:8080/debug/pprof/heap   # allocs
+```
+
+Optional continuous profiling with Pyroscope (local docker, ~1-2% overhead):
+
+```bash
+docker run --rm -p 4040:4040 grafana/pyroscope
+```
+
+Add `github.com/grafana/pyroscope-go` and call `pyroscope.Start` with `ServerAddress: "http://localhost:4040"` and `route` label — gives the same flamegraphs but over time. Keep it only if pprof snapshots are not enough.
+
 ## TODO
 
 - Compute estimated power, speed
@@ -128,6 +170,7 @@ TypeScript checks can also be run directly with `npm run check`, covering format
 - processing takes components as input, not entities
 - issue: many passes are pedestriant (cf Marseille Calanques, http://localhost:8080/rides/397)
 - analytics: color split (by year, type, etc)
+- perf: improve GPX parsing and Analyze
 
 ## Resources