System log forwarder

The System log forwarder (aws.greengrass.SystemLogForwarder) uploads active system logs directly to Amazon CloudWatch using the CloudWatch HTTPS API.

Versions

This component has the following versions:

Type

This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

For more information, see Component types.

Operating system

This component must be installed on systemd-based Linux systems.

Requirements

This component has the following requirements:

The component requires access to create log and stream groups in CloudWatch as well as permission to perform the PutLogEvents HTTP call. You must add the following policy to your Greengrass device's role alias:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}
      

Endpoints and ports

This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see Allow device traffic through a proxy or firewall.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

2.0

The following table lists the dependencies for version 2.0 of this component.

Dependency	Compatible versions	Dependency type
Token exchange service	>=2.0.0	Hard

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

v2.0.x

maxUploadIntervalSec

The maximum period at which system log forwarder will attempt to upload logs. Since log forwarder will upload logs when the memory fills, it may still upload more often than the configured maximum cadence.

maxRetriesCount

Number of times system log forwarder will attempt to retry a transient HTTP error.

bufferCapacity

The size of the ring buffer for in-memory log storage.

logGroup

The log path in CloudWatch.

logStream

The CloudWatch logStream.

filters

A map of filter configurations for the core device.

services

A list of service name filters that System Log Forwarder will use to determine which logs gets uploaded. A log will only be uploaded if the service it originated from matches at least one of the filters in this list. The filters in this list may either be a string that the service name must fully match, or a string ending with *, which means the prefix must match.

Default: [ggl.*]

Important

A log will only be uploaded if the service it originated from matches at least one of the filters in this list.

Note

Using the value * will include all available services.

Example configuration:

The example below will filter logs by all services included in Greengrass Nucleus Lite.

{
    "maxUploadIntervalSec": 300,
    "maxRetriesCount": 3,
    "bufferCapacity": 1048576,
    "logGroup": "greengrass/systemLogs",
    "logStream": "deviceName",
    "filters": {
        "services": ["ggl.*"]
    }
}

Changelog

The following table describes the changes in each version of the component.