Dashboard GitHub

Installation

Install the LogFlux Agent for comprehensive log collection

This guide covers installing the LogFlux Agent, a flexible log collection and forwarding system supporting multiple input sources including CLI, syslog, systemd journal, and container platforms.

LogFlux Agent

The LogFlux Agent is a plugin-based system for comprehensive log collection. It includes a core agent daemon that manages multiple specialized plugins for different log sources, from command-line tools to container platforms and observability protocols.

For Ubuntu/Debian systems:

1

curl -fsSL https://apt.logflux.io/install.sh | sudo bash

For RHEL/CentOS/Rocky/Alma systems:

1

curl -fsSL https://rpm.logflux.io/install.sh | sudo bash

Manual APT Repository Setup

If you prefer manual installation on Ubuntu/Debian:

1
2
3
4
5
6
7
8

# Download and add GPG key
curl -fsSL https://apt.logflux.io/logflux.gpg | sudo gpg --dearmor -o /usr/share/keyrings/logflux-archive-keyring.gpg

# Add repository with signed-by option
echo "deb [signed-by=/usr/share/keyrings/logflux-archive-keyring.gpg] https://apt.logflux.io stable main" | sudo tee /etc/apt/sources.list.d/logflux.list

# Install
sudo apt update && sudo apt install logflux-agent

Other Platforms

The LogFlux Agent supports multiple package repositories:

  • RPM Repository: rpm.logflux.io (RHEL/CentOS/Rocky/Alma)
  • Binary Downloads: download.logflux.io (all platforms)

Quick Start

After installation, follow these steps to get started:

1. Configure API Key (Required)

Edit the main configuration file:

1

sudo nano /etc/logflux-agent/agent.yaml

Update at minimum:

1

api_key: your-actual-api-key-here  # Replace with your LogFlux API key

2. Start the Main Agent Service

1

sudo systemctl enable --now logflux-agent

3. Test the CLI

1
2
3
4
5
6
7
8

# Send a test message
logflux -message "Hello, LogFlux!"

# Check version
logflux -version

# Perform health check
logflux -health

4. Enable Core System Plugins

The agent includes essential system log collection plugins:

1
2
3
4

# Enable core system log collectors
sudo systemctl enable --now logflux-syslogd       # Syslog collector
sudo systemctl enable --now logflux-journald      # Journal collector  
sudo systemctl enable --now logflux-filestream    # File monitoring

These plugins provide comprehensive system log collection:

  • Syslog: Collects logs from applications using syslog protocol
  • Journald: Integrates with systemd journal for system logs
  • File Monitoring: Watches log files for real-time collection

Core Agent Components

The LogFlux Agent includes essential plugins for system log collection:

Core System Plugins

  • CLI Plugin (logflux) - Command-line tool for manual log submission and testing
  • Syslog Plugin (logflux-syslogd) - Syslog daemon (TCP/UDP port 514) for application logs
  • Journal Plugin (logflux-journald) - systemd journal integration for system logs
  • Filestream Plugin (logflux-filestream) - File monitoring and streaming for log files

These four plugins provide comprehensive coverage for most system logging needs. Additional plugins for container platforms, observability protocols, and cloud providers are available and covered in the integrations section.

Configuration

Basic Configuration

The agent requires minimal configuration. The main configuration file is /etc/logflux-agent/agent.yaml:

1
2
3

api_key: your-actual-api-key-here  # REQUIRED - must be updated
server_url: /tmp/logflux-agent.sock  # Default Unix socket
node: default-node                  # Should be updated for production

Advanced Configuration

Create plugin-specific configuration files in /etc/logflux-agent/plugins/:

1
2

sudo mkdir -p /etc/logflux-agent/plugins
sudo nano /etc/logflux-agent/plugins/cli.yaml

Example plugin configuration:

1
2
3
4
5

# CLI plugin configuration
server_url: /tmp/logflux-agent.sock
api_key: your-api-key
node: hostname-cli
prefix: CLI

Configuration Priority

  1. Command line flags (override all)
  2. Configuration file specified with -config
  3. /etc/logflux-agent/agent.yaml (main config)
  4. /etc/logflux-agent/plugins/<plugin>.yaml (plugin-specific)
  5. Built-in defaults

CLI Usage Examples

Once configured, you can use the LogFlux CLI in multiple ways:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Send a single message
logflux -message "Hello, LogFlux!"

# Send with custom level and prefix
logflux -message "System starting" -level info -prefix "SYSTEM"

# Interactive mode
logflux -interactive

# Batch mode from stdin
echo -e "Message 1\nMessage 2\nMessage 3" | logflux -batch

# Read from file
logflux -file /var/log/app.log

# Tail mode
tail -f /var/log/app.log | logflux -tail

# Watch file for changes
logflux -watch /var/log/app.log

# Health check
logflux -health

Available CLI Options

  • -config FILE: Path to configuration file
  • -url URL: LogFlux server URL
  • -key KEY: API key for authentication
  • -node ID: Node identifier
  • -message MSG: Log message to send
  • -level LEVEL: Log level (debug, info, warn, error)
  • -prefix PREFIX: Log prefix
  • -batch: Enable batch mode (read multiple messages)
  • -interactive: Interactive mode
  • -health: Perform health check
  • -version: Show version information
  • -help: Show help information
  • -init: Initialize configuration file
  • -verbose: Enable verbose output
  • -timestamp TIME: Custom timestamp (RFC3339 format)
  • -file FILE: Read log messages from file
  • -tail: Tail mode - continuously read from stdin
  • -watch FILE: Watch file for changes and send new lines

Docker Installation

Run the LogFlux Agent using Docker:

1
2
3
4
5
6

# Pull the image
docker pull docker.io/logflux/agent:latest

# Run with configuration mounted
docker run -v /etc/logflux-agent:/etc/logflux-agent \
  docker.io/logflux/agent:latest

Performance Features

The LogFlux Agent includes several performance optimizations:

  • Automatic Batching: All plugins batch messages by default (configurable size and intervals)
  • Rate Limiting: Protect against log floods with configurable burst capacity
  • Log Filtering: Level-based and regex filtering to reduce network traffic
  • Multi-line Handling: Proper stack trace and multi-line event processing
  • Field Extraction: Regex-based structured data extraction from log messages
  • Log Sampling: Probabilistic sampling with error level preservation
  • File Rotation Awareness: Inode-based rotation detection with automatic file discovery
  • Connection Pooling: Efficient connection management for high throughput
  • Graceful Shutdown: Proper signal handling with queue flushing

Next Steps