# API Service Mapping

Service alias → Datadog service name → K8S deployment → namespace.

**Canonical source**: the api config (`k8s.services`) —
`pysae-ai-tools project show --project pysae/api --json k8s.services`
(`name`, `deployment` = `<env>-<base>` template, `datadog_service`). The **actual k8s
deployment** is the template with `<env>` substituted, e.g. `prod-api-ndp` (verified via
`kubectl get deploy -n prod`). The base names below are a convenience cache.

| Alias | Datadog service | K8S deployment base (real = `<env>-<base>`) | Namespace |
|-------|-----------------|---------------------------------------------|-----------|
| `api-fast` | `api-fast` | `api-fast` | `prod` |
| `ndp` | `api-nav-data-processor` | `api-ndp` | `prod` |
| `gtfsrt` | `api-gtfs-rt` | `api-gtfsrt` | `prod` |
| `evt` | `events-handler` | `api-evt` | `prod` |
| `stats` | `api-stats` | `api-stats` | `prod` |
| `simu` | `api-simulation` | `api-simu` | `prod` |
| `docs` | `docs` | `api-docs` | `prod` |
| `mcf` | — | `api-mcf` | `prod` |
| `metrics` | — | `api-metrics` | `prod` |

## Usage

When user provides an alias (e.g. `ndp`), resolve it to the Datadog service name for metric queries and the K8S deployment name for kubectl commands.

If user provides a name not in this table, try fuzzy matching against both alias and Datadog service columns. If ambiguous, ask the user.

## Datadog query patterns

```
# Latency P99 for a service (last 1h)
avg:trace.fastapi.request.duration.by.service.99p{service:<dd_service>,env:prod}

# Latency P95
avg:trace.fastapi.request.duration.by.service.95p{service:<dd_service>,env:prod}

# Latency P50
avg:trace.fastapi.request.duration.by.service.50p{service:<dd_service>,env:prod}

# Error rate
sum:trace.fastapi.request.errors{service:<dd_service>,env:prod}.as_rate()

# Request throughput
sum:trace.fastapi.request.hits{service:<dd_service>,env:prod}.as_rate()
```

## kubectl patterns

```bash
# Pods status
kubectl get pods -n prod -l app=<k8s_deployment> -o wide

# Resource usage
kubectl top pods -n prod -l app=<k8s_deployment>

# Pod restarts (check RESTARTS column in get pods output)
```
