Troubleshooting

Troubleshooting Agent Behavior

Start in the SparkLogs app

Open Configure > Agents and select the agent. The detail pane reports what the agent last sent, so it also shows whether the agent is reporting at all.

• Connectivity: Online, or offline with a last-contact time. Distinguishes a failure from Device shut down, Agent service stopped, and Registered, never checked in.
• Collection health: feeds current, behind, starting up, or needing attention. Independent of connectivity; an online agent can be collecting nothing.
• Reported issue: the agent's own account of what is wrong, with a next step.
• Data feeds: per-feed status, which isolates one stuck feed from a broadly unhealthy agent.
• System Details: agent version and data feed pack version.

For a full tour see Agent detail.

Use the local logs below when the app cannot answer the question: the agent has never checked in, its last report is stale, or the cause is on the endpoint.

Troubleshooting with Agent Logs

The agent writes two logs under %ProgramData%\SparkLogs\agent\logs\:

File	Contents	subsource LQL field value
agent.log	Registration, check-ins, policy, updates, and collector supervision. Start here.	sparklogs.agent.log
vector-YYYY-MM-DD-HH.log	Collector diagnostics, one file per hour. Use when a specific feed produces no data.	sparklogs.agent.vector

Local read requires elevation (protected agent\ DACL); standard users cannot browse this path.

When an agent is able to ship data to SparkLogs, both logs are shipped and you can inspect them within SparkLogs itself. To read both for one agent, filter on its agent ID (copy from the agent details pane). For example:

agent_id="658aa664-215e-4611-8e93-d2ffedb922ef" subsource in (sparklogs.agent.log, sparklogs.agent.vector)

If the agent is unhealthy and not shipping data, inspect the files locally with an elevated shell or RMM running as SYSTEM.

Troubleshooting with Agent Windows Event Logs

The agent writes a curated set of significant events to the Windows Event Log Application channel, SparkLogs Agent source. This is not a copy of agent.log: a transient failure the agent recovers from on its own stays in agent.log. Treat the Event Log as the alerting surface and agent.log as the diagnostic one.

Event IDs are banded by consequence to the machine, not by severity to the agent:

ID range	Level	Meaning
1000-1099	Information	Normal lifecycle milestones, such as the service starting or an update applying.
2000-2099	Warning	The agent needs attention or is degraded, but the machine is fine. Includes operator-initiated states, such as the agent being deleted in the SparkLogs app.
3000-3099	Error	Collection has stopped and a person has to intervene, such as revoked credentials or a fatal startup failure.

Alert on the band, not on individual IDs. IDs within a band may be added or renumbered; the boundaries and their meanings are stable.

You can view these in the Windows Event Viewer, or read them from your own tooling. To surface anything that has stopped collection on a host:

Get-WinEvent -FilterHashtable @{LogName='Application'; ProviderName='SparkLogs Agent'} |
  Where-Object { $_.Id -ge 3000 } |
  ForEach-Object { "{0}  {1}  {2}" -f $_.TimeCreated, $_.Id, $_.Message }

Drop the Where-Object filter to see every event the agent has written.

Agent status: waiting for its data feed pack

The Agents list can show an enrolled agent as waiting for its data feed pack. Classic Windows Event Log channels are not collected until the agent downloads its data feed pack, which describes what to collect and how. On a healthy install this clears almost immediately; if it is still shown after about an hour, check the endpoint's outbound HTTPS (port 443) access to the SparkLogs cloud; see Blocked outbound 443.

Troubleshooting Install Issues

Install logs

When you run a silent EXE or MSI install with /l*v %TEMP%\SparkLogsAgent-install.log, the verbose log lands at:

%TEMP%\SparkLogsAgent-install.log

If you did not specify a log file, a default log file will be in %TEMP% with the name MSI[RANDOM].log.

Certain types of failures (invalid registration token) will also be logged to the Windows Event Log Application channel, SparkLogs Agent source.

Common failures

• Bad or expired token. The registration token is wrong, revoked, or past its expiry. Issue a fresh token in Configure > Agents and re-run.
• Hash mismatch. If the downloaded file does not match the expected SHA-256 then do not proceed; re-download and re-verify.
• Blocked outbound 443. The endpoint cannot reach the SparkLogs cloud over TLS 443. The agent makes only outbound connections; allow outbound 443 and retry.

PowerShell does not wait on the installer

If you are running the installer from a script, you may need to wait on the installer to finish and check whether or not it was successful.

PowerShell does not block on a GUI process such as the installer or msiexec. If you run the installer bare from a PowerShell prompt (.\SparkLogsAgentSetup.exe /qn ... or msiexec /i ... /qn) then the command will return right away, before the install finishes, and $LASTEXITCODE will not hold the installer's result. A script that tests $LASTEXITCODE on the next line reads a stale or empty value and treats a failed install as a success.

Run the installer through Start-Process -Wait -PassThru and read the exit code from the returned object. -Wait blocks until the install finishes; -PassThru hands back the process object so $p.ExitCode carries the real result (0, 3010, or 1641 on success). For example:

$p = Start-Process $env:TEMP\SparkLogsAgentSetup.exe -Wait -PassThru -ArgumentList '/qn /norestart EULA=ACCEPT REGISTRATION_TOKEN=us_97... USEPARENTORG=1'
$p.ExitCode

For an MSI install, wrap msiexec the same way:

$p = Start-Process msiexec -Wait -PassThru -ArgumentList '/i','SparkLogsAgentSetup-x64-1.9.10.msi','/qn','/norestart','EULA=ACCEPT','REGISTRATION_TOKEN=us_97...','USEPARENTORG=1','/l*v',"$env:TEMP\SparkLogsAgent-install.log"
$p.ExitCode

The exit code is only available in the session that ran the install. For fleet presence checks, detect by the Windows service instead.

Detect by service, not MSI product code

For detection rules (RMM, Intune), check the Windows service. The MSI product code (GUID) changes across versions, so it is not a reliable presence check:

if (Get-Service "SparkLogsAgent" -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }

See Manage and verify agents for the Agents list and last-seen freshness.