From 5708f4c687b54097e125f70c6aab376fc7aaa9eb Mon Sep 17 00:00:00 2001 From: Leslie Cheung <16958222+lesliebc@users.noreply.github.com> Date: Sun, 24 May 2026 12:32:30 -0400 Subject: [PATCH 1/4] Amend response format and query params for app logs endpoint --- monitoring/logs-api-options.html.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/monitoring/logs-api-options.html.md b/monitoring/logs-api-options.html.md index 103676adda..b79eb755ca 100644 --- a/monitoring/logs-api-options.html.md +++ b/monitoring/logs-api-options.html.md @@ -37,13 +37,13 @@ GET /api/v1/apps/:app_name/logs Authorization: ``` -You’ll get a stream of newline-delimited JSON log lines. You can pass query params like: +The response is a JSON:API document with a `data` array of log entries and a `meta.next_token` cursor for paging. By default, the most recent 100 logs from the last 24 hours are returned. You can pass these query params to filter logs or set a starting timestamp: -- `region=cdg` (filter by region) -- `instance=` (filter by instance — sometimes flaky) -- `start_time=2023-08-01T00:00:00Z` (to backfill) +- `region`: three-letter region code. Returns only logs from this region +- `instance`: a Machine ID. Returns only logs from this instance +- `next_token`: a nanosecond Unix timestamp. Returns logs after this time. Each response includes a `meta.next_token` — pass it in your next request to page forward -This endpoint isn’t officially documented, but it’s mostly stable: `flyctl` depends on it. That said, filters don’t always work as expected. +This endpoint isn’t officially supported for external use, but it’s mostly stable: `flyctl` depends on it. Use this for quick fetches or simple polling scripts. If you hit rate limits or auth issues, check that your token has `read` access to the app. @@ -78,7 +78,7 @@ This gives you structured JSON log messages in real time. - If you want to dedupe across subscribers, use NATS queue groups. - NATS only streams logs from starting from the moment you connect. You won’t get any history unless you’ve been subscribed the whole time. -For more details on connecting to Fly’s NATS log stream (authentication, subject patterns, example clients), head over to the [Observability for User Apps](/docs/blueprints/observability-for-user-apps/?utm_source=chatgpt.com#streaming-fly-app-logs-to-your-end-users) guide. +For more details on connecting to Fly’s NATS log stream (authentication, subject patterns, example clients), head over to the [Observability for User Apps](/docs/blueprints/observability-for-user-apps/#streaming-fly-app-logs-to-your-end-users) guide. ### 3. Log Shipper to External Sink From b3308f4f68cf1eab173de8d0c46b13eb8adf5c45 Mon Sep 17 00:00:00 2001 From: Leslie Cheung <16958222+lesliebc@users.noreply.github.com> Date: Sun, 24 May 2026 12:41:21 -0400 Subject: [PATCH 2/4] Update logs backend and retention period after VictoriaLogs migration --- monitoring/logging-overview.html.markerb | 2 +- monitoring/logs-api-options.html.md | 4 ++-- monitoring/search-logs.html.markerb | 18 ++++++------------ 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/monitoring/logging-overview.html.markerb b/monitoring/logging-overview.html.markerb index 7f23e7922a..ded438bab7 100644 --- a/monitoring/logging-overview.html.markerb +++ b/monitoring/logging-overview.html.markerb @@ -25,7 +25,7 @@ Learn how to fetch, stream or export logs programmatically without touching the ## Search logs -We have an app log search feature in Grafana that retains logs for 30 days. For more information, see [Search logs](/docs/monitoring/search-logs/). +We have an app log search feature in Grafana that retains logs for 7 days. For more information, see [Search logs](/docs/monitoring/search-logs/). ## Export logs diff --git a/monitoring/logs-api-options.html.md b/monitoring/logs-api-options.html.md index b79eb755ca..8b91bfafa4 100644 --- a/monitoring/logs-api-options.html.md +++ b/monitoring/logs-api-options.html.md @@ -12,7 +12,7 @@ date: 2025-10-01 ## Overview -Fly.io apps run on Firecracker microVMs we call Machines. Each Machine captures `stdout`/`stderr`, ships those logs over NATS, and stores them for a period of time in a Quickwit-backed search index. Most users consume logs via `fly logs` or by setting up log shipping to an external sink. +Fly.io apps run on Firecracker microVMs we call Machines. Each Machine captures `stdout`/`stderr`, ships those logs over NATS, and stores them for a period of time in a VictoriaLogs-backed search index. Most users consume logs via `fly logs` or by setting up log shipping to an external sink. But sometimes you want to grab logs directly, without a CLI or setting up an exporter, because you’re building a tool, automating something, or you just want to pipe logs into your own system. @@ -47,7 +47,7 @@ This endpoint isn’t officially supported for external use, but it’s mostly s Use this for quick fetches or simple polling scripts. If you hit rate limits or auth issues, check that your token has `read` access to the app. -Importantly, this is the only option that gives you access to historical logs going back to the current retention window (about 15 days). The other options only start streaming from the moment they're connected. +Importantly, this is the only option that gives you access to historical logs going back to the current retention window (about 7 days). The other options only start streaming from the moment they're connected. ### 2. Subscribe to logs via NATS (experimental) diff --git a/monitoring/search-logs.html.markerb b/monitoring/search-logs.html.markerb index c88c54ffd8..387b1cbcc2 100644 --- a/monitoring/search-logs.html.markerb +++ b/monitoring/search-logs.html.markerb @@ -6,20 +6,14 @@ redirect_from: /docs/metrics-and-logs/search-logs/ ---
-Searchable application logs is a beta feature. Learn more and post your suggestions or issues in the community thread: [Searchable application logs in Grafana](https://community.fly.io/t/searchable-application-logs-in-grafana/18878+external) +Searchable application logs is a beta feature. During the beta period, log search is free.
-We’re working with [Quickwit](https://quickwit.io/docs+external) to bring you an application log cluster and search interface. +Log search on Fly.io is backed by our own instance of [VictoriaLogs](https://docs.victoriametrics.com/victorialogs+external) and is exposed through a Grafana interface. We currently retain logs for 7 days. -You can access searchable logs in Grafana: +To search logs from your Fly Apps: -- Click **Log Search** in your Fly.io app dashboard, or -- Go directly to your [Grafana metrics](https://fly-metrics.net/d/fly-logs/fly-logs+external) +- Click **Search logs in Grafana** in your Fly.io app dashboard, or +- Open your [Grafana dashboard](https://fly-metrics.net/d/fly-logs/fly-logs) directly -
-**Important:** If you’re already signed in to Grafana, then you'll need to log out and log back in. -
- -Searchable logs are built on our [Tigris Storage](/docs/tigris/) and [Supabase Postgres](/docs/supabase/) extensions. - -For the beta period, log search is free and we retain logs for 30 days. Learn how to build more complex queries [Quickwit’s query language](https://quickwit.io/docs/get-started/query-language-intro+external). +Learn how to build more complex queries using [LogsQL, the query language of VictoriaLogs](https://docs.victoriametrics.com/victorialogs/logsql+external). From 4efe2fef1bb8d1a4a54c38da1ebae7e853c2de3d Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Tue, 26 May 2026 12:11:04 -0700 Subject: [PATCH 3/4] Update monitoring/search-logs.html.markerb --- monitoring/search-logs.html.markerb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/monitoring/search-logs.html.markerb b/monitoring/search-logs.html.markerb index 387b1cbcc2..8047e973da 100644 --- a/monitoring/search-logs.html.markerb +++ b/monitoring/search-logs.html.markerb @@ -6,7 +6,7 @@ redirect_from: /docs/metrics-and-logs/search-logs/ ---
-Searchable application logs is a beta feature. During the beta period, log search is free. +Searchable application logs are a beta feature. During the beta period, log search is free.
Log search on Fly.io is backed by our own instance of [VictoriaLogs](https://docs.victoriametrics.com/victorialogs+external) and is exposed through a Grafana interface. We currently retain logs for 7 days. From b6aadfb794432a84eee881803f8de3d07939f951 Mon Sep 17 00:00:00 2001 From: Leslie Cheung <16958222+lesliebc@users.noreply.github.com> Date: Tue, 26 May 2026 15:31:02 -0400 Subject: [PATCH 4/4] Add example for `next_token` query param --- monitoring/logs-api-options.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/monitoring/logs-api-options.html.md b/monitoring/logs-api-options.html.md index 8b91bfafa4..1a1a4a11b6 100644 --- a/monitoring/logs-api-options.html.md +++ b/monitoring/logs-api-options.html.md @@ -41,7 +41,7 @@ The response is a JSON:API document with a `data` array of log entries and a `me - `region`: three-letter region code. Returns only logs from this region - `instance`: a Machine ID. Returns only logs from this instance -- `next_token`: a nanosecond Unix timestamp. Returns logs after this time. Each response includes a `meta.next_token` — pass it in your next request to page forward +- `next_token`: a nanosecond Unix timestamp (e.g `1779235200000000000`). Returns logs after this time. Each response includes a `meta.next_token` — pass it in your next request to page forward This endpoint isn’t officially supported for external use, but it’s mostly stable: `flyctl` depends on it.