Welcome to the FluentDo Agent Wiki
Relevant source files
The following files were used as context for generating this wiki page:
FluentDo Agent is an open-source (Apache 2.0 licensed) downstream distribution of Fluent Bit. It is designed to be a hardened, stable, and secure-by-default solution with predictable releases and long-term support (LTS) versions maintained for 24 months. The agent enhances the core Fluent Bit functionality with built-in features for log volume reduction, intelligent routing, and efficient buffering.
This project is built upon the foundation of Fluent Bit and integrates several other open-source libraries. It emphasizes security, a smaller footprint optimized for production, and battle-tested quality through extensive testing. This wiki provides a technical overview of the agent's architecture, features, installation, and development workflows.
Sources: README.md:11-19, 311-314
Key Features
FluentDo Agent provides several enhancements over the standard Fluent Bit distribution, focusing on production readiness, security, and cost reduction.
| Feature Category | Description |
|---|---|
| Smaller Footprint | Optimized for production with only essential plugins, size-focused builds using dead code elimination, and interprocedural optimization (IPO/LTO). |
| Security Hardened | Builds are compiled with FORTIFY_SOURCE and stack protection. 17 vendor-specific plugins and all remote interfaces are disabled by default, requiring authentication. FIPS-compliant builds are also available. |
| LTS Support | A 24-month Long-Term Support cycle provides predictable and reliable releases, with weekly security patches and daily vulnerability scans. |
| Advanced Features | Includes native capabilities for performant log deduplication, log sampling, AI-based filtering/routing, native data flattening for OpenSearch/Elasticsearch, and type safety with automatic conflict resolution. |
| Battle-Tested Quality | The agent undergoes a full integration and regression testing suite, memory safety validation with Valgrind/AddressSanitizer, and performance benchmark testing. |
Sources: README.md:60-88
Support & Lifecycle
FluentDo Agent follows a structured release and support lifecycle to ensure predictability and stability for users.
Version Support Matrix
| Version | Release Date | Type | End of Support | Status | Branch |
|---|---|---|---|---|---|
| 26.10 | Oct 2026 | LTS | Oct 2028 | 🟡 Planned | |
| 26.04 | Apr 2026 | LTS | Apr 2028 | 🟢 Active | main |
| 25.10 | Oct 2025 | LTS | Oct 2027 | 🟢 Active | release/25.10-lts |
| 25.07 | Jul 2025 | Regular | Jan 2026 | 🟢 Active |
Sources: README.md:26-36
Release Schedule
The release schedule is designed to provide both stable long-term versions and more frequent updates with new features.
| Release Type | Frequency | Description |
|---|---|---|
| LTS Release | Twice yearly (April, October) | Long-term support for 24 months |
| Regular Release | Quarterly | 6-month support cycle |
| Security Updates | Weekly | CVE patches and critical fixes |
| Patch Release | As needed | Bug fixes and minor updates |
| Main Builds | Weekly | Latest development builds from the main branch |
Sources: README.md:41-49
The diagram below illustrates the release cadence.
Sources: README.md:26-49
Installation
FluentDo Agent can be installed via Docker containers, pre-built packages, or by building from source.
Docker
Docker images are available for UBI and Debian. The agent can be run by mounting a log directory and specifying a configuration file.
# UBI-based image
docker run --rm -it -v /var/log/containers:/var/log/containers:ro ghcr.io/fluentdo/agent/ubi:main -c /fluent-bit/etc/fluent-bit.yaml
# Debian-based image
docker run --rm -it -v /var/log/containers:/var/log/containers:ro ghcr.io/fluentdo/agent/debian:main -c /fluent-bit/etc/fluent-bit.yaml
Sources: README.md:93-96
Package Installation
The install.sh script provides a convenient way to download and install the correct package for your Linux distribution.
curl -sSfL https://raw.githubusercontent.com/FluentDo/agent/refs/heads/main/install.sh | bash
Sources: README.md:105-107
For macOS, a Homebrew tap is available:
brew install fluentdo/tap/agent
Sources: README.md:110-112
Installation Script (install.sh) Logic
The installation script automates platform detection, package discovery, download, and installation.
The following diagram shows the high-level flow of the install.sh script.
Sources: install.sh
The script accepts several command-line arguments to customize its behavior.
| Option | Argument | Description |
|---|---|---|
-v, --version | VERSION | Install a specific version instead of the latest. |
-i, --interactive | Interactively select a version from a list of available ones. | |
-u, --url | URL | Use a custom URL for the package repository. |
-l, --log-file | FILE | Specify a path for the log file. |
-f, --force | Force installation attempt on unsupported distributions. | |
-d, --download | Download the package only, without installing it. | |
--debug | Enable verbose debug output. | |
-h, --help | Show the help message. |
Sources: install.sh:453-481
Building from Source
The agent can be compiled natively or using a container-based build system. Before the build, the scripts/setup-code.sh script is used to apply patches and set the correct version information.
Pre-Build Setup (setup-code.sh)
This script prepares the source code for building by performing these key steps:
- Versioning: It parses the
FLUENTDO_AGENT_VERSIONenvironment variable into major, minor, and patch components. - Patching: It applies a series of patches listed in
patches/patches-agent.filesto the source code located in thesource/directory. - CMake Configuration: It updates the
source/CMakeLists.txtfile with the correct version numbers and rebrands the project from "fluent-bit" to "fluentdo-agent".
Sources: scripts/setup-code.sh
This diagram illustrates the workflow of the setup-code.sh script.
Sources: scripts/setup-code.sh:22-101
Compilation
After the setup script runs, you can compile the agent.
Native Compilation:
git clone https://github.com/FluentDo/agent.git
cd agent/source/build
cmake ..
make
Sources: README.md:129-134
Container-based Build:
This method uses a script to build for a specific Linux distribution inside a container.
git clone https://github.com/FluentDo/agent.git
cd agent
./source/packaging/build.sh -d rockylinux/9
Sources: README.md:117-121
The project uses CMake, which can be configured with various options to enable/disable features, similar to those found in its dependencies like yyjson.
Sources: source/lib/yyjson-0.12.0/doc/doxygen/html/building-and-testing.html
Development & Contribution
The development process for FluentDo Agent involves maintaining a downstream fork of Fluent Bit, applying custom patches, and regularly syncing with upstream changes.
Upstream Sync Process
The scripts/create-sync-pr.sh script automates the creation of pull requests for synchronizing with upstream Fluent Bit. This ensures that FluentDo Agent stays up-to-date with the latest fixes and features from the original project while preserving its own customizations.
The script's workflow is as follows:
- Check Prerequisites: Verifies that
gh(GitHub CLI) is installed and authenticated, and that the working directory is clean. - Collect Commits: Gathers a list of commits between the local branch and
origin/main, categorizing them into technical fixes, tests, and other changes. It extracts upstream commit references to include in the PR body. - Prepare Branch: Pushes the current branch to the remote repository.
- Generate PR Body: Creates a detailed pull request body in a temporary file, including a summary, categorized change lists, and links to the upstream commit range.
- Create Pull Request: Uses
gh pr createto open the PR on GitHub. It can be created as a draft and can be set to auto-merge.
Sources: scripts/create-sync-pr.sh
This sequence diagram shows the interaction between the developer, the script, and GitHub.
Sources: scripts/create-sync-pr.sh
Contribution Philosophy
As a stable distribution, FluentDo Agent values API and ABI compatibility. This principle is also found in its key dependencies. For example, the contribution guidelines for librdkafka state that existing public APIs must never be changed to ensure that applications relying on the library do not break. New features are added via new APIs, and old ones are deprecated rather than removed. This philosophy is central to providing a reliable LTS product.
Sources: source/lib/librdkafka-2.10.1/CONTRIBUTING.md:27-33, 44-50
Similarly, coding style is enforced to maintain readability and reduce errors. The project uses tools to check and fix styles before commits are accepted.
Sources: source/lib/librdkafka-2.10.1/CONTRIBUTING.md:92-98, source/lib/monkey/CONTRIBUTING.md:14-17
Security
Security is a core aspect of the FluentDo Agent.
- Image Signing: Container images are signed with Cosign. The public key is available in the repository (
cosign.pub) for verification. - Reporting Issues: Security vulnerabilities should be reported privately to
security@fluent.do. Public GitHub issues should not be used for security disclosures. Reports should include a description, reproduction steps, potential impact, and any suggested fixes.
Sources: README.md:152-171