Third-party usage metrics¶
The backend calls three paid APIs: DeepSeek (the semantic layer), Google Places (API New) and Serper (search enrichment). Each call is counted on /metrics so request volume, errors, tokens, credits and estimated spend can be charted per environment. Prometheus adds the env label (prod, dev) at scrape time. The free Frankfurter exchange-rate API is counted the same way.
Labels stay low-cardinality: no user IDs, place IDs or query text. A failed call carries a bucketed status: err_timeout (client timeout or expired deadline), err_transport, err_429, err_5xx, err_auth, err_4xx, plus err_parse and similar where the client decodes the body. Known label combinations are zero-initialised, so panels read 0 before the first call.
DeepSeek¶
Emitted by internal/platform/llm/client.go. kind is the semantic operation (extract, select).
| Metric | Labels | Meaning |
|---|---|---|
llm_requests_total |
model, kind, status |
One per HTTP attempt, so a retried call counts twice |
llm_request_duration_seconds |
model, kind |
Histogram covering the whole logical call, retries included |
llm_tokens_total |
model, kind, direction (input, output), cache (hit, miss, na) |
From the response usage block: prompt_cache_hit_tokens and prompt_cache_miss_tokens for input, completion_tokens for output. A provider that omits the cache split counts all prompt_tokens as miss |
deepseek_balance_usd |
currency |
Prepaid balance, refreshed hourly by the async worker |
Google Places¶
Emitted by internal/platform/places/places_service.go, the only Places caller. The location resolver and enricher reach it through NearbySearch and FetchPlaceDetails; location_provider_calls_total{provider, reason} records why each escalation happened.
| Metric | Labels | Meaning |
|---|---|---|
places_requests_total |
operation (nearby_search, place_details), sku, status |
One per HTTP request |
places_estimated_cost_usd_total |
operation, sku |
List price of each successful request. Failed requests add nothing |
The SKU comes from the field mask the code sends: a request bills at the highest tier of any field it asks for. placesSKU in usage_metrics.go derives it from the field lists in Google's Places data-fields reference, so a mask change moves the label with it.
| Operation | Fields that set the tier | SKU |
|---|---|---|
nearby_search |
currentOpeningHours, phone numbers, websiteUri, priceLevel, rating, userRatingCount |
nearby_search_enterprise |
place_details |
the same Enterprise fields | place_details_enterprise |
Prices per SKU live in config.PlacesSKUPriceUSD (backend/config/provider_pricing.go), at the first paid tier before the monthly free cap. The estimate therefore runs high for low volume; the Cloud Billing export is the bill of record. Update the table when Google's pricing page changes.
Serper¶
Emitted by internal/platform/places/search_enrichment.go.
| Metric | Labels | Meaning |
|---|---|---|
search_enrichment_requests_total |
provider (serper), endpoint (search, maps), status |
One per HTTP request. Prometheus stores endpoint as exported_endpoint, because the scrape target has its own endpoint label |
search_enrichment_request_duration_seconds |
provider, endpoint |
Latency histogram |
serper_credits_used_total |
operation (search, maps) |
Credits from each successful response's credits field. A response without it falls back to config.SerperCreditsPerRequest (1 credit per default-sized query) |
The catalog seeder (cmd/catalogseeder) also calls Serper, but runs as a one-off job outside the API, so its calls are not on these metrics.
Frankfurter¶
Emitted by internal/platform/currency/fx/frankfurter.go. Free and keyless; the counters show how polite the cache keeps us (one call per base currency per day). See Currency → Conversion.
| Metric | Labels | Meaning |
|---|---|---|
fx_requests_total |
provider (frankfurter), status |
One per HTTP request; cache hits make none |
fx_request_duration_seconds |
provider |
Latency histogram |
Dashboards and alerts¶
The panels and the monthly cost rules live in the devops repo: the Tomoda Costs dashboard and k8s/envs/platform/manifests/cost-alerts.yaml.