Files · Vercel AI Gateway Observability for SMB AI Agent Operations

# Vercel AI Gateway Observability for SMB AI Agent Operations
 
Unified OpenTelemetry tracing, cost tracking, and performance alerts for every LLM call routed through Vercel AI Gateway.
 
## Architecture
 
```
Vercel AI Gateway → Hono API (/api/telemetry/[[...route]]) → TelemetryService
                                                                  ├── SpanEnricher (OTel GenAI semconv)
                                                                  ├── CostTracker (LLM cost per call)
                                                                  ├── CostAggregationService
                                                                  │     ├── CostCollector (buffered spans)
                                                                  │     ├── CostAggregator (multi-dim)
                                                                  │     └── BudgetManager (per-tenant caps)
                                                                  ├── MetricsManager (OTLP metrics)
                                                                  └── Logger (Pino, PII-redacted)
                                                                        └── LangfuseExporter (traces)
 
BudgetAlertService (cron: */5 * * * *) → Slack webhook on threshold breach
Dashboard (Next.js App Router) → reads from Hono API
```
 
## Getting Started
 
```bash
pnpm install
pnpm dev         # http://localhost:3000
```
 
## Testing
 
```bash
pnpm test        # vitest run --coverage
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint .
```
 
## Submitting a Telemetry Span
 
```bash
curl -X POST http://localhost:3000/api/telemetry/spans \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-5.2",
    "inputTokens": 150,
    "outputTokens": 45,
    "tenant": "acme-corp"
  }'
```
 
## Environment Variables
 
| Variable | Description |
|---|---|
| `OTEL_SERVICE_NAME` | OpenTelemetry service name |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `SUPABASE_URL` | Supabase project URL |
| `SUPABASE_ANON_KEY` | Supabase anonymous key |
| `SLACK_WEBHOOK_URL` | Slack webhook for budget alerts |
| `DEFAULT_DAILY_BUDGET` | Default daily budget cap in USD |
| `DEFAULT_MONTHLY_BUDGET` | Default monthly budget cap in USD |
 
## API Endpoints
 
| Method | Path | Description |
|---|---|---|
| `POST` | `/api/telemetry/spans` | Submit an LLM call span |
| `GET` | `/api/telemetry/costs/:tenant` | Get cost breakdown by tenant |
| `GET` | `/api/telemetry/summary` | Get aggregated cost summary |
| `POST` | `/api/telemetry/budget/check` | Check budget against estimated cost |
| `GET` | `/api/telemetry/budget/status/:tenant` | Get budget status for a tenant |
| `POST` | `/api/telemetry/alerts/config` | Create or update alert configuration |
| `GET` | `/api/telemetry/alerts/config` | List alert configurations |
| `GET` | `/api/telemetry/dashboard/metrics` | Get aggregated dashboard metrics |
 
## License
 
MIT — see [LICENSE](./LICENSE).