> ## Documentation Index
> Fetch the complete documentation index at: https://dcc-5ccd5152.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BigFred Diagnostics: Logs, Slots, and the Audit Log

> Access server logs, DCC slot occupancy, and the audit log from the BigFred admin interface to monitor system health and trace operator activity.

BigFred gives you several built-in tools to monitor system health, inspect DCC command station state, and review operator activity — all without leaving the browser. This page covers the **Logs** page (admin-only), the **DCC Bus Slots** page (admin-only), the **Audit Log** page (available to all authenticated users), and the lightweight `/healthz` health check endpoint.

***

## Server Logs

**Admin → Logs**

The Logs page streams the tail of every supervisord-managed process log directly into your browser — no SSH access required. Log sources include:

* **loco-server** — the main application server
* **dcc-bus daemons** — one per configured command station
* **Valkey (Redis)** — the sidecar used for audit log and session storage

### How to use

1. Open **Admin → Logs** in the left sidebar.
2. Choose a **source group** (process name) from the first dropdown.
3. Choose a **log file** from the second dropdown (each process may have a current log and rotated archives).
4. Set the **tail lines** field to control how many of the most recent lines are loaded (default: 500; maximum: 10,000).
5. Click **Refresh** to reload the latest content at any time.

The log viewer shows the file name, size, and a truncation notice when the file is too large to display in full.

<Tip>
  Increase the log verbosity to `debug` by setting `LOG_LEVEL=debug` in your `loco-server.conf` (or passing `--log-level=debug` on the command line) and restarting. This is especially helpful when diagnosing command station connection problems. Remember to set it back to `info` once you're done — debug logging is verbose.
</Tip>

<Note>
  Logs can be read in the UI but cannot be downloaded directly. For offline analysis or log shipping, access the log files on the server directly — they are standard text files managed by supervisord and written to the configured log directory.
</Note>

***

## DCC Bus Slots

**Admin → DCC Bus Slots**

### What slots are

A DCC command station keeps an internal table of active locomotives called the **slot table**. Each slot holds one DCC address and tracks its speed, direction, and which user is driving it. The number of available slots depends on the command station type:

| Command station              | Slot limit                             |
| ---------------------------- | -------------------------------------- |
| LocoNet (e.g. DCS52, DCS240) | Fixed — 80 slots by default in BigFred |
| Z21                          | No fixed slot limit                    |

LocoNet's fixed-size slot table is a significant operational constraint. If all 80 slots are occupied, new locomotives cannot be activated until an existing slot is freed.

### What this page shows

The DCC Bus Slots page connects to the selected command station over a live WebSocket and displays a real-time snapshot of the slot table. For each active lease you can see:

| Column       | Meaning                                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| **Address**  | DCC address of the locomotive                                                                             |
| **Kind**     | Whether this is a single-address lease or a train consist                                                 |
| **Holders**  | User ID, session identifier, connection source (`ws`, `z21`, `WiFred`), and time since last drive command |
| **Acquired** | How long ago this slot was first taken                                                                    |
| **Flags**    | Any pending state, such as a release already in progress                                                  |

A **slot budget bar** at the top of the page shows total used vs. maximum slots and remaining headroom. A separate per-user table shows how many slots each user is currently holding relative to their per-user cap (`maxPerUser`).

A slot row highlighted in amber means the holder is a remote client (Z21 or WiThrottle handset) that hasn't sent a drive command recently and is approaching the idle timeout.

<Warning>
  Releasing a slot sends an immediate release command to the command station. If the locomotive is actively running, it will stop and the throttle driver will lose control. Only release slots that are genuinely stale.
</Warning>

### Releasing a stale slot

1. Open **Admin → DCC Bus Slots**.
2. Select the command station from the dropdown.
3. Find the slot you want to free — look for entries with a holder that is no longer connected or a DCC address that is not in use.
4. Click **Release** in the Actions column.
5. Confirm the release in the dialog that appears.

The slot table updates in real time, so you'll see the slot disappear within a second or two of releasing it.

***

## Audit Log

The Audit Log is available to **all authenticated users** from the main navigation — it is not restricted to admins.

The log shows a chronological table of significant actions taken in BigFred, with a timestamp and a plain-English description of each event. Events recorded include:

* User logins and logouts
* Vehicle registrations and modifications
* Lease grants and revocations (who took or released control of a locomotive)
* Command station configuration changes
* Admin actions (user management, layout changes, etc.)

### How to use

Navigate to **Audit Log** in the main sidebar. The page loads the **last 200 entries** by default. You can request up to 500 entries using the API directly (`/api/v1/audit-log?limit=500`).

Click **Refresh** at any time to pull the latest entries.

Each row shows:

* **Time** — the local date and time the event occurred
* **Event** — a human-readable description including the actor's login name and relevant details

Use the audit log to:

* Trace who made a specific change and when
* Review session history after an unexpected state change
* Verify that a vehicle hand-off or lease revocation was recorded correctly

<Note>
  Audit entries are stored in an internal message stream and trimmed automatically to the most recent 5,000 entries. If Valkey (Redis) is unavailable when BigFred starts, the audit service is disabled and the log will appear empty. See [Troubleshooting](/admin-guide/troubleshooting) for how to resolve this.
</Note>

***

## Health Check

BigFred exposes a lightweight liveness endpoint you can poll from a router, uptime monitor, or shell script:

```
GET /healthz
```

A healthy server responds with HTTP `200 OK` and the plain-text body `ok`.

**Example:**

```bash theme={null}
curl http://192.168.0.10:8080/healthz
# → ok
```

Use this endpoint to:

* Confirm BigFred started successfully after a reboot
* Set up an uptime monitor (UptimeRobot, Healthchecks.io, router watchdog, etc.)
* Script a readiness check before running automated tests against the API

<Tip>
  If `/healthz` returns anything other than `ok`, or times out, check the loco-server process with `supervisorctl status` on the host and review Admin → Logs for startup errors.
</Tip>