Skip to main content

Troubleshooting

Troubleshooting Agent Behavior​

Troubleshooting with Agent Logs​

The agent logs all activity to %ProgramData%\SparkLogs\agent\logs\agent.log. Local read requires elevation (protected agent\ DACL); standard users cannot browse this path. When an agent is able to ship data to SparkLogs, this log file will be shipped and you can inspect the logs within SparkLogs itself. If the agent is unhealthy and not shipping data, inspect the log file locally with an elevated shell or RMM running as SYSTEM.

Troubleshooting with Agent Windows Event Logs​

The agent writes all warnings and errors to the Windows Event Log Application channel, SparkLogs Agent source. You can view the logs in the Windows Event Viewer. You can also use the Windows Event Log API to read the logs from your application. For example:

$logs = Get-WinEvent -FilterHashtable @{LogName='Application'; ProviderName='SparkLogs Agent'}
$logs | ForEach-Object { Write-Host $_.Message }

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.6.0.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.