Skip to content

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.