Skip to content

Valhalla

OSM-based map-matching and routing service. Used by Sense Worker on ConfirmTrack to align noisy GPS samples to actual road segments.

At a glance

Property Value
Service Valhalla (OSM map-matching + routing)
Deployed In-cluster, Helm chart in axion.infra/services/valhalla
Service DNS infra-staging-valhalla.axion.svc:8002
Data OSM extract — sized to the deployment region
Caller Sense Worker (ValhallaClient component)

Why Valhalla (not OSRM, not Mapbox)

  • Self-hostable on the customer's infrastructure — Mapbox is out for on-prem.
  • Map-matching is first-class (/trace_attributes endpoint).
  • Compatible OSM data — the same extract serves routing for the Planner web app's basemap (we don't currently use Valhalla for routing, but it's there if needed).

How the platform uses it

When ConfirmTrack lands and the Worker has assembled the full GPS sequence for a track, it calls Valhalla's /trace_attributes with the points. Valhalla returns a sequence of OSM way IDs and a snapped polyline.

The matched polyline replaces the raw GPS in ClickHouse (tracks.route) and is_map_matched flips to true. This:

  1. Removes GPS noise — the line follows the road, not the antenna's wandering.
  2. Makes coverage maps line up with the road network — H3 cells touched by snapped points are more accurate.
  3. Enables future routing-style queries (e.g., "what's the next road segment we haven't covered?").

Data refresh

OSM data is refreshed periodically (monthly is typical):

  1. New OSM extract pulled into the Helm-deployed pod's persistent volume.
  2. Valhalla's tile-build step runs (CPU + disk heavy; can take an hour for a country-sized extract).
  3. Pod is restarted to pick up the new tiles.

Stale data → bad matches. Stale by years → matches against deprecated road geometry. Schedule the refresh.

Operations

  • Restart pod after data refresh — the daemon reads tiles at startup; in-place hot-reload isn't reliable.
  • Resource sizing: tile build is CPU-bound; runtime is memory-bound. Tile size grows with extract area.
  • Match failures are silent at the protocol level (Valhalla returns an empty result). The Worker treats empty results as "leave is_map_matched=false and try again later" — a sweep job re-runs map-matching for unmapped tracks.

Observability

  • HTTP latency exported to SigNoz from the Worker side (the call is one of the valhalla.match spans).
  • Valhalla's own metrics are scraped if the chart exposes them; otherwise rely on caller-side latency.

Configuration

"Valhalla": {
  "BaseUrl": "http://infra-staging-valhalla.axion.svc:8002",
  "TimeoutSeconds": 30
}

The 30-second timeout is generous — most matches complete in under a second, but particularly long tracks can stretch.