Observability
What is tracked, where to see it, and how to use observability to understand and debug your API traffic.
Overview
This guide explains how observability works in the application: what is tracked, where to see it, and how to use it to understand and debug your API traffic.
What is observability?
Observability gives you visibility into your API requests that go through the gateway. Every request (to functions, KV, queues, storage, scheduler, cron, and other primitives) can be counted, and many are stored in detail so you can:
- See how many requests you're making and how that changes over time
- Spot errors (4xx and 5xx) and see whether they came from the gateway or from upstream services
- Inspect latency (how long requests take)
- Drill into individual requests to see headers, request/response bodies, and timing
All of this is per team: you only see data for the team you're currently using in the console.
Where to find it
- Console → Observability
Main observability page: counts, throughput, errors, latency, recent activity, and recent errors. - Console → Overview (dashboard)
Summary widgets: requests in the last 7 days, errors in the last 24 hours, and a small throughput chart. Each links through to the full Observability page. - Request detail
From the Observability page (or Overview recent activity), click a request to open its detail view: method, path, status, duration, headers, and request/response bodies.
You must be signed in and have a team selected to see observability data. If you don't select a team, the Observability page will ask you to select one.
What gets recorded?
Every request (counters)
For every API request through the gateway, the system records:
- Counts per operation (e.g.
invokeFunction,putKvItem) and per day - Throughput (requests per day, and per hour for charts)
- Success vs error (HTTP 2xx/3xx = success, 4xx/5xx = error)
- Error source when it's an error:
gateway(our side: e.g. 404, 429, 401, 502) orupstream(from the control plane / backend)
These counters are stored in Redis and drive the Counts, Throughput, Errors by source, and Error rate views. They are not tied to log retention (see below).
Request logs (when we store full details)
In addition to counters, request logs (full details for a single request) are stored only when:
- The request returned an error (HTTP status ≥ 400), or
- The request succeeded and success logging is enabled and the request is within the success sample rate (by default, all successful requests are logged; this can be reduced for high traffic).
So: all errors are logged; successful requests may be logged in full depending on configuration (e.g. 100% or a sample).
Each stored request log includes:
- Request: method, path, headers, body (truncated if over the configured max length)
- Response: status, body (truncated if over the max)
- Metadata: request ID, operation ID, duration (ms), status category (e.g. success, client_error, server_error), error source (gateway vs upstream), timestamps
Request logs are stored in the database and automatically pruned after a configured retention period (e.g. 30 days). Counters are not pruned the same way.
Using the console
Main Observability page: what each section shows
Counts
- Total requests in the selected time window (e.g. last 7 or 14 days), for your team.
- Per-operation counts: how many requests for each API operation (e.g.
invokeFunction,listKvItems). - You can sort by count (high/low) or by error rate.
Use this to see which operations you use most and which have the highest error rate.
Throughput
- Requests per day for your team over the last 7–90 days (depending on the "Days" setting).
- Shown as a chart: each bar is one day's total request count.
Use this to see trends and spikes.
Errors by source
- How many errors came from the gateway (e.g. not found, quota exceeded, auth, upstream unreachable).
- How many came from upstream (the control plane / backend returned 4xx or 5xx).
Use this to see whether issues are on our side (gateway) or from the backing services (upstream).
Latency
- Per-operation latency for the last 24 hours: P50, P95, P99 (in milliseconds) and request count.
- Only includes requests that have a stored duration (from request logs).
Use this to see which operations are slow and how stable latency is.
Recent activity
- A list of recent API requests (method, path, status, time).
- You can filter by:
- Date range (from / to)
- Endpoint (path or operation ID)
- HTTP method (GET, POST, PUT, etc.)
- You can change how many rows are shown (e.g. 25, 50, 100).
Click a row to open the request detail for that request.
Recent errors
- A list of recent failed requests (status ≥ 400).
- You can filter by: all errors, 4xx only, 5xx only, or by operation.
- Default cap on how many errors are shown (e.g. 200; can be increased up to a maximum).
Click a row to open the request detail for that error.
Request detail page
From Observability (or Overview recent activity), clicking a request opens the request detail view. You'll see:
- Summary: Request ID, operation, status code, status category, error source (if any), duration, time, body sizes.
- Request: Headers and body (with copy button; body may be truncated with a "... truncated" note if it was too long).
- Response: Response body (same truncation and copy behavior).
Request ID is a unique identifier for that call. You can copy it and use it in support requests or when correlating with your own logs.
Error source (when present) is either:
- gateway – The gateway returned the error (e.g. 404, 429, 401, 502).
- upstream – The error was returned by the control plane / backend and passed through.
Tips and best practices
- Select the right team
Observability is scoped to the current team. Switch teams in the console if you manage more than one. - Use the time range
Use the "Days" control (e.g. 7, 14, 90) to change how much history you see for counts and throughput. - Narrow recent activity
Use the activity filters (date range, endpoint, method) to find specific calls instead of scrolling through everything. - Debug errors from the list
Use "Recent errors" and the error filters (4xx/5xx, operation) to find failing calls, then open the request detail to see exact request/response and error source. - Save the Request ID
When talking to support or debugging, the Request ID in the detail view uniquely identifies that request. - Bodies may be truncated
Request and response bodies are stored only up to a maximum length (e.g. 32 KB). Longer bodies are cut and marked "... truncated". Original sizes are still shown in the summary. - Sensitive data
Request and response bodies are stored as captured. Avoid sending secrets or personal data in bodies if you need to inspect them in the console. Application logs (e.g. Laravel logs) may redact API keys and similar; the observability request log stores the request as received (headers and bodies) for debugging.
Retention and pruning
- Request logs (the detailed records you see in "Recent activity" and "Request detail") are kept only for a limited time (e.g. 30 days). Older logs are removed automatically by a daily job (
observability:prune-logs). You cannot recover pruned logs. - Counters (counts, throughput, success/error) are stored separately and are not pruned in the same way; they drive the charts and totals even when individual request logs are gone.
Summary
| What you want | Where to look |
|---|---|
| Request volume over time | Observability → Throughput (or Overview chart) |
| Errors in last 24h | Overview → "Errors (24h)" or Observability → Recent errors |
| Which operations fail | Observability → Counts (sort by error rate) |
| Gateway vs upstream | Observability → Errors by source |
| Slow operations | Observability → Latency (P50/P95/P99) |
| One specific request | Observability → Recent activity (filter) → click row → Request detail |
| Full request/response | Request detail (headers, bodies, status, duration) |
Observability runs automatically for all API traffic through the gateway. No extra setup is required on your side beyond using the console to view and filter the data.