Shipper Troubleshooting

Common issues and solutions for the Nadi Shipper agent.

Diagnostic Commands

Check Version

shipper --version

Validate Configuration

shipper --config /path/to/nadi.yaml --validate

Test Connection

shipper --config /path/to/nadi.yaml --test

Check Status

shipper --config /path/to/nadi.yaml --status

Verbose Mode

shipper --config /path/to/nadi.yaml --record --verbose

Common Issues

Logs Not Being Sent

1. Check Log Files Exist

ls -la /var/log/nadi/

Expected: Files like nadi-2024-01-15.log

If empty:

• Verify your SDK is writing logs
• Check SDK's storage_path matches Shipper's storage

2. Check Shipper is Running

# systemd
systemctl status shipper

# supervisord
supervisorctl status shipper

# Process check
ps aux | grep shipper

3. Check Configuration

shipper --config /path/to/nadi.yaml --validate

4. Check Tracker File

cat /var/log/nadi/tracker.json

The tracker shows what's been processed.

Permission Errors

"Permission denied" Reading Logs

# Check file permissions
ls -la /var/log/nadi/

# Fix permissions
sudo chown shipper:shipper /var/log/nadi
sudo chmod 755 /var/log/nadi

"Permission denied" Writing Tracker

# Shipper user needs write access
sudo chown shipper:shipper /var/log/nadi

SELinux Issues (RHEL/CentOS)

# Check SELinux status
getenforce

# Temporarily disable
sudo setenforce 0

# Permanent fix
sudo semanage fcontext -a -t var_log_t "/var/log/nadi(/.*)?"
sudo restorecon -Rv /var/log/nadi

Connection Errors

"Connection refused"

1. Check network connectivity:

   curl -I https://nadi.pro/api/health

2. Check firewall:

   # Allow outbound HTTPS
   sudo ufw allow out 443/tcp

3. Check proxy settings:

   echo $HTTP_PROXY
   echo $HTTPS_PROXY

"Connection timeout"

Increase timeout in configuration:

nadi:
  timeout: 2m  # Increase from default 1m

"SSL certificate error"

# Update CA certificates
sudo apt-get update && sudo apt-get install ca-certificates

# Or (CentOS)
sudo yum update ca-certificates

Authentication Errors

"Invalid API Key"

1. Verify API key in configuration:

   nadi:
     apiKey: your-api-key

2. Check for whitespace/formatting issues

3. Regenerate API key in Nadi dashboard

4. Test directly:

   curl -H "Authorization: Bearer YOUR_API_KEY" \
        https://nadi.pro/api/health

"Application Not Found"

1. Verify application key:

   nadi:
     token: your-app-key

2. Check application exists in Nadi dashboard

3. Ensure app key matches the application

Storage Path Issues

"Storage path not found"

# Create directory
sudo mkdir -p /var/log/nadi

# Set ownership
sudo chown www-data:www-data /var/log/nadi

"No logs found in storage"

1. Check SDK configuration matches:

   // Laravel config/nadi.php
   'storage_path' => '/var/log/nadi',

2. Verify SDK is writing:

   # Trigger a test error, then check
   ls -la /var/log/nadi/

Memory Issues

High Memory Usage

Reduce batch size:

nadi:
  batchSize: 50  # Reduce from default 100

Out of Memory

1. Check for stuck processes:

   ps aux | grep shipper

2. Restart with limits:

   # systemd
   [Service]
   MemoryLimit=100M

Duplicate Events

If you're seeing duplicate events:

1. Check tracker file:

   cat /var/log/nadi/tracker.json

2. Reset tracker:

   rm /var/log/nadi/tracker.json

   WARNING

   This will re-send all existing logs

3. Clear old logs first:

   rm /var/log/nadi/nadi-*.log
   rm /var/log/nadi/tracker.json

Service Won't Start

systemd

# Check status
systemctl status shipper

# Check logs
journalctl -u shipper -n 50

# Common fixes
sudo systemctl daemon-reload
sudo systemctl restart shipper

supervisord

# Check status
supervisorctl status shipper

# Check logs
tail -f /var/log/shipper.log

# Restart
supervisorctl restart shipper

Log Analysis

Check Shipper Logs

# systemd
journalctl -u shipper -f

# supervisord
tail -f /var/log/shipper.log

# Manual
tail -f /var/log/shipper.log

Common Log Messages

Message	Meaning	Action
Starting shipper...	Normal startup	None
Connected to Nadi	Connection successful	None
Batch sent: 100 events	Events delivered	None
Retry attempt 1/3	Temporary network issue	Wait
Authentication failed	Bad credentials	Check keys
Storage path not accessible	Permission issue	Fix permissions

Enable Debug Logging

nadi:
  logLevel: debug
  verbose: true

Or via command line:

shipper --record --verbose

Performance Issues

Slow Delivery

1. Increase batch size:

   nadi:
     batchSize: 200

2. Decrease flush interval:

   nadi:
     flushInterval: 5s

3. Enable compression:

   nadi:
     compress: true

High CPU Usage

1. Increase flush interval:

   nadi:
     flushInterval: 30s

2. Reduce verbose logging:

   nadi:
     logLevel: warn
     verbose: false

Getting Help

If you're still having issues:

1. Collect diagnostics:

   shipper --version
   shipper --config /path/to/nadi.yaml --validate
   shipper --config /path/to/nadi.yaml --test
   ls -la /var/log/nadi/
   cat /var/log/nadi/tracker.json

2. Check logs:

   journalctl -u shipper -n 100

3. Contact support: Email [email protected] with:

   • OS and version
   • Shipper version
   • Configuration (redact keys)
   • Error messages
   • Log output