AmpliServ SDK Configuration Reference

Environment Variables

Required Variables

Variable	Type	Description	Example
AMPLISERV_API_KEY	string	API key for authentication	ak_xxxxx
AMPLISERV_LOG_PATH	string	Path to log file to tail	/var/log/app.log

Optional Variables

Variable	Type	Default	Description
AMPLISERV_ENDPOINT	string	https://ingest.ampliserv.io/v1/ingest/logs	API endpoint URL
AMPLISERV_SERVICE_NAME	string	unknown-service	Name of your service
AMPLISERV_ENV	string	prod	Environment (dev/staging/prod)
AMPLISERV_BATCH_SIZE	int	50	Number of logs per batch
AMPLISERV_FLUSH_INTERVAL_SEC	int	5	Flush interval in seconds
AMPLISERV_INCIDENT_ENABLED	bool	true	Enable incident detection
AMPLISERV_COLLECTOR_MODE	string	file	Collector mode
AMPLISERV_LOG_LEVEL	string	info	SDK log level
AMPLISERV_FLUENT_BIT_PORT	int	0	Port for Fluent Bit input

Collector Modes

File Mode

export AMPLISERV_COLLECTOR_MODE="file"
export AMPLISERV_LOG_PATH="/path/to/app.log"

Docker Mode

export AMPLISERV_COLLECTOR_MODE="docker"
# Automatically discovers containers at /var/lib/docker/containers

Kubernetes Mode

export AMPLISERV_COLLECTOR_MODE="k8s"
# Tails logs from /var/log/containers/*.log

Auto Mode

export AMPLISERV_COLLECTOR_MODE="auto"
# Auto-detects environment (K8s > Docker > File)

Docker Deployment

docker run -d \
  -e AMPLISERV_API_KEY="your-api-key" \
  -e AMPLISERV_COLLECTOR_MODE="docker" \
  -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
  -v /var/log:/var/log:ro \
  ampliserv/agent:latest

Kubernetes Deployment (DaemonSet)

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: ampliserv-agent
spec:
  template:
    spec:
      containers:
      - name: agent
        image: ampliserv/agent:latest
        env:
        - name: AMPLISERV_API_KEY
          valueFrom:
            secretKeyRef:
              name: ampliserv-secrets
              key: api-key
        - name: AMPLISERV_COLLECTOR_MODE
          value: "k8s"
        volumeMounts:
        - name: varlog
          mountPath: /var/log
          readOnly: true
      volumes:
      - name: varlog
        hostPath:
          path: /var/log

Log Format Requirements

The SDK expects JSON logs with the following fields:

{
  "timestamp": "2026-03-23T10:30:45.123Z",
  "level": "INFO|WARN|ERROR|DEBUG",
  "message": "Log message",
  "correlation_id": "optional-uuid",
  "stack_trace": "optional-stack-trace"
}

Enriched Fields Added by SDK

Field	Description
agent_id	Unique agent identifier
agent_version	SDK version
host	Hostname where agent runs
container_id	Docker container ID (Docker/K8s mode)
container_name	Container name (Docker/K8s mode)
pod_name	Kubernetes pod name (K8s mode)
namespace	Kubernetes namespace (K8s mode)
node_name	Kubernetes node name (K8s mode)

Incident Detection Configuration

Default Rules

Rule	Trigger	Severity	Cooldown
Panic Detection	panic:, fatal error:	CRITICAL	1 minute
Error Spike	10 errors in 1 minute	HIGH	1 minute

Custom Rules (Coming Soon)

incident_rules:
  - name: "High Error Rate"
    pattern: "ERROR"
    threshold: 20
    window_seconds: 60
    severity: "HIGH"

Performance Tuning

Batch Size vs Memory

Batch Size	Memory Usage	Network Efficiency
10	Low	Low
50 (Default)	Medium	Medium
100	High	High
500	Very High	Very High

Flush Interval vs Latency

Interval	Log Latency	Network Calls
1 second	Very Low	Very High
5 seconds (Default)	Low	Medium
30 seconds	Medium	Low
60 seconds	High	Very Low

Troubleshooting Configuration

Enable debug logging:

export AMPLISERV_LOG_LEVEL="debug"

Check configuration:

./ampliserv-agent --version
./ampliserv-agent --help

View agent logs:

# SDK logs appear in the terminal where agent runs
# Check for connection errors or parsing issues