Troubleshooting
Start from the visible symptom, preserve useful evidence, and follow the shortest diagnostic path.
Start with what you can observe, not the cause you suspect.
Before changing configuration, record:
- organization, project, and region (US or EU);
- exact timestamp and timezone;
- affected object or job ID;
- last successful time;
- workflow, plus environment and release tags;
- integration, SDK, and version;
- exact error message without secrets.
Changing several settings before preserving this context makes intermittent problems harder to diagnose.
Choose the symptom
| What you observe | Diagnostic guide |
|---|---|
| No run appears after instrumentation | Traces are not arriving |
| You need to prove the installed SDK and key work | SDK Doctor local and probe modes |
| A trace import failed, stalled, or produced unexpected results | Troubleshoot imports |
| OAuth fails, the wrong account is connected, or a resource is missing | Troubleshoot connections and permissions |
| An alert did not notify its destination | Create and troubleshoot an alert |
| An Eval was not assigned or remains incomplete | Add human and AI reviewers |
| A coding agent or tracker did not receive the fix brief | Review and hand off a fix |
| Evidence is missing from an investigation | Investigate a failure |
Diagnose in layers
Use this order:
- Scope: correct organization, project, environment, and time range.
- Object state: enabled rule, running job, open batch, or completed trace.
- Credentials: correct key type, account, region, endpoint, and expiration.
- Permissions: Neatlogs organization and project role plus external provider access. A view-only notice on a settings page means the action needs a higher role.
- Delivery path: application, exporter, network, ingestion, processing, and destination.
- Evidence: logs, history, IDs, and the last successful comparable action.
Stop when you find the first failed layer. Later symptoms often disappear once the earlier boundary is corrected.
Preserve safety while testing
- Use a non-production trace or test destination where possible.
- Do not paste credentials into logs, comments, screenshots, or support messages.
- Avoid repeatedly starting imports when source load is a concern.
- Record the original error before reconnecting or rotating credentials.
- Do not broaden permissions merely to see whether a workflow starts working.
When to contact support
Contact support at neatlogs-support@neatlogs.com after the relevant guide does not resolve the problem, or immediately for suspected data exposure, security impact, or widespread production outage.
Send the smallest reproducible context rather than complete customer payloads.