Quarkus Fluency Fluentd Extension

A Quarkus extension that integrates Fluency — a high-performance Fluentd / Fluent Bit client for Java — into your Quarkus application as a managed CDI bean.

This extension addresses the direct Fluentd integration request raised in quarkusio/quarkus#453.

Prerequisites

• Java 17+
• Maven 3.9+
• A running Fluentd or Fluent Bit instance (optional for development — the client degrades gracefully if unavailable)

Installation

Add the runtime artifact to your project:

<dependency>
    <groupId>io.github.yuokada.quarkus.extension</groupId>
    <artifactId>quarkus-fluency-fluentd</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

Usage

Inject FluencyClient wherever you need to forward log records to Fluentd:

@ApplicationScoped
public class MyService {

    @Inject
    FluencyClient fluencyClient;

    public void doSomething() {
        Map<String, Object> record = new LinkedHashMap<>();
        record.put("message", "something happened");
        record.put("userId", 42);

        fluencyClient.emit("myapp.events", record);
    }
}

emit() returns false (and does not throw) when Fluentd is unreachable, so no special error handling is required in application code.

Centralized Log Management

This extension is one approach to forwarding application events to a centralized log management stack such as EFK (Elasticsearch + Fluentd + Kibana).

The official Quarkus guide — Centralized Log Management — covers an alternative approach using Quarkus's built-in syslog handler to push logs to Fluentd:

Comparison with alternatives

	quarkus-logging-gelf	Quarkus syslog handler	This extension (Fluency)
Status	Deprecated	Active	Active
Protocol	GELF over UDP/TCP (port 12201)	Syslog UDP/TCP (port 5140)	Fluentd forward TCP (port 24224)
Transport	jboss-logmanager log handler	jboss-logmanager log handler	Fluency client library
What gets sent	All log output automatically	All log output automatically	Only records explicitly emitted via emit()
Wire format	GELF JSON	Syslog (RFC 5424)	MessagePack (Fluentd native)
Primary target	Graylog (Fluentd via plugin)	Fluentd / any syslog sink	Fluentd / Fluent Bit natively
Config prefix	quarkus.log.handler.gelf.*	quarkus.log.syslog.*	quarkus.fluency.*

• Use quarkus-logging-gelf — not recommended; deprecated in favour of OpenTelemetry Logging or the socket handler.
• Use the syslog handler when you want all Quarkus log output forwarded automatically with no code changes.
• Use this extension when you need to emit specific structured events (audit logs, metrics, domain events) from application code with full control over the Fluentd tag and record payload.

Configuration

All properties are under the quarkus.fluency prefix.

Property	Default	Description
quarkus.fluency.host	localhost	Fluentd host
quarkus.fluency.port	24224	Fluentd TCP port
quarkus.fluency.enabled	true	Set to false to disable log forwarding entirely
quarkus.fluency.sender-max-retry-count	4	Max send retry attempts
quarkus.fluency.buffer-chunk-initial-size	1048576	Buffer chunk initial size in bytes (1 MiB); must be less than retention size
quarkus.fluency.buffer-chunk-retention-size	4194304	Buffer chunk retention size in bytes (4 MiB); must be greater than initial size
quarkus.fluency.buffer-chunk-retention-time-millis	1000	Buffer flush interval in milliseconds

Example application.properties:

quarkus.fluency.host=fluentd.internal
quarkus.fluency.port=24224
quarkus.fluency.sender-max-retry-count=8

Building

# Build extension modules and run unit tests
./mvnw install -pl deployment,runtime

# Build everything including integration tests (requires Docker for Testcontainers)
./mvnw verify -DskipITs=false

# Skip tests
./mvnw install -DskipTests

Code Style

This project uses spotless-maven-plugin with google-java-format to enforce consistent Java formatting.

# Check formatting (runs automatically during verify)
./mvnw spotless:check

# Apply formatting
./mvnw spotless:apply

The spotless:check goal is bound to the verify phase, so CI will fail on unformatted code. Run spotless:apply before committing.

Project Structure

quarkus-fluency-fluentd-parent
├── runtime/            # CDI beans and config — the artifact users depend on
├── deployment/         # Build-time processors (@BuildStep) for augmentation
└── integration-tests/  # Quarkus application exercising the extension

Releasing

This project releases to Maven Central from GitHub Actions. The release Maven profile is intended for the GitHub Actions workflow in .github/workflows/maven-central-publish.yml, not for routine local use.

Release prerequisites

Before starting a release, make sure the following are configured:

• Push access to this GitHub repository
• GitHub Actions secrets for Maven Central publishing (CENTRAL_USERNAME, CENTRAL_PASSWORD, GPG_PRIVATE_KEY, GPG_PASSPHRASE)
• A clean working tree (git status)

Release steps

1. Verify the branch state and test suite:

   git status
   ./mvnw verify

2. Bump project versions and create the release tag. This project uses maven-release-plugin for version/tag management:

   ./mvnw release:clean release:prepare

   What this does:

   • updates the root, runtime, deployment, and integration-tests module versions
   • creates a Git tag in the form vX.Y.Z
   • updates the repository to the next development version

3. Push the release commit and tag to GitHub:

   git push origin master
   git push origin vX.Y.Z

4. GitHub Actions publishes the package to Maven Central:

   • the workflow .github/workflows/maven-central-publish.yml runs on tag push
   • that workflow activates -Prelease
   • the release profile performs source/javadoc generation, GPG signing, and Central publishing

5. Confirm the release was published:

   • check the generated GitHub tag/release commit
   • verify the new version appears in Maven Central

If you run -Prelease locally, you must provide the same GPG key and Maven Central credentials that GitHub Actions injects. Otherwise artifact signing or publishing will fail.

License

MIT License