AmpliServ Backend SDK Integration Guide

Overview

The AmpliServ Backend SDK enables seamless log collection, enrichment, and transmission from your backend applications to the AmpliServ observability platform. The SDK provides automatic log tailing, batch processing, incident detection, and correlation ID propagation.

Architecture

┌─────────────────┐       ┌──────────────┐       ┌─────────────────┐       ┌─────────────┐
│ Your Backend    │────▶│ app.log      │────▶│ AmpliServ SDK │────▶│ AmpliServ │
│ Application     │       │ (JSON logs)  │       │ Agent           │       │ Cloud       │
└─────────────────┘       └──────────────┘       └─────────────────┘       └─────────────┘
                                                                                 │
                                                                                 ▼
                                                                           ┌─────────────┐
                                                                           │ Kibana/     │
                                                                           │ Grafana     │
                                                                           └─────────────┘

Key Features

Feature	Description
Automatic Log Collection	Tails log files in real-time
JSON Log Parsing	Extracts structured data from JSON logs
Batch Processing	Groups logs into batches for efficient transmission
Incident Detection	Detects error spikes and panic patterns
Correlation ID Support	Preserves request tracing across services
Multiple Deployment Modes	File, Docker, Kubernetes, Fluent Bit
Retry with Backoff	Automatic retry on transmission failures

Quick Start

1. Configure Your Backend for JSON Logging

Your application must output logs in JSON format to a file. The SDK will tail this file.

2. Download the AmpliServ Agent

# Download the appropriate binary for your OS
# Windows: ampliserv-agent.exe
# Linux: ampliserv-agent
# macOS: ampliserv-agent

3. Configure Environment Variables

# Required
export AMPLISERV_API_KEY="your-api-key"
export AMPLISERV_LOG_PATH="/path/to/your/app.log"

export AMPLISERV_ENDPOINT="https://ingest.ampliserv.io/v1/ingest/logs"
export AMPLISERV_SERVICE_NAME="your-service-name"
export AMPLISERV_ENV="production"
export AMPLISERV_BATCH_SIZE="50"
export AMPLISERV_FLUSH_INTERVAL_SEC="5"
export AMPLISERV_INCIDENT_ENABLED="true"

4. Run the SDK Agent

./ampliserv-agent

Supported Frameworks

Framework	Integration Guide
Java / Spring Boot	View Guide →
Python / Django / Flask	View Guide →
Node.js / Express.js	View Guide →
.NET Core / C#	View Guide →
C++	View Guide →

Deployment Modes

File Mode (Default)

Tails a specific log file on the filesystem.

Docker Mode

Automatically discovers and tails logs from Docker containers.

Kubernetes Mode

Tails logs from /var/log/containers/*.log with pod metadata extraction.

Fluent Bit Mode

Accepts logs via HTTP from Fluent Bit sidecar.

Log Format Requirements

The SDK expects logs in JSON format with the following structure:

{
  "timestamp": "2026-03-23T10:30:45.123Z",
  "level": "ERROR",
  "message": "Error message here",
  "correlation_id": "uuid-here",
  "stack_trace": "Optional stack trace",
  "service": "your-service",
  "environment": "production"
}

What the SDK Adds

When the SDK processes your logs, it enriches them with:

Field	Description
agent_id	Unique identifier of the SDK agent
agent_version	Version of the SDK
host	Hostname where the agent runs
container_id	Docker container ID (if applicable)
pod_name	Kubernetes pod name (if applicable)
namespace	Kubernetes namespace (if applicable)

Incident Detection Rules

The SDK automatically detects and reports:

Rule	Trigger Condition	Severity
PANIC	panic:, fatal error:, segmentation fault	CRITICAL
ERROR_SPIKE	10+ errors in 1 minute	HIGH

Troubleshooting

Issue	Solution
SDK can't read log file	Check file permissions
No logs being sent	Verify AMPLISERV_LOG_PATH is correct
JSON parsing errors	Ensure logs are valid JSON
Connection refused	Verify endpoint URL and network connectivity

View full troubleshooting guide →

Support

• Documentation: docs.ampliserv.io
• Issues: github.com/ampliserv/agent/issues
• Email: support@ampliserv.io