Start at the top and work down. Most problems are answered in the first two steps.
- Is the service running?
sc.exe query dplens - What does the console say? The health indicator, then Overview.
The service will not start
Check Windows Logs → System for the Service Control Manager's record, then check the configuration:
"C:\Program Files\DPLens\dplens.exe" --validate-only --config "C:\ProgramData\DPLens\config\agent.yaml"
| Cause | Fix |
|---|---|
| The configuration file is invalid | The validator names the problem. Fix and start again. |
| The configuration file is unreadable | Check permissions with icacls C:\ProgramData\DPLens\config |
| The state folder was written by a newer version | The machine ran a newer build before. Install that version, or uninstall with REMOVE_STATE=1 and start fresh. |
| The program file is missing or damaged | Repair: msiexec /f dplens.msi /qn |
The console will not open
| Symptom | Cause | Fix |
|---|---|---|
| Connection refused | The console is switched off, or on a different port | Check settings.ui in the configuration file |
| Connection refused from another machine | Remote access is off — the default | Turn it on and set allowed networks in Settings → General |
| Connection refused from another machine, remote access on | The address is not in the allow-list, or the firewall blocks it | Check the list, then the firewall |
| Certificate warning | The self-signed certificate | Expected. Install your own. |
| Sign-in rejected | Wrong password, or locked out after repeated attempts | Wait, or reset: dplens.exe --set-admin-password |
Nothing is being collected
Is the agent licensed?
Settings and audit → Licence. Unlicensed, or past the grace period, the console runs and everything is configurable but no events flow. See Licensing.
Is the pipeline enabled?
A new installation ships with its pipeline switched off deliberately. Check the switch on Pipeline.
Is the source healthy and producing?
On Sources, check the health chip and the rate.
| Source | Common cause of silence |
|---|---|
| Windows Event Log | The channel is genuinely quiet, or is not enabled in Windows. Check it in Event Viewer. |
| Windows Event Log | Read events already in the log is off and nothing new has happened. Expected. |
| Log file | The path matches nothing. Check for typos and wildcards. |
| Log file | The service account cannot read the path. Check permissions. |
| Log file on a share | Access was granted to the service account rather than the computer account |
| Syslog / NetFlow | The firewall is blocking the port |
| Syslog / NetFlow | The sender is not in Allowed networks |
| File integrity | Nothing has changed since the last scan. Expected. |
Is a filter dropping everything?
The funnel on Overview shows each stage's in and out. A stage with events in and none out is doing exactly what you told it.
Events are collected but not arriving
Check the Destinations page.
Cached backlog
The agent cannot deliver and is queueing on disk.
| Check | |
|---|---|
| Address and port | Typos, and the wrong port for the transport |
| Firewall | Outbound to that address and port |
| The receiver | Is it running and accepting? |
| TLS | Does the certificate validate? Is ca_file right? Does the name match? |
| Splunk HEC | Is the token valid and the endpoint enabled? |
Once you fix it, the queue drains automatically. Those events appear on Live stream tagged as replayed.
Delivering, but nothing in your SIEM
The events are leaving, so the problem is downstream.
| Check | |
|---|---|
| Format | Does the receiver expect what you are sending? Watch Live stream to see the exact bytes. |
| Framing | On TCP or TLS, the wrong framing makes records run together or truncate. Try the other setting. |
| Index and sourcetype | For Splunk, data lands somewhere your searches do not look |
| Time | Events with an unexpected timestamp land outside the window you are searching |
Something is being dropped
Every drop is counted and attributed on Overview.
| Counter | Meaning | What to do |
|---|---|---|
| Filtered | A filter rule dropped it | Intended, if the rule is right |
| Aggregated | Collapsed into a representative | Intended |
| Rate limited | The cap was exceeded | Raise the cap, or accept it |
| Cache full | The queue hit its cap and your policy is to drop | Increase the cache, or change the policy |
| Group limit reached | More distinct aggregation groups than the maximum | Raise the maximum, or group by fewer fields |
| Decode failures | A malformed message arrived at a receiver | Check the sending device |
| Missing template | NetFlow records arrived before their template | Usually settles; if it persists, check the exporter |
A component is quarantined
It failed repeatedly and was stopped so it could not affect the rest. Fix the cause, then re-enable it — pause and resume from its row, or apply a configuration change.
Turn on the diagnostics file to find out why it failed. See Logs and health.
Disk is filling
Caches are the only thing that grows without bound if a destination stays down, and they are capped.
- Settings and audit → Resources shows total cache and per destination.
- Fix the unreachable destination, and the cache drains.
- If you cannot, reduce that destination's cache size, or change what happens when it fills.
- Set Keep free on the volume so a cache cannot take the last of the disk.
The diagnostics file is bounded by size limit × files kept, so it cannot be the cause unless configured very large.
Performance
| Symptom | Likely cause | What to try |
|---|---|---|
| High CPU | Message rendering on a busy channel | Turn rendering off unless your receiver needs it |
| High CPU | Complex patterns in filter or mask rules on high volume | Filter at the source instead — an event never read costs nothing |
| Falling behind | The destination cannot keep up | Check whether acknowledgement is on; it trades throughput for a guarantee |
| Falling behind | One pipeline paced by a slow destination | Give the slow one its own pipeline so it cannot hold up the others |
Getting help
Have ready:
- The DPLens version, at the foot of the console's navigation panel.
- Your Windows version.
agent.yaml, with secret handles left as handles — they contain no values, so the file is safe to share.- What the console shows: health, the funnel, the destination card.
- The diagnostics file for the period, if you can reproduce the problem with capture on.
Never send a licence key, a password, or the contents of the secret store. No support question needs them.