Skip to content

Clarify NATS stability and log shipper relationship #2359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kcmartin merged 1 commit into from
Feb 25, 2026
Merged

Clarify NATS stability and log shipper relationship #2359

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions monitoring/logs-api-options.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,21 +68,21 @@
This gives you structured JSON log messages in real time.

<div class="callout">
**Note:** The NATS proxy is a dusty corner of Fly’s platform. It works, but it’s unofficial, experimental, and may change as we evolve our logging infrastructure. If you’re building something serious, we recommend exporting logs instead.
**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.
</div>

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

Check warning on line 76 in monitoring/logs-api-options.html.md

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'reconnections' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'reconnections' a typo?", "location": {"path": "monitoring/logs-api-options.html.md", "range": {"start": {"line": 76, "column": 25}}}, "severity": "INFO"}
- 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.

Check warning on line 77 in monitoring/logs-api-options.html.md

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'backpressure' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'backpressure' a typo?", "location": {"path": "monitoring/logs-api-options.html.md", "range": {"start": {"line": 77, "column": 25}}}, "severity": "INFO"}
- If you want to dedupe across subscribers, use NATS queue groups.

Check warning on line 78 in monitoring/logs-api-options.html.md

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'dedupe' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'dedupe' a typo?", "location": {"path": "monitoring/logs-api-options.html.md", "range": {"start": {"line": 78, "column": 18}}}, "severity": "INFO"}
- 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.

### 3. Log Shipper to External Sink

If you want durable, queryable logs, export them. We maintain a small app called the [Fly Log Shipper](https://github.com/superfly/fly-log-shipper) that listens to NATS and forwards logs to sinks like Loki, Datadog, Elastic, Honeycomb, or even S3.

Check warning on line 85 in monitoring/logs-api-options.html.md

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'Datadog' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'Datadog' a typo?", "location": {"path": "monitoring/logs-api-options.html.md", "range": {"start": {"line": 85, "column": 208}}}, "severity": "INFO"}

Check warning on line 85 in monitoring/logs-api-options.html.md

View workflow job for this annotation

GitHub Actions / Vale linter 

[vale] reported by reviewdog 🐶
[Fly.Spelling] Is 'queryable' a typo?

Raw Output:
{"message": "[Fly.Spelling] Is 'queryable' a typo?", "location": {"path": "monitoring/logs-api-options.html.md", "range": {"start": {"line": 85, "column": 22}}}, "severity": "INFO"}

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.

Expand All @@ -104,7 +104,7 @@

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 is the most robust option if you want long-term retention, full-text search, alerting, or integration with your existing observability stack.
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:

Expand Down
Loading