Troubleshooting
Start here when telemetry is missing or a collector looks offline. The flowchart below isolates an ingestion failure to one of three places, the edge firewall, the local buffer, or the SaaS rate limiter, so you debug the right tier instead of guessing. Tier-specific playbooks then take over.
For quick answers to common questions, see the FAQ. If you are still stuck after the playbooks below, Support & Contact has how to reach the TechForcz team.
Isolating an ingestion failure
The three-way split in one line: firewall problems show as no heartbeat plus failing DNS, egress, or NTP; local buffer problems show as a growing JetStream backlog while the WAN is down (self-healing on reconnect); rate limiter problems show as HTTP 429 with local data fresh and the link up.
Playbooks
| Symptom class | Go to |
|---|---|
| Network drops, local buffer overflow, TLS handshake failures, collector services down | Data Collector Troubleshooting |
| Ingestion throttling, API rate limits, webhook delivery failures, RBAC issues | SaaS Platform Troubleshooting |
Before you escalate, capture state first
# ALWAYS attach these to a case (collector side)
python3 /opt/techforcz/bin/diagnostics.py # writes /opt/techforcz/logs/diagnostics.json
docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
docker logs <implicated-container> --tail 100
A case without diagnostics, docker ps -a, and the last 100 log lines of the implicated container will be returned. The architecture context for every fault path is in Platform Architecture.