Skip to main content
Illustration by Annie Ruygt of a rocket ship, a satellite dish, a cargo container, and a clock, all representing different options for logs

​
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 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.

​
Options for fetching logs programmatically

You can get logs programmatically via:
  • Undocumented HTTP API: What fly logs uses under the hood.
  • NATS proxy: Subscribe to real-time logs at the message level.
  • Log shipper to external sink: Ingest logs elsewhere, then query them via that system.
Each has tradeoffs. If you want durable search, export logs. If you want low-latency push, use NATS. If you want to curl something now, use the HTTP API.

​
1. HTTP API (same as fly logs)

The Fly CLI hits an internal API to stream logs. You can use it too:
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: 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 (e.g. 1779235200000000000). Returns logs after this time, used either as a paging cursor or to backfill from a specific moment. Each response includes a meta.next_token that you can pass in your next request to page forward.
    • next_token replaces the previously documented start_time (ISO 8601) param.
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. 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)

Logs are streamed through NATS under subjects like:
You can subscribe directly using NATS clients, connecting via the proxy URL and authenticating with your org slug and personal access token. Example NATS subject:
This gives you structured JSON log messages in real time.
Note: The NATS proxy is an internal transport without a versioned API or stability guarantee. It works, but may change as we evolve our logging infrastructure. If you’re building something serious, we recommend exporting logs via the log shipper instead.
Things to know:
  • You’ll need to handle reconnections: if the network drops or the proxy restarts, your subscriber needs to reconnect and resume without losing messages.
  • You’ll need to handle backpressure: if your app can’t process logs fast enough, messages might pile up and get dropped. Design your consumer to either keep up or fail gracefully.
  • 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 guide.

​
3. Log Shipper to External Sink

If you want durable, queryable logs, export them. We maintain a small app called the Fly Log Shipper that listens to NATS and forwards logs to sinks like Loki, Datadog, Elastic, Honeycomb, or even S3. The log shipper is a prebuilt Fly app running Vector, with configuration you can customize via TOML. It subscribes to log subjects and streams data wherever you want. Example config:
To control which logs get forwarded, set the SUBJECT environment variable when deploying:
Like NATS, the log shipper only sees logs from the moment it connects onward. If you deploy it today, you won’t see logs from yesterday. The log shipper uses NATS internally. Since it’s maintained by Fly, it’s more likely to stay compatible with infrastructure changes than a custom NATS client. It’s the most robust option if you want long-term retention, full-text search, alerting, or integration with your existing observability stack. More details:

​
Summary: So what should I use?

  • Want to grep logs from a script? Try the HTTP API.
  • Want real-time stream into your own system? NATS (with caveats).
  • Want reliable search and dashboards? Export logs via shipper.