Skip to main content

​
Overview

Beacon writes endpoint telemetry to a local runtime JSONL log. Local log checks help confirm that commands, the dashboard, and any downstream forwarding are reading the same file. This guide shows how to find the active log, keep user-mode and system-mode checks separate, test a custom log path, and understand local rotation behavior.

​
Setup

Write a validation event first so the runtime log has a known record:
Write a validation event
beacon endpoint test-event

​
1. Find The Active Runtime Log

Use status to print the configured runtime log path and last observed event:
Print runtime log path
beacon endpoint status
Sample output
$ beacon endpoint status

Runtime log: ~/.beacon/endpoint/logs/runtime.jsonl
Last event: 2026-06-10T04:37:14Z
Runtime log source: user
For machine-readable output:
Print status as JSON
beacon endpoint status --json
Status also reports runtime-log source warnings when a system collector may be writing OTLP events to a different log than the one you are inspecting.

​
2. Compare User And System Paths

Default local evaluation uses per-user endpoint paths:
Check user-mode paths
beacon endpoint status --user
beacon endpoint test-event --user
Managed package deployments usually use system mode and write endpoint events to /var/log/beacon-agent/runtime.jsonl:
Check system-mode paths
sudo beacon endpoint status --system
sudo beacon endpoint test-event --system
Keep user-mode and system-mode checks separate. A dashboard opened against a user log will not show events written only to the system log, and a system-mode status check may report a different collector or launchd service state.

​
3. Understand Log Rotation

Beacon keeps the active runtime.jsonl path stable and rotates it when the next write would exceed 10 MiB. By default, it keeps five numbered local archives next to the active file: 
runtime.jsonl
runtime.jsonl.1
runtime.jsonl.2
runtime.jsonl.3
runtime.jsonl.4
runtime.jsonl.5
External shippers should continue tailing the active runtime.jsonl path and use their normal file-rotation handling to checkpoint offsets. The local dashboard can inspect the active log and numbered archives when you need to review recent rotated events.

​
4. Test A Custom Log Path

Use --log-path when testing a temporary runtime log or a support reproduction:
Use a custom runtime log
beacon endpoint test-event --log-path /path/to/runtime.jsonl
beacon endpoint status --log-path /path/to/runtime.jsonl
beacon endpoint dashboard --log-path /path/to/runtime.jsonl
The same path should be used across the write, status, and dashboard checks. When a custom log rotates, archives use the same path plus a numeric suffix. For example, /tmp/beacon/runtime.jsonl rotates to /tmp/beacon/runtime.jsonl.1.

​
Verify Results

AreaExpected result
Runtime pathStatus shows the log path you intend to test
Writabilitybeacon endpoint test-event can append a validation event
FreshnessStatus reports a recent last Beacon event
RotationThe active log remains at runtime.jsonl and older local data moves to numbered archives
Dashboard sourceDashboard --log-path matches the tested runtime log
Deployment modeUser or system mode matches the installation you are validating

​
Troubleshooting

  • If status points at a different log than the dashboard, pass the same --log-path to both commands.
  • If the system collector is running but the user log is empty, validate with --system.
  • If a shipper misses records after rotation, confirm it tails the active runtime.jsonl path and handles numbered archives normally.
  • If test-event cannot write, check parent directory permissions and run doctor checks.

Run Endpoint Health Checks

Confirm endpoint configuration, collector health, and local diagnostics.

Write Validation Events

Append a known-good event to the runtime JSONL log.

Test the Local Dashboard

Confirm the dashboard is reading and summarizing the expected log.

Endpoint event schema

Review the normalized JSONL contract used for endpoint events.