Skip to main content

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. An offline agent reads Device shut down, Agent service stopped or Registered, never checked in when one of those explains it.
  • Collection health: feeds current, behind, starting up, or needing attention. An online agent can still 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. What agent status, feed health and missed events mean: Collection health.

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.

The agent's log files​

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

FileContentssubsource LQL field value
agent.logRegistration, check-ins, policy, updates, and collector supervision. Start here.sparklogs.agent.log
vector-YYYY-MM-DD-HH.logCollector 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.

The agent's Windows Event Log entries​

The agent writes a curated set of significant events to the Windows Event Log Application channel, SparkLogs Agent source. A transient failure that the agent recovers from on its own stays in agent.log and is not written here. Alert on the Event Log, and diagnose with agent.log.

Event ID ranges follow what the event means for the machine:

ID rangeLevelMeaning
1000-1099InformationNormal lifecycle milestones, such as the service starting or an update applying.
2000-2099WarningThe 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-3099ErrorCollection 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.

Install problems​

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.

Some failures, such as an invalid registration token, are also 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 new token in Configure > Agents and run the install again.
  • Hash mismatch. The downloaded file does not match the expected SHA-256. Do not install it. Download it again and verify it again.
  • Blocked outbound 443. The endpoint cannot reach the SparkLogs cloud over TLS 443. Allow outbound 443 and retry.

PowerShell does not wait on the installer​

A script that runs the installer has to wait for it to finish and then check its exit code.

PowerShell does not block on a GUI process such as the installer or msiexec. Run directly from a PowerShell prompt, as .\SparkLogsAgentSetup.exe /qn ... or msiexec /i ... /qn, the command returns right away, before the install finishes. $LASTEXITCODE does 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 returns the process object, so $p.ExitCode holds 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','SparkLogsAgent-x64-1.14.13.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.