Why does the Laravel Pulse Servers card stay empty after installation, and what does the pulse:check command do on each server?

## Two kinds of recorders **Laravel Pulse** recorders capture data in one of two ways: - **Event-driven** recorders hook into things the app already does: `SlowRequests` and `UserRequests` hook the HTTP kernel, `SlowQueries` listens to `QueryExecuted`, `SlowJobs` and `Queues` listen to queue events, `Exceptions` to reported exceptions. They start filling their cards as soon as traffic arrives. - **Polling** recorders need something to wake them up regularly. The built-in one is `Servers`, and some third-party cards work the same way. The Servers card stays empty after installation because nothing is waking its recorder yet. ## What pulse:check does `php artisan pulse:check` is a long-running loop. On each iteration, about once per second, it: 1. Exits if the restart signal in the cache (`laravel:pulse:restart`) has changed since it started. 2. Tries a one-second cache lock named `laravel:pulse:check`; if it gets it, it dispatches `IsolatedBeat`, meant for work that should happen on only one server. 3. Dispatches `SharedBeat` with the current time and a random instance id, meant for work every server should do. 4. Calls `Pulse::ingest()` to flush what the recorders captured. `--once` takes a single snapshot and exits. When the command detects Vapor (the `VAPOR_SSM_PATH` variable), it also runs once, because there is no long-lived server to monitor there. ## What the Servers recorder stores The `Servers` recorder listens to `SharedBeat` and throttles itself to one snapshot every **15 seconds** per `pulse:check` instance, using the Pulse cache store. Each snapshot records: - CPU usage and used memory as averaged aggregates (for the card's graphs); - a `system` value holding the server's display name, current CPU, used and total memory, and used and total space for each directory in `PULSE_SERVER_DIRECTORIES` (colon-separated, default `/`). CPU and memory are read through operating-system tools via `shell_exec` on Linux, macOS, Windows and BSD; on any other OS family the recorder throws. Hosts that disable `shell_exec` can plug in their own readers with `Servers::detectCpuUsing()` and `Servers::detectMemoryUsing()`. ## Naming servers | Setting | Env variable | Default | |---|---|---| | `server_name` | `PULSE_SERVER_NAME` | PHP's `gethostname()` | | `directories` | `PULSE_SERVER_DIRECTORIES` | `/` | The name becomes the key under which snapshots are stored, so **every reporting server must have a unique name**. Containers or cloned images that share a hostname appear as one server, flickering between their readings. When you retire a server, the card keeps showing it; the `ignore-after` prop, such as `<livewire:pulse.servers ignore-after="3 hours" />`, hides servers that stopped reporting. ## Running it in production - Run `pulse:check` on **every** application server you want on the card, not just one. - Keep it alive with a process monitor such as Supervisor, as the docs recommend. - Run `php artisan pulse:restart` during each deploy; it writes a new restart timestamp to the cache, and each `pulse:check` exits on its next loop, to be restarted with the new code. - Use a cache store shared by all servers, because both the restart signal and the `IsolatedBeat` lock live there; the lock only works on a store that supports locks. ## Beyond the built-in card The beat events are also the extension point for polling cards. A custom recorder can declare a `$listen` property of `SharedBeat::class` to measure something on every server, or listen to `IsolatedBeat` to poll a shared resource, such as an external API's quota, exactly once across the fleet. The built-in `Servers` recorder shows the pattern for keeping that cheap: it throttles itself so a once-per-second beat produces a snapshot at most every 15 seconds. Whatever a custom recorder captures goes through the normal `Pulse::record()` or `Pulse::set()` calls and the configured ingest, so the rest of the pipeline is unchanged.