Fleet diagnostics: check auspex health across your organization

Last updated: October 30, 2026

Fleet diagnostics shows, for each person in your organization, whether auspex is installed on their machine, whether it is running and healthy, and whether it is producing agent traces. Use it to find people whose traces are missing, and why.

Why it matters

Agent Trace metrics are only as complete as your auspex rollout. A machine where auspex was never installed, stopped running, or can't capture from a coding tool sends no traces, and the gap shows up later as lower AI usage in your reports. Fleet diagnostics lets you find those machines and fix them first.

For IT and platform admins: confirm an MDM rollout reached everyone, and find devices that need a reinstall or an upgrade.
For engineering leaders: check coverage before you rely on trace-based metrics for a team.

Before you begin

Permission: you need the Manage Integrations permission. It is the same permission that opens Settings > Integrations, where you connect integrations and check their status, and Settings > Traces. The default Owners, Admins and Integration Admins permission groups have it.
Availability: Fleet diagnostics is available to every organization. It reports on auspex devices, so it has data once auspex is deployed to at least one machine.

To open it:

In Span, go to Settings > Traces.
Click the Fleet diagnostics tab.

How it works

Data as of. A banner at the top reads Data as of a date and time, followed by the lookback it covers. That time is the earlier of your organization's latest auspex heartbeat and latest trace. Every "how long ago" on the page is measured against it, not against the current time, so a delay in data processing doesn't make your whole fleet look stale.

Heartbeats and health checks. auspex sends a regular heartbeat from each device. Each heartbeat carries the result of its health checks. Span reads these, plus each person's traces and coding activity, to give every person one status.

Working days. Day counts are working days: weekends and the person's out-of-office days don't count. For someone who isn't in Span, Span has no calendar, so their working days are weekdays in UTC.

Statuses. A device takes the worst status any of its reasons gives it. A person takes the status of their primary device (see below). The Details column lists the reasons.

Status	When it applies
Issues	A health check is persistently failing, for example Daemon is not running or Hooks are not wired. Or the person has never produced a trace, more than 3 working days after auspex was installed, while they were coding.
Stale	The device hasn't sent a heartbeat for more than 2 working days. Or the person has produced no trace for more than 7 working days while the device was sending heartbeats and the person was coding. Or the device's hooks are persistently idle while auspex is running, which means traces are being lost.
Healthy	None of the above.
Not installed	The person has no auspex device in the lookback period, other than ephemeral ones.
Ephemeral only	Shown instead of Not installed when every device the person has is ephemeral. These people are counted with Not installed.

The health checks the Details column can name are: Daemon is not running, Daemon is stuck, Hooks are not wired, Trace delivery is failing, Policy sync is failing, Heartbeat is not refreshing, Unsupported tool versions, Privacy state check is failing, Low memory headroom, Managed configuration did not converge and Git check is failing. The other reasons read, for example, Last heartbeat 3 working days ago, No traces in 4 working days active since install, despite coding activity or Hooks are idle: the daemon's liveness marker is stale.

How Span avoids false alarms.

A failing check must persist. A check counts only when it fails on the device's latest heartbeat and on more than half of the heartbeats in the 24 hours up to it, with at least 10 failing heartbeats. One-off and intermittent failures are ignored.
Upgrades start fresh. Only heartbeats from the device's current auspex version count toward a failing check.
Warnings mostly don't count. Health checks can also warn. The only warning that changes a status is hooks being idle while auspex is running, which makes the device Stale.
Missing traces count only while the person coded and the device was alive. Someone on vacation, or who didn't write code, isn't flagged. A device that stopped sending heartbeats is Stale for that reason, not for missing traces.

Primary device. A person can have several devices. The People table shows each person through one primary device: of their devices that sent a heartbeat within 3 working days of the person's latest heartbeat, the one with the worst status, with ties going to the most recent heartbeat. On one operating system, a device that reported at least an hour after all the others has replaced them (as a reinstall or a new laptop does), so only it competes. Filters and sorting apply to the primary device.

Ephemeral devices. Span treats a Linux device as ephemeral, meaning a CI runner, virtual machine or container rather than a workstation, when either of these is true:

Its whole lifetime, from install to last heartbeat, falls inside that of another of the person's devices, and that other device kept reporting on a later working day. Two devices used up to the same day are both treated as workstations.
It sent heartbeats on 5 days or fewer, and it then went silent for more than 2 working days or the person has other Linux devices like it.

An ephemeral device is never primary. It is judged only on its health checks, not on missing heartbeats or traces, because a CI runner isn't expected to produce traces. Ephemeral devices are left out of the sub-totals.

People not in Span. When auspex reports a work email that matches no person in Span, the page lists that email as its own row, marked Not in Span. These rows are judged on heartbeats and health checks only, because Span has no calendar or coding activity for them.

Using the page

The page has two tabs, People and Sub-totals.

People tab. One row per person, ordered Issues, Stale, Healthy, Ephemeral only, Not installed, then by most recent heartbeat. The summary above the table, such as "12 people · 15 devices · 3 ephemeral", counts everything that matches your filters, not only the current page. Click a column header to sort. Expand a row to see all of a person's devices: the primary device first, then other devices, then ephemeral ones.

Column	What it shows
Person	Name, email and device count, plus Not in Span when the work email matches no person in Span.
Last coding activity	The last day the person had coding activity, in their own time zone.
Last trace	The person's most recent trace, at any time. Hover to see the last trace from each AI coding tool. Never means no trace at all.
Status	The primary device's status.
Auspex version	The auspex version on the primary device.
OS	The operating system, with its version and architecture underneath.
Installed	When auspex was first seen on the device.
Last heartbeat	When the device last reported in, relative to the Data as of time.
Details	The reasons behind a Stale or Issues status. A dash means there are none.

Filters. These controls change who is in the report and which device is primary:

Lookback: Last 30 days (the default), Last 60 days or Last 90 days, counted back from the Data as of time. Devices that haven't sent a heartbeat within it are left out, so a person with no device in the lookback shows as Not installed. A person's status doesn't otherwise depend on the lookback.
Employment: Active, Terminated or Not in Span.
Dev contribution: Dev contributors, Non-contributors or Not in Span.
OS: limits the report to devices on those operating systems. Each person's primary device is chosen among their devices on them, and people with none are left out.

By default the report shows active people, whatever their dev contribution, plus people not in Span. Not in Span rows appear only while both Employment and Dev contribution include it.

On the People tab you can also Search by name or email, and filter by Status and Auspex version. To return to the defaults, click Clear filters & sorting. Your filters, sort, tab and page are saved in the page URL, so you can bookmark a view or share it with a colleague.

Sub-totals tab. Counts people and devices By status, By OS and By Auspex version, for the same filters. Use it to answer questions such as "How many Windows devices are still on an old version?"

Each person's primary device always counts. Their other devices count while they are still sending heartbeats, unless a newer device on the same operating system replaced them.
By status, each person counts once, under their own status. By OS and version, a person counts in every group that one of their counted devices is in.
Ephemeral devices aren't counted. Hover the icon next to Not installed to see how many of those people have no devices and how many are ephemeral only.

Export. On the People tab, click Export, then People (CSV) or Devices (CSV). The file holds every row that matches your filters, in the current sort, not only the current page. People (CSV) has one row per person, described through their primary device. Devices (CSV) has one row per device of those people and leaves out people with no device. The file name includes the Data as of date and the lookback.

Fix common problems

Some steps below use auspex commands on the person's machine. Run them yourself as an admin, or through your MDM.

Not installed

Deploy auspex to the person's machine with your MDM, or have them self-install it. See the IT admin guide for your MDM in Related articles.
If the person still uses Span's older coding hooks, they show as Not installed. Fleet diagnostics tracks auspex only. Move them to auspex; on Windows, see Retiring Span coding-hooks on Windows.
If the person replaced their machine more than the lookback ago and the new one never got auspex, they also show here.

Hooks are not wired

auspex reports this when its capture configuration is missing, or turned off, in one or more of the AI coding tools it supports: Claude Code, Codex, GitHub Copilot, Cursor and VS Code. That configuration is what makes each tool call auspex, so capture from an unwired tool is off. auspex checks every tool it supports, whether or not the person uses it. See the FAQ below for what it does and doesn't mean. For the full causes, a remediation script that also restarts the agent and checks the result, and how to read its output, see Hooks not wired (macOS) and Hooks not wired (Windows).

Find which tool. On the device, run auspex hooks status. It lists each supported tool's wiring state. auspex status also names the unwired tools on its capture-wiring line.
Re-place the hooks on an MDM-managed device. Re-run auspex's managed install step with administrator rights:
- macOS: re-push the auspex package from your MDM, run sudo auspex install --system --target-user <username>, or run the script in the macOS troubleshooting guide. auspex also re-runs this step automatically when a user logs in at the console.
- Windows: reinstall the auspex .msi from your MDM (each install or upgrade runs this step), run auspex install --system from an elevated prompt (Run as administrator), or run the script in the Windows troubleshooting guide.
- Linux: run sudo auspex install --system.
Don't use auspex hooks install without --system on a managed device: auspex refuses it there, because per-user hooks on top of the machine-wide ones would capture every event twice. On managed devices, the running auspex agent re-wires VS Code by itself.
Re-place the hooks on a self-installed device. As the person who uses the machine, in their own session and without sudo or Run as administrator, run auspex hooks install. It wires every supported tool and reports any tool it couldn't wire. auspex install --system doesn't apply here: it stops on a device without your MDM's managed configuration.
If a tool still won't wire, check the install log. Each managed install step records its result, including errors, in /Library/Logs/auspex/install.log on macOS and C:\ProgramData\auspex\logs\install.log on Windows. On macOS the package's own output is in /var/log/install.log; on Windows, install with msiexec /i <package>.msi /l*v install.log to capture the installer's log. A failed step also shows in Fleet diagnostics as Managed configuration did not converge. Run auspex support in the person's own session (not elevated) to create a support archive (it includes the install logs) and send it to Span support.

auspex doesn't put back missing machine-wide hooks on its own, except on macOS at the next console login, so the status stays until the step runs again. Once the device's latest heartbeat passes the check, the reason drops off at the next data refresh.

Daemon is not running or Daemon is stuck

The auspex background process starts at each login: a launch agent on macOS, a logon scheduled task on Windows. Have the person sign out and back in, or restart the machine.
If the check keeps failing, run auspex support on the device and send the archive to Span support.

Stale: no recent heartbeat

The device is offline, auspex was removed, or the machine was retired. If the person replaced their machine, the old device drops out of the report once its last heartbeat is older than the lookback.
If the machine is in use, check that auspex is still installed and that its background process is running.

Stale or Issues: no traces despite coding activity

If the device's health checks pass but traces from one tool never arrive, the tool may be ignoring auspex's hooks. For Claude Code, organization-wide remote settings can cause this; see the Claude Code Remote Settings and Managed Hooks articles for macOS and Windows.
To confirm what a device is capturing, see Verify that auspex is sending traces.

Not in Span

The work email set on the device doesn't match anyone in Span, or the person hasn't been added to Span yet. Make sure the work email your MDM passes to auspex matches the person's email in Span.

FAQ

Why do people who still use the older coding hooks show as Not installed?

Fleet diagnostics reports on auspex only. Devices that run Span's older coding hooks aren't counted, so a person with only those devices has no auspex device and shows as Not installed.

What does "Hooks are not wired" mean?

It is a health check auspex reports from the device. auspex couldn't find its configuration in one or more supported AI coding tools, such as Claude Code, Codex and Cursor, or found it turned off. Without it, those tools don't call auspex, so their activity isn't captured. It can apply to one tool or to all of them.

Does it mean the person hasn't opened a coding agent?

No. It is about the configuration on the machine, not about whether anyone used a tool. People with this check usually show Issues, and their Last trace often reads Never, even when their Last coding activity is recent.

Why does it happen?

There are three common causes. The wiring step failed during install: auspex still installs and runs when that step fails, so the device looks installed and keeps sending heartbeats. Or the hooks were wired and later removed, for example when a tool's configuration was replaced or edited. Or a tool turned its hooks off, for example Codex hooks turned off in the user's Codex config.toml, or VS Code's chat.useHooks setting set to false. To fix it, see Hooks are not wired under Fix common problems.

Things to know

The page doesn't say which tool is unwired. auspex sends only whether the wiring check passed. Run auspex hooks status on the device to see the tool.
The wiring check covers every supported tool. A tool the person never uses still has to be wired for the check to pass.
A configuration auspex can't read counts as wired. If auspex can't read a tool's configuration, the wiring check doesn't fail for that tool. auspex hooks status on the device shows that tool as unknown, with the error.
Ephemeral detection is based on reporting patterns. A short-lived Linux workstation can be classified as ephemeral, and a long-running Linux VM can be classified as a workstation.
Older coding hooks aren't tracked. Only auspex devices appear.
Traces aren't tied to a device. Last trace, the per-tool breakdown and the trace-based reasons describe the person, not a specific machine. If a person has two machines and one of them stopped capturing, traces from the other keep the trace reasons clear.
Wired doesn't always mean firing. The wiring check confirms auspex's configuration is in place on disk. A tool setting that tells the tool to ignore it, such as Claude Code remote settings, shows up as missing traces instead.

Worked example. The Data as of time is Monday 9:00. A developer's laptop last sent a heartbeat on the previous Wednesday evening. The working days since then are Thursday, Friday and Monday, so 3 working days have passed. That is more than 2, so the laptop is Stale with Last heartbeat 3 working days ago. If the developer was out of office on Thursday, only 2 working days count and the laptop stays Healthy.

Worked example: persistence. A device sent 30 heartbeats in the 24 hours up to its latest one. If 14 of them, including the latest, report Hooks are not wired, that is less than half, so the device isn't flagged. If 16 do, it is more than half and at least 10, so the device shows Issues. If the device was upgraded and has sent only 5 heartbeats on the new version, all failing, it isn't flagged yet, because fewer than 10 count.

Verify that auspex is sending traces

Understanding Agent Traces in Span (auspex)

auspex: IT Admin User Guide for Jamf Pro (macOS)

auspex: IT Admin User Guide for Microsoft Intune (Windows)

auspex: Retiring Span coding-hooks on Windows

auspex: Claude Code Remote Settings and Managed Hooks (macOS)

auspex: Claude Code Remote Settings and Managed Hooks (Windows)

auspex Issues Troubleshooting Guide (macOS)

auspex Issues Troubleshooting Guide (Windows)