From 19113d22bec225d743219ba9cf4a0edbf67dd82b Mon Sep 17 00:00:00 2001
From: Nico <32375741+nulmete@users.noreply.github.com>
Date: Tue, 6 Jan 2026 09:11:58 -0300
Subject: [PATCH] Add Testing NATS logging local development docs (#37759)

**Related issue:** Resolves #37854

<!-- Add the related story/sub-task/bug number, like Resolves #123, or
remove if NA -->
Adds instructions on how to set up a NATS server locally to use as a log
destination.
Follow-up of https://github.com/fleetdm/fleet/pull/36527.
---
 .../testing-and-local-development.md          | 106 ++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/docs/Contributing/getting-started/testing-and-local-development.md b/docs/Contributing/getting-started/testing-and-local-development.md
index 1038ea15d7..8a60a6543e 100644
--- a/docs/Contributing/getting-started/testing-and-local-development.md
+++ b/docs/Contributing/getting-started/testing-and-local-development.md
@@ -726,6 +726,112 @@ FLEET_FIREHOSE_STATUS_STREAM=s3-stream-status
 
 You can inspect logs by visiting `http://localhost:4566/s3-firehose` on your browser.
 
+## Testing NATS logging
+
+1. Install the `nats` CLI:
+
+```sh
+$ go install github.com/nats-io/natscli/nats@latest
+```
+
+2. Install the `nats-server` executable:
+
+```sh
+$ curl -fsSL https://binaries.nats.dev/nats-io/nats-server/v2@latest | sh
+```
+
+3. Open a terminal and run the `nats-server`:
+
+```sh
+$ ./nats-server
+```
+
+4. Run Fleet with the following flags:
+
+```sh
+$ FLEET_ACTIVITY_ENABLE_AUDIT_LOG=true \
+FLEET_ACTIVITY_AUDIT_LOG_PLUGIN=nats \
+FLEET_OSQUERY_RESULT_LOG_PLUGIN=nats \
+FLEET_OSQUERY_STATUS_LOG_PLUGIN=nats \
+FLEET_NATS_SERVER=nats://localhost:4222 \
+FLEET_NATS_STATUS_SUBJECT=osquery_status \
+FLEET_NATS_RESULT_SUBJECT=osquery_result \
+FLEET_NATS_AUDIT_SUBJECT=fleet_audit \
+./build/fleet serve --dev
+```
+
+5. Open another terminal and run the following command to subscribe to all subjects.
+This will print all messages received by the NATS server.
+
+```sh
+$ ./nats --server=nats://localhost:4222 subscribe ">"
+```
+
+### Using NKey authentication
+
+One authentication mechanism allowed by nats is using an [NKey](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_intro/nkey_auth).
+
+
+1. Install `nkey`:
+
+```sh
+$ go install github.com/nats-io/nkeys/nk@latest
+```
+
+2. Generate a `User NKey`:
+
+```sh
+$ nk -gen user -pubout
+```
+
+You should see an output with the following format:
+
+```
+SUxxx
+Uyyy
+```
+
+The first output line starts with the letter `S` for `Seed`. The second letter, `U` stands for `User`. Seeds are private keys; you should treat them as secrets and guard them with care.
+
+The second line starts with the letter U for User and is a public key which can be safely shared.
+
+3. Copy the keys to a txt file, e.g. `nkey-cred-file.txt`.
+
+Create a new NATS server config file, e.g. `nats-server-config.conf`, with this content:
+
+```
+authorization {
+  users = [
+    {
+      nkey: "Uyyy"
+    }
+  ]
+}
+```
+
+4. Run the NATS server providing the config file above:
+
+```sh
+$ ./nats-server -config nats-server-config.conf
+```
+
+You should see a log saying `Using configuration file: nats-server-config.conf`.
+
+5. Start Fleet with the following flags:
+
+```sh
+$ FLEET_ACTIVITY_ENABLE_AUDIT_LOG=true \
+FLEET_ACTIVITY_AUDIT_LOG_PLUGIN=nats \
+FLEET_OSQUERY_RESULT_LOG_PLUGIN=nats \
+FLEET_OSQUERY_STATUS_LOG_PLUGIN=nats \
+FLEET_NATS_SERVER=nats://localhost:4222 \
+FLEET_NATS_STATUS_SUBJECT=osquery_status \
+FLEET_NATS_RESULT_SUBJECT=osquery_result \
+FLEET_NATS_AUDIT_SUBJECT=fleet_audit \
+FLEET_NATS_NKEY_FILE="nkey-cred-file.txt" \
+./build/fleet serve --dev
+```
+
 ## Telemetry
 
 You can configure the server to record and report trace data using OpenTelemetry or Elastic APM and use a tracing system like [Jaeger](https://www.jaegertracing.io/) to consume this data and inspect the traces locally.