omawslogshlc sends log messages to Amazon CloudWatch Logs using the HTTP Log Collector (HLC) endpoint with bearer token authentication. It is a user-contributed, experimental module with higher operational risk than core-supported mature modules.

omawslogshlc: Amazon CloudWatch Logs HLC Output Module¶

Module Name:	omawslogshlc
Author:	Amazon CloudWatch Logs team
Status:	user-contributed, experimental
Available since:	v8.2604

Warning

omawslogshlc is user-contributed and experimental. It has had less production exposure and core-maintainer ownership than mature rsyslog modules, so deployments should treat it as higher risk, test it carefully, and expect possible feedback-driven behavior or configuration changes.

Purpose¶

This module provides native support for forwarding syslog messages to Amazon CloudWatch Logs. It uses the publicly available HLC (HTTP Log Collector) endpoint and bearer token authentication, eliminating the need for the AWS SDK or a separate log collection agent.

Each syslog message is wrapped in the HLC JSON event format and posted to the configured CloudWatch Logs log group and log stream.

Notable Features¶

Bearer token authentication (no AWS SDK dependency)
Automatic event batching with configurable batch size
JSON escaping of message content
Automatic inclusion of timestamp, hostname, and source metadata
User-Agent header identifying rsyslog version
Retry-friendly error handling for transient failures (429, 5xx)

Requirements¶

To use omawslogshlc, you need the following:

libcurl support at build time
An AWS region where CloudWatch Logs is available
A CloudWatch Logs log group with bearer token authentication enabled
A bearer token generated for that log group (starts with ACWL)
A log stream within the log group

The module is built only when ./configure is invoked with --enable-omawslogshlc.

For information on setting up bearer token authentication, see the AWS documentation.

Configuration Parameters¶

Note

Parameter names are case-insensitive.

Note

This module supports action parameters only.

Action Parameters¶

region¶

Type:	string
Required:	yes

The AWS region for the CloudWatch Logs endpoint (e.g., us-west-2, eu-west-1). This is used to construct the HLC endpoint URL: https://logs.<region>.amazonaws.com/services/collector/event

bearer_token¶

Type:	string
Required:	yes

The bearer token for HLC endpoint authentication. Tokens start with ACWL. This value is sent in the Authorization: Bearer <token> header.

log_group¶

Type:	string
Required:	yes

The name of the CloudWatch Logs log group to send events to. The value is URL-encoded automatically.

log_stream¶

Type:	string
Required:	yes

The name of the CloudWatch Logs log stream within the log group. The value is URL-encoded automatically.

max_batch_size¶

Type:	integer
Default:	100
Required:	no

Maximum number of events per HTTP request. When the batch reaches this count, it is flushed immediately. Valid range is 1 to 10000. AWS recommends 10–100 events per request for optimal performance.

template¶

Type:	word
Default:	RSYSLOG_TraditionalFileFormat
Required:	no

The rsyslog template used to render the message content. The rendered output becomes the event field in the HLC JSON payload.

Batching Behavior¶

omawslogshlc accumulates events within a transaction and flushes them when one of the following happens:

The event count reaches max_batch_size
The rsyslog transaction ends (endTransaction)
The total batch size approaches the 1 MiB HLC request limit

Events are sent as concatenated JSON objects (no array wrapper), which is one of the accepted formats for the HLC endpoint.

Error Handling¶

The module handles HTTP errors as follows:

200–299: Success. Batch is cleared.
401/403: Authentication failure. The action is suspended for retry. Check that the bearer token is valid and not expired.
429: Rate limited. The action is suspended and retried according to rsyslog’s action retry settings.
5xx: Server error. The action is suspended for retry.
Other 4xx: Non-retryable. The batch is dropped and an error is logged.

Use rsyslog’s action.resumeInterval and action.resumeRetryCount to control retry behavior.

Example¶

Forward all syslog messages to CloudWatch Logs:

module(load="omawslogshlc")

*.* action(
   type="omawslogshlc"
   region="us-west-2"
   bearer_token="ACWL..."
   log_group="my-application-logs"
   log_stream="server-01"
)

Forward only auth logs with a larger batch size:

module(load="omawslogshlc")

auth,authpriv.* action(
   type="omawslogshlc"
   region="eu-west-1"
   bearer_token="ACWL..."
   log_group="security-logs"
   log_stream="auth"
   max_batch_size="50"
   action.resumeInterval="5"
   action.resumeRetryCount="10"
)

YAML configuration for the same target:

version: 2
modules:
  - load: omawslogshlc

rulesets:
  - name: main
    filter: "*.*"
    actions:
      - type: omawslogshlc
        region: us-west-2
        bearer_token: ACWL...
        log_group: my-application-logs
        log_stream: server-01
        max_batch_size: 50

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project