Visit Azul.com Support

Forwarder 2.1.0

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

Forwarder 2.1.0

Release date: November, 2026

Intelligence Cloud

This release adds command-line tools to check the Forwarder’s settings before you start it, and the Forwarder now validates its settings at every start. It also fixes how the Forwarder responds to malformed requests and updates bundled security libraries.

Important
 Start scripts that pass unknown command-line arguments, or that put -D options after -jar, stop working after this upgrade. See Command Line and Settings Validation.

What’s New

Command line and settings validation: The Forwarder’s command-line tools show and check its settings:

Command What it does

-h, --help

Shows the usage and the available commands.

--help args [env|sys|conf] [section]

Lists the settings of the Forwarder. Required settings are marked [required].

--help config-file

Shows a sample properties file.

--validate-args

Checks the setup without starting the Forwarder, and prints PASS, FAIL or SKIP for each check.

--dump-config

Shows the effective value of each setting and where it comes from. Secrets are masked.

--version

Shows the version, commit and build time.

The Forwarder also checks its settings at every start. The first invalid setting stops the Forwarder with exit code 1 and a message that names the setting.

Behavior change: Unknown or extra command-line arguments now stop the Forwarder instead of being ignored. The Forwarder prints the problem and a short help, exits with code 255, and does not start. Pass -D options before -jar: after -jar, they are program arguments and are rejected.

Exit code Meaning

0

The command succeeded.

1

A setting is invalid at startup, or --validate-args found a failure.

2

The Forwarder failed to start.

3, 4

The authorization with Azul Intelligence Cloud failed.

255

The command-line arguments are invalid.

Software Bill of Materials (SBOM): Each release now comes with an SBOM in CycloneDX format, forwarder-<version>.cdx.json, next to the Forwarder JAR. It lists the third-party components that the JAR contains.

Bug Fixes

  • Clearer errors for invalid requests: Malformed requests from agents now get an HTTP 4xx response, instead of an internal error (500) or no response. A request without a Content-Type header returns 400, and a malformed artifact upload gets a proper error response.

  • Generated certificates: The certificate that the Forwarder generates now also lists the domain used as its common name in the list of alternative names (SAN), which some clients require.

Security

These updates were first delivered in Forwarder 2.0.1 to 2.0.4.

Compatibility

  • Fully compatible with all existing Intelligence Cloud Agent versions

  • No agent-side configuration changes required

  • Upgrading: check that your start script passes no unknown arguments and that every -D option comes before -jar

Azul Intelligence On-Premises

This is the first Forwarder release for Azul Intelligence On-Premises. The Forwarder can now deliver the data of your Azul IC Agents and AMT to your own installation, so nothing leaves your network.

What’s New

Local mode: Start the Forwarder with --mode=local and point it at your installation with azul.ljvmi.url. The Forwarder then accepts data from the Azul IC Agent and from AMT, and delivers it to your installation’s inbox, on a local filesystem or in an S3-compatible bucket.

Mode Option What the Forwarder does

Local

--mode=local

Accepts the data of Agents and AMT and delivers it to your Azul Intelligence On-Premises installation.

The mode is fixed for the lifetime of the process. For installation steps, see Installing the Forwarder.

How it works:

  1. At startup, the Forwarder checks in to your installation with its access key. The installation answers with everything else the Forwarder needs: where to deliver, the storage type, the limits for delivery files, and its clock. You configure none of these on the Forwarder host.

  2. The Forwarder accepts connections from Agents and AMT on its port.

  3. It writes the received data into delivery files and hands each file over when it is complete.

  4. While running, the Forwarder polls your installation every 10 seconds by default. The poll keeps the connection status, the clock, and the S3 upload grant up to date, and tells the Forwarder when an Admin disabled it.

What is delivered:

Source Delivered as

Azul IC Agent

JVM events, one JSON object per line, in files named events.<timestamp>.ndjson.

AMT

Each report as its own file, named amt.<timestamp>.csv.

  • Only the events that your installation uses are stored: JVM start, JVM updates, and application identification data. The Forwarder accepts and discards other Agent events.

  • File names carry a timestamp aligned to your installation’s clock and increase within each kind of file. You can order deliveries by name, even when several Forwarders write to one inbox.

Storage: Your installation chooses the storage when the Forwarder checks in.

Storage How the Forwarder delivers

Local filesystem

Writes into the directory that your installation assigns. Each file is written under a temporary .tmp name and renamed when it is complete, so a reader never sees a partial file. The Forwarder cleans up temporary files left behind by a crash.

S3-compatible bucket (AWS S3, Silo, RustFS, Ceph)

Uploads each completed file with a short-lived upload grant that your installation issues and renews. The Forwarder holds no bucket name and no S3 credentials.

Delivery file limits: The Forwarder completes a delivery file when it reaches a number of lines, a size, or an age, whichever comes first. Your installation can make these limits smaller, never larger.

Limit Default Setting

Lines

10,000

azul.local.merger.max.lines

Size

16 MiB

azul.local.merger.max.bytes

Age

10 hours

azul.local.merger.max.duration

Configuration: A local-mode setup needs the access key and the URL of your installation, plus a keystore unless you use plain HTTP:

 
azul.forwarder.access.key = <forwarder-access-key>
azul.ljvmi.url = http://<your-installation-host>:<port>
azul.forwarder.keystore.path = <path-to-keystore>
azul.forwarder.keystore.password = <keystore-password>
 
java -DforwarderSettings=forwarder-settings.properties -jar forwarder.jar --mode=local

You supply the keystore (JKS or PKCS12) with the certificate and private key that the Forwarder presents to Agents. The settings file that your installation generates under Settings > Data Source Setup is the shortest way to start.

Settings that don’t apply to local mode, such as the proxy and deduplication settings, are ignored with a warning in the log. --help args --mode local lists the settings that you can use.

Limitations:

  • The Forwarder does not deduplicate events in local mode. It delivers all stored events.

  • Delivery is best-effort. With S3 storage, completed files wait for their upload in memory. When the bucket is unavailable for a long time, the Forwarder drops the oldest waiting files first, and files still waiting at shutdown are lost. Under heavy overload, the Forwarder drops incoming events instead of letting memory grow. The Forwarder logs and counts every drop.

  • Uploading artifacts is not available in local mode. The Forwarder answers these requests with HTTP 501.

Plain HTTP for Agents: By default, the Forwarder accepts Agent connections over HTTPS only, with TLS 1.2 or 1.3. When no certificate is available yet, for example in a pilot, set azul.client.tls.disabled=true to serve plain HTTP on the Forwarder’s port. No keystore is needed then. The Agent must also allow it with noSsl=true, and only the Agent version released with this Forwarder supports that option. The setting applies only to connections from Agents and AMT to the Forwarder, and the Forwarder logs a warning at startup.

Warning
 With plain HTTP, all observations travel unencrypted on your network. Use it only on networks you trust, for example for a time-boxed pilot.

Startup checks and disabled Forwarders: The Forwarder only starts accepting connections after every check succeeds. Otherwise, it logs the reason and stops.

  1. The settings are valid for local mode.

  2. Your installation accepts the access key.

  3. Your installation assigns a supported storage, with a directory or an upload grant.

  4. The storage works: the directory is writable, or the S3 endpoint is reachable.

After the start, the Forwarder never stops by itself:

  • When your installation is not reachable, the status poll fails and the connection status shows DOWN. Delivery continues, and the status recovers with the next successful poll.

  • When an Admin disables the Forwarder or deletes its registration, the Forwarder pauses delivery. It keeps running and accepting connections, but drops the data it receives, and its health state turns YELLOW. When the Forwarder is enabled again, delivery resumes without a restart.

Monitoring: The health endpoint (/forwarder/health) and the status page show the mode and a localDelivery block:

Field Meaning

state

GREEN, or YELLOW while delivery is paused.

storageType

fs or s3.

writePath

Filesystem storage only: the delivery directory.

s3Target

S3 storage only: the bucket URL and key prefix. It never contains the upload credentials.

deliverySuspended

true while delivery is paused.

droppedObjects

The number of delivery files dropped since startup.

droppedSince

When the first drop happened. Only present when files were dropped.

sealLimits

The delivery file limits in effect, when your installation set any.

The Prometheus endpoint (port 9090 by default) has new metrics, all with a type label that is events or amt:

Metric Meaning

azul_forwarder_local_delivery_objects_total

Delivery files handed to storage.

azul_forwarder_local_delivery_bytes

Size distribution of the delivery files.

azul_forwarder_local_dropped_total

Files dropped instead of delivered, with a reason label: ingest (overload), spool_overflow, grant_ceiling, store_reject (S3), or store_error (filesystem).

azul_forwarder_local_s3_upload_total

S3 upload attempts, with a result label: delivered, retry_transient, or retry_grant.

azul_forwarder_local_s3_spool_used and azul_forwarder_local_s3_spool_capacity

S3 storage only: the files waiting for upload, and the maximum.

A series only appears once it has a value, so the S3 series never appear with filesystem storage. The metrics do not count data dropped while delivery is paused.

Command line and settings validation: The command-line tools work per mode. Use --mode to select the mode, and --help, --help args, --help config-file, --validate-args and --dump-config show and check only the settings of that mode:

 
java -DforwarderSettings=forwarder.properties -jar forwarder.jar --mode local --validate-args

In local mode, --validate-args checks the required settings, the port, the access key, the keystore (it exists and opens with the password, unless you use plain HTTP), the format of the installation URL, and the S3 truststore if you configured one. It does not contact your installation. A setting that the selected mode does not use is ignored with a warning in the log, and --dump-config lists it as ignored.

The Forwarder checks its settings at every start. The first invalid setting stops the Forwarder with exit code 1 and a message that names the setting. Unknown command-line arguments stop the Forwarder with exit code 255, and -D options must come before -jar.

Software Bill of Materials (SBOM): Each release now comes with an SBOM in CycloneDX format, forwarder-<version>.cdx.json, next to the Forwarder JAR. It lists the third-party components that the JAR contains.

Security

Compatibility

  • Use this Forwarder with the Azul IC Agent version released with it.