Skip to main content

Troubleshooting Guide

Common Issues and Solutions​

1. SDK Cannot Read Log File​

Error:

Error opening file: permission denied

Solution:

# Check file permissions
ls -la app.log

# Fix permissions (Linux/Mac)
chmod 644 app.log
chown $(whoami) app.log

# On Windows, run terminal as Administrator

2. No Logs Being Sent​

Symptoms:

  • SDK starts but shows no activity
  • No "RECEIVED LOG BATCH" messages

Checklist:

  • Is AMPLISERV_LOG_PATH correct?
  • Is your app writing to the log file?
  • Are logs in JSON format?
  • Is the log file accessible?

Debug:

# Enable debug logging
export AMPLISERV_LOG_LEVEL="debug"

# Check if file is being tailed
tail -f app.log  # Should show new logs

3. JSON Parsing Errors​

Error in SDK terminal:

invalid character 's' looking for beginning of value

Cause: Log file contains non-JSON content

Solution:

// Ensure your logs are valid JSON
// ✅ Correct
{"level":"INFO","message":"Hello"}

// ❌ Incorrect
INFO: Hello

4. Connection Errors​

Error:

Failed to send batch: connection refused

Solutions:

Check endpoint:

curl -X POST https://your-endpoint/v1/ingest/logs \
  -H "Authorization: Bearer $AMPLISERV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Check network:

# Test connectivity
ping ingest.ampliserv.io
telnet ingest.ampliserv.io 443

5. 401 Unauthorized Errors​

Error:

API returned error 401: Unauthorized

Solution:

# Verify API key is correct
echo $AMPLISERV_API_KEY

# Ensure key is active in AmpliServ dashboard
# Generate new key if needed

6. High Memory Usage​

Symptoms:

  • SDK uses excessive memory
  • System becomes slow

Solutions:

# Reduce batch size
export AMPLISERV_BATCH_SIZE="25"

# Reduce flush interval
export AMPLISERV_FLUSH_INTERVAL_SEC="2"

# Restart agent
killall ampliserv-agent
./ampliserv-agent

7. Logs Are Truncated​

Issue: Long log lines are cut off

Solution: Increase buffer size (SDK v1.5+ supports this)

8. Duplicate Logs​

Issue: Same log appears multiple times

Cause: Multiple SDK instances tailing same file

Solution: Run only one SDK instance per log file

9. Stack Traces Not Visible​

Issue: Errors appear but no stack traces

Solution: Ensure your application captures stack traces:

Java:

logger.error("Error", exception);  // Pass exception as second param

Node.js:

logger.error({ message: err.message, stack: err.stack });

Python:

logger.exception("Error occurred")  # Automatically includes stack trace

10. Correlation ID Not Propagating​

Issue: Correlation ID missing in logs

Solutions:

Check MDC setup (Java):

MDC.put("correlation_id", correlationId);
// Ensure MDC is cleared after request

Check child logger (Node.js):

const childLogger = logger.child({ correlation_id: correlationId });

Debug Mode​

Enable debug logging for detailed output:

export AMPLISERV_LOG_LEVEL="debug"
./ampliserv-agent

Debug output includes:

  • File tailing status
  • Parsed log entries
  • Batch assembly
  • HTTP request/response details

Getting Support​

If issues persist:

Collect logs:

./ampliserv-agent --debug > sdk-debug.log 2>&1

Check versions:

./ampliserv-agent --version

Open an issue with:

  • SDK version
  • OS and architecture
  • Complete error output
  • Sample log line
  • Configuration (redacted API key)

Quick Diagnostic Script​

#!/bin/bash
echo "=== AmpliServ SDK Diagnostic ==="
echo "SDK Version: $(./ampliserv-agent --version 2>/dev/null || echo 'Not found')"
echo "Log File: $AMPLISERV_LOG_PATH"
echo "Log File Exists: $([ -f "$AMPLISERV_LOG_PATH" ] && echo "Yes" || echo "No")"
echo "Log File Readable: $([ -r "$AMPLISERV_LOG_PATH" ] && echo "Yes" || echo "No")"
echo "Endpoint: $AMPLISERV_ENDPOINT"
echo "Service: $AMPLISERV_SERVICE_NAME"
echo "Environment: $AMPLISERV_ENV"
echo "Last 5 log lines:"
tail -5 "$AMPLISERV_LOG_PATH" 2>/dev/null || echo "Cannot read log file"

Run with:

chmod +x diagnose.sh
./diagnose.sh