Support

Troubleshooting

Diagnose and resolve common issues with DB Audit. Find step-by-step solutions for connection problems, missing events, and more.

Quick Diagnostic Steps

Before diving into specific issues, run these quick checks to identify the problem area.

1
Check collector status

Is the collector process running? Check systemd, Docker, or Kubernetes status.

2
Review collector logs

Look for error messages indicating connection failures or configuration issues.

3
Check health endpoint

The /health/detailed endpoint shows connectivity status for databases and API.

4
Verify configuration

Run dbaudit-collector validate to check for configuration errors.

Common Issues

Connection Issues

Collector cannot connect to database

Symptoms
  • Connection timeout errors
  • Authentication failures
  • SSL/TLS handshake errors
Possible Causes
  • Incorrect credentials
  • Firewall blocking connection
  • SSL certificate issues
  • Database not accepting connections
Solutions
  • 1Verify credentials are correct and the user has required permissions
  • 2Check firewall rules allow traffic from collector to database port
  • 3For SSL issues, verify certificates are valid and paths are correct in config
  • 4Test connectivity with: `dbaudit-collector test-connection --database prod-postgres`

Collector cannot reach DB Audit API

Symptoms
  • API connection errors
  • Events not appearing in dashboard
  • Cache filling up
Possible Causes
  • Network/firewall blocking outbound HTTPS
  • Invalid API key
  • Proxy configuration missing
Solutions
  • 1Verify outbound HTTPS (443) to api.dbaudit.ai is allowed
  • 2Check API key is valid: `dbaudit-collector validate-key`
  • 3If behind proxy, set HTTPS_PROXY environment variable
  • 4Test API connectivity: `curl -I https://api.dbaudit.ai/health`

Event Capture Issues

Events not appearing in dashboard

Symptoms
  • Zero events in dashboard
  • Some queries not captured
  • Missing events for specific databases
Possible Causes
  • Database audit logging not enabled
  • Collector not running
  • Incorrect database configuration
  • Sampling filtering events
Solutions
  • 1Verify native audit logging is enabled on the database (see connector docs)
  • 2Check collector status: `systemctl status dbaudit-collector`
  • 3Review collector logs: `journalctl -u dbaudit-collector -f`
  • 4Verify database is listed in config and credentials are correct
  • 5Check if sampling is excluding events: review sampling config

Event lag or delays

Symptoms
  • Events appearing minutes after execution
  • Dashboard showing stale data
Possible Causes
  • High event volume overwhelming collector
  • Network latency to API
  • Insufficient collector resources
Solutions
  • 1Check collector buffer utilization: `curl localhost:8080/health/detailed`
  • 2Increase collector resources (CPU/memory) if buffer is frequently full
  • 3Deploy additional collectors to distribute load
  • 4Consider enabling sampling for high-volume, low-value queries

Performance Issues

High collector CPU/memory usage

Symptoms
  • Collector using excessive resources
  • OOM kills
  • System slowdown
Possible Causes
  • Very high event volume
  • Complex policy rules
  • Memory leak (rare)
Solutions
  • 1Enable sampling to reduce event volume
  • 2Increase resource limits in deployment config
  • 3Simplify complex regex patterns in policies
  • 4If memory leak suspected, check for latest collector version

Slow API queries

Symptoms
  • Dashboard loading slowly
  • API timeouts
  • Report generation failing
Possible Causes
  • Querying large time ranges
  • Missing time filters
  • Rate limit throttling
Solutions
  • 1Add time bounds to queries (use last 24h instead of all time)
  • 2Use aggregations instead of fetching raw events for dashboards
  • 3Check rate limit headers and implement backoff if needed
  • 4Contact support if consistently slow for reasonable queries

Alert Issues

Alerts not triggering

Symptoms
  • Expected alerts not firing
  • Policy violations not notifying
Possible Causes
  • Alert channel not configured
  • Policy not enabled
  • Severity threshold too high
  • Alert cooldown active
Solutions
  • 1Verify alert channel is configured and tested
  • 2Check policy is enabled and matches the events
  • 3Review severity settings on alert channel
  • 4Check if cooldown is preventing duplicate alerts
  • 5Test alert delivery: Settings > Alerts > Send Test

Too many alerts (alert fatigue)

Symptoms
  • Hundreds of alerts per day
  • Important alerts buried in noise
Possible Causes
  • Thresholds too sensitive
  • Missing exclusions for known patterns
  • Baseline not tuned
Solutions
  • 1Increase thresholds for noisy alert rules
  • 2Add exclusions for known-good patterns (e.g., monitoring queries)
  • 3Enable anomaly detection to reduce false positives
  • 4Use alert aggregation to batch similar alerts

Diagnostic Commands

Systemd (Linux)

# Check collector service status
systemctl status dbaudit-collector

# View collector logs (last 100 lines)
journalctl -u dbaudit-collector -n 100

# Follow logs in real-time
journalctl -u dbaudit-collector -f

# Check collector health endpoint
curl -s localhost:8080/health/detailed | jq

# Validate configuration
dbaudit-collector validate --config /etc/dbaudit/config.yaml

# Test database connectivity
dbaudit-collector test-connection --database prod-postgres

# Test API connectivity
dbaudit-collector test-api

Docker

# Check container status
docker ps -a | grep dbaudit

# View container logs
docker logs dbaudit-collector --tail 100 -f

# Execute commands inside container
docker exec -it dbaudit-collector /bin/sh

# Check health inside container
docker exec dbaudit-collector curl -s localhost:8080/health/detailed

# Restart container
docker restart dbaudit-collector

Kubernetes

# Check pod status
kubectl get pods -l app=dbaudit-collector

# Describe pod for events
kubectl describe pod -l app=dbaudit-collector

# View pod logs
kubectl logs -l app=dbaudit-collector --tail 100 -f

# Check resource usage
kubectl top pod -l app=dbaudit-collector

# Execute into pod
kubectl exec -it deploy/dbaudit-collector -- /bin/sh

# Check configmap
kubectl get configmap dbaudit-config -o yaml

Network Diagnostics

# Test outbound connectivity to DB Audit API
curl -v https://api.dbaudit.ai/health

# Test database connectivity
nc -zv your-database.example.com 5432

# Check DNS resolution
nslookup api.dbaudit.ai

# Test with proxy (if configured)
HTTPS_PROXY=http://proxy:8080 curl -v https://api.dbaudit.ai/health

# Check listening ports
netstat -tlnp | grep dbaudit

Error Codes Reference

Common error codes you may encounter in collector logs and their meanings.

CodeDescriptionAction
CONN_TIMEOUTConnection to database timed outCheck network path and firewall rules
AUTH_FAILEDDatabase authentication failedVerify credentials in config file
SSL_HANDSHAKESSL/TLS handshake failedCheck certificate validity and paths
API_UNAUTHORIZEDInvalid or expired API keyRegenerate API key in dashboard
API_RATE_LIMITAPI rate limit exceededImplement exponential backoff
BUFFER_FULLEvent buffer capacity reachedIncrease buffer size or add collectors
CACHE_FULLLocal cache capacity reachedIncrease cache size or check API connectivity
PARSE_ERRORFailed to parse audit log entryCheck database audit log format

Still Need Help?

If you're still experiencing issues after following this guide, our support team is here to help.

Contact SupportReport IssueBrowse Docs