# Log manager
<a name="log-manager-component"></a>

**Warning**  
We recommend upgrading to Log Manager v2.3.5 or later. Version 2.3.5 optimizes Log Manager configuration writes, reducing IO operations and improving log upload speed, overall device performance and possibly extending device life.

The log manager component (`aws.greengrass.LogManager`) uploads logs from AWS IoT Greengrass core devices to Amazon CloudWatch Logs. You can upload logs from the Greengrass nucleus, other Greengrass components, and other applications and services that aren't Greengrass components. For more information about how to monitor logs in CloudWatch Logs and on the local file system, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="log-manager-considerations-intro"></a>The following considerations apply when you use the log manager component to write to CloudWatch Logs:<a name="log-manager-considerations"></a>
+ **Log delays**

  The log manager component version 2.2.8 (and earlier) processes and uploads logs from only rotated log files. By default, the AWS IoT Greengrass Core software rotates log files every hour or after they are 1,024 KB. As a result, the log manager component uploads logs only after the AWS IoT Greengrass Core software or a Greengrass component writes over 1,024 KB worth of logs. You can configure a lower log file size limit to cause log files to rotate more often. This causes the log manager component to upload logs to CloudWatch Logs more frequently.

  The log manager component version 2.3.0 (and later) processes and uploads all logs. When you write a new log, log manager version 2.3.0 (and later) processes and directly uploads that active log file instead of waiting for it to be rotated. This means that you can view the new log in 5 minutes or less.

  The log manager component uploads new logs periodically. By default, the log manager component uploads new logs every 5 minutes. You can configure a lower upload interval, so the log manager component uploads logs to CloudWatch Logs more frequently by configuring the `periodicUploadIntervalSec`. For more information about how to configure this periodic interval, see [Configuration](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html#log-manager-component-configuration).

  Logs can be uploaded in near real-time from the same Greengrass file system. If you need to observe logs in real time, consider using [file system logs](monitor-logs.md#access-local-logs).
**Note**  
If you're using different file systems to write logs to, log manager reverts back to the behavior in log manager component versions 2.2.8 and earlier. For information about accessing file system logs, see [Access file system logs](https://docs.aws.amazon.com/greengrass/v2/developerguide/monitor-logs.html#access-local-logs).
+ **Clock skew**

  The log manager component uses the standard Signature Version 4 signing process to create API requests to CloudWatch Logs. If the system time on a core device is out of sync by more than 15 minutes, then CloudWatch Logs rejects the requests. For more information, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference*.

For information about the log groups and log streams to which this component uploads logs, see [Usage](#log-manager-component-usage).

**Topics**
+ [Versions](#log-manager-component-versions)
+ [Type](#log-manager-component-type)
+ [Operating system](#log-manager-component-os-support)
+ [Requirements](#log-manager-component-requirements)
+ [Dependencies](#log-manager-component-dependencies)
+ [Configuration](#log-manager-component-configuration)
+ [Usage](#log-manager-component-usage)
+ [Local log file](#log-manager-component-log-file)
+ [Changelog](#log-manager-component-changelog)

## Versions
<a name="log-manager-component-versions"></a>

This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type
<a name="log-manager-component-type"></a>

<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system
<a name="log-manager-component-os-support"></a>

This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements
<a name="log-manager-component-requirements"></a>

This component has the following requirements:
+ The [Greengrass device role](device-service-role.md) must allow the `logs:CreateLogGroup`, `logs:CreateLogStream`, `logs:PutLogEvents`, and `logs:DescribeLogStreams` actions, as shown in the following example IAM policy.

  ```
  {
    "Version": "2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "logs:CreateLogGroup",
          "logs:CreateLogStream",
          "logs:PutLogEvents",
          "logs:DescribeLogStreams"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:logs:*:*:*"
      }
    ]
  }
  ```
**Note**  
The [Greengrass device role](device-service-role.md) that you create when you install the AWS IoT Greengrass Core software includes the permissions in this example policy by default.

  For more information, see [Using identity-based policies (IAM policies) for CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-identity-based-access-control-cwl.html) in the *Amazon CloudWatch Logs User Guide*.
+ The log manager component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The log manager component must have connectivity to `logs.region.amazonaws.com` which has the VPC endpoint of `com.amazonaws.us-east-1.logs`.

### Endpoints and ports
<a name="log-manager-component-endpoints"></a>

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](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `logs.region.amazonaws.com`  | 443 | No |  Required if you write logs to CloudWatch Logs.  | 

## Dependencies
<a name="log-manager-component-dependencies"></a>

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](#log-manager-component-changelog) 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](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.3.11 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.17.0 | Soft | 

------
#### [ 2.3.10 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.16.0 | Soft | 

------
#### [ 2.3.9 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.15.0 | Soft | 

------
#### [ 2.3.8 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.14.0 | Soft | 

------
#### [ 2.3.7 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.13.0 | Soft | 

------
#### [ 2.3.5 and 2.3.6 ]

The following table lists the dependencies for versions 2.3.5 and 2.3.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.12.0 | Soft | 

------
#### [ 2.3.3 – 2.3.4 ]

The following table lists the dependencies for versions 2.3.3 to 2.3.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.11.0 | Soft | 

------
#### [ 2.2.8 – 2.3.2 ]

The following table lists the dependencies for versions 2.2.8 to 2.3.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.10.0 | Soft | 

------
#### [ 2.2.7 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.9.0 | Soft | 

------
#### [ 2.2.6 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.8.0 | Soft | 

------
#### [ 2.2.5 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.7.0 | Soft | 

------
#### [ 2.2.1 - 2.2.4 ]

The following table lists the dependencies for versions 2.2.1 - 2.2.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.6.0 | Soft | 

------
#### [ 2.1.3 and 2.2.0 ]

The following table lists the dependencies for versions 2.1.3 and 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.5.0 | Soft | 

------
#### [ 2.1.2 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.4.0 | Soft | 

------
#### [ 2.1.1 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.3.0 | Soft | 

------
#### [ 2.1.0 ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.2.0  | Soft | 

------
#### [ 2.0.x ]

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


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration
<a name="log-manager-component-configuration"></a>

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

------
#### [ v2.3.10 ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
We strongly recommend using a single configuration key per component. You should only target a group of files that have only one log file that's actively being written to when using the `logFileRegex`. Not following this recommendation may lead to duplicate logs getting uploaded to CloudWatch. If you are targeting multiple active log files with a single regex, we recommend you upgrade to log manager v2.3.1 or later and consider changing your configuration using the [example configuration](#log-manager-multiple-logs-v2.3.10).
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.  
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

`updateToTlogIntervalSec`  
(Optional) The period in seconds for how often the nucleus writes Amazon CloudWatch Events log-upload event details to the local transaction log (`config.tlog`). Defaults to the value specified in `periodicUploadIntervalSec`. You can modify this parameter to increase the writing interval.  
Default: `periodicUploadIntervalSec`  
Minimum: `periodicUploadIntervalSec`

`deprecatedVersionSupport`  
Indicates whether the log manager should use logging speed improvements introduced in log manager v2.3.5. Set the value to `false` to use the improvements.  
If you set this value to `false` when you upgrade from log manager v2.3.1 or earlier duplicate log entries may be uploaded.  
The default is `true`.

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300",
  "deprecatedVersionSupport": "false"
}
```

**Example: Configuration to upload multiple active log files using log manager v2.3.1**  
The following example configuration is the recommended example if you want to target multiple active log files. This example configuration specifies what active log files you want to upload to CloudWatch. Using this configuration example configuration will also upload any rotated files that match the `logFileRegex`. This example configuration is supported on log manager v2.3.1.  

```
{
  "logsUploaderConfiguration": {
    "componentLogsConfigurationMap": {
      "com.example.A": {
        "logFileRegex": "com.example.A\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
      "com.example.B": {
        "logFileRegex": "com.example.B\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "10"
}
```

------
#### [ v2.3.6 – v2.3.9 ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
We strongly recommend using a single configuration key per component. You should only target a group of files that have only one log file that's actively being written to when using the `logFileRegex`. Not following this recommendation may lead to duplicate logs getting uploaded to CloudWatch. If you are targeting multiple active log files with a single regex, we recommend you upgrade to log manager v2.3.1 or later and consider changing your configuration using the [example configuration](#log-manager-multiple-logs-v2.3.1).
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.  
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

`deprecatedVersionSupport`  
Indicates whether the log manager should use logging speed improvements introduced in log manager v2.3.5. Set the value to `false` to use the improvements.  
If you set this value to `false` when you upgrade from log manager v2.3.1 or earlier duplicate log entries may be uploaded.  
The default is `true`.

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300",
  "deprecatedVersionSupport": "false"
}
```

**Example: Configuration to upload multiple active log files using log manager v2.3.1**  
The following example configuration is the recommended example if you want to target multiple active log files. This example configuration specifies what active log files you want to upload to CloudWatch. Using this configuration example configuration will also upload any rotated files that match the `logFileRegex`. This example configuration is supported on log manager v2.3.1.  

```
{
  "logsUploaderConfiguration": {
    "componentLogsConfigurationMap": {
      "com.example.A": {
        "logFileRegex": "com.example.A\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
      "com.example.B": {
        "logFileRegex": "com.example.B\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "10"
}
```

------
#### [ v2.3.0 – 2.3.5 ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
We strongly recommend using a single configuration key per component. You should only target a group of files that have only one log file that's actively being written to when using the `logFileRegex`. Not following this recommendation may lead to duplicate logs getting uploaded to CloudWatch. If you are targeting multiple active log files with a single regex, we recommend you upgrade to log manager v2.3.1 and consider changing your configuration using the [example configuration](#log-manager-multiple-logs-v2.3.1).
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.  
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300"
}
```

**Example: Configuration to upload multiple active log files using log manager v2.3.1**  
The following example configuration is the recommended example if you want to target multiple active log files. This example configuration specifies what active log files you want to upload to CloudWatch. Using this configuration example configuration will also upload any rotated files that match the `logFileRegex`. This example configuration is supported on log manager v2.3.1.  

```
{
  "logsUploaderConfiguration": {
    "componentLogsConfigurationMap": {
      "com.example.A": {
        "logFileRegex": "com.example.A\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
      "com.example.B": {
        "logFileRegex": "com.example.B\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "10"
}
```

------
#### [ v2.2.x ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.   
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300"
}
```

------
#### [ v2.1.x ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
 `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfiguration`   
(Optional) A list of log configurations for components on the core device. Each configuration in this list defines the log configuration for a component or application. The log manager component uploads these component logs to CloudWatch Logs  
Each object contains the following information:    
`componentName`  <a name="log-manager-component-configuration-component-component-name"></a>
The name of the component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

 `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfiguration": [
      {
        "componentName": "com.example.HelloWorld",
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    ]
  },
  "periodicUploadIntervalSec": "300"
}
```

------
#### [ v2.0.x ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
`systemLogsConfiguration`  
(Optional) The configuration for AWS IoT Greengrass Core software system logs. Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`componentLogsConfiguration`  
(Optional) A list of log configurations for components on the core device. Each configuration in this list defines the log configuration for a component or application. The log manager component uploads these component logs to CloudWatch Logs  
Each object contains the following information:    
`componentName`  <a name="log-manager-component-configuration-component-component-name"></a>
The name of the component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  
The path to the folder that contains this component's log files.  
To upload a Greengrass component's logs, specify **`/greengrass/v2`/logs**, and replace `/greengrass/v2` with your Greengrass root folder.  
`logFileRegex`  
A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
To upload a Greengrass component's logs, specify a regex that matches the rotated log file names. For example, you might specify **com.example.HelloWorld\$1\$1w\$1.log** to upload logs for a Hello World component. The `\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `com.example.HelloWorld.log` – The most recent log file for the Hello World component.
+ `com.example.HelloWorld_2020_12_15_17_0.log` – An older log file for the Hello World component. The Greengrass nucleus adds a rotating timestamp to the log files.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

`periodicUploadIntervalSec`  
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfiguration": [
      {
        "componentName": "com.example.HelloWorld",
        "minimumLogLevel": "INFO",
        "logFileDirectoryPath": "/greengrass/v2/logs",
        "logFileRegex": "com.example.HelloWorld\\w*.log",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    ]
  },
  "periodicUploadIntervalSec": "300"
}
```

------

## Usage
<a name="log-manager-component-usage"></a>

The log manager component uploads to the following log groups and log streams.

------
#### [ 2.1.0 and later ]<a name="log-manager-log-group-stream-format"></a>

**Log group name**  

```
/aws/greengrass/componentType/region/componentName
```
The log group name uses the following variables:  
+ `componentType` – The type of the component, which can be one of the following:
  + `GreengrassSystemComponent` – This log group includes logs for the nucleus and plugin components, which run in the same JVM as the Greengrass nucleus. The component is part of the [Greengrass nucleus](greengrass-nucleus-component.md).
  + `UserComponent` – This log group includes logs for generic components, Lambda components, and other applications on the device. The component isn't part of the Greengrass nucleus.

  For more information, see [Component types](develop-greengrass-components.md#component-types).
+ `region` – The AWS Region that the core device uses.
+ `componentName` – The name of the component. For system logs, this value is `System`.

**Log stream name**  

```
/date/thing/thingName
```
The log stream name uses the following variables:  
+ `date` – The date of the log, such as `2020/12/15`. The log manager component uses the `yyyy/MM/dd` format.
+ `thingName` – The name of the core device.
If a thing name contains a colon (`:`), the log manager replaces the colon with a plus (`+`).

------
#### [ 2.0.x ]

**Log group name**  

```
/aws/greengrass/componentType/region/componentName
```
The log group name uses the following variables:  
+ `componentType` – The type of the component, which can be one of the following:
  + `GreengrassSystemComponent` – The component is part of the [Greengrass nucleus](greengrass-nucleus-component.md).
  + `UserComponent` – The component isn't part of the Greengrass nucleus. The log manager uses this type for Greengrass components and other applications on the device.
+ `region` – The AWS Region that the core device uses.
+ `componentName` – The name of the component. For system logs, this value is `System`.

**Log stream name**  

```
/date/deploymentTargets/thingName
```
The log stream name uses the following variables:  
+ `date` – The date of the log, such as `2020/12/15`. The log manager component uses the `yyyy/MM/dd` format.
+ `deploymentTargets` – The things whose deployments include the component. The log manager component separates each target by a slash. If the component runs on the core device as the result of a local deployment, this value is `LOCAL_DEPLOYMENT`.

  Consider an example where you have a core device named `MyGreengrassCore`, and the core device has two deployments:
  + A deployment that targets the core device, `MyGreengrassCore`.
  + A deployment that targets a thing group named `MyGreengrassCoreGroup`, which contains the core device.

  The `deploymentTargets` for this core device are `thing/MyGreengrassCore/thinggroup/MyGreengrassCoreGroup`.
+ `thingName` – The name of the core device.

------

### Formats for log entries.
<a name="log-manager-entry-format"></a>

The Greengrass nucleus writes log files in either string or JSON format. For system logs, you control the format by setting the `format` field of the `logging` entry. You can find the `logging` entry in the Greengrass nucleus component's configuration file. For more information, see [Greengrass nucleus configuration](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html#greengrass-nucleus-component-configuration).

The text format is free-form and accepts any string. The following fleet status service message is an example of string formatted logging:

```
2023-03-26T18:18:27.271Z [INFO] (pool-1-thread-2)
com.aws.greengrass.status.FleetStatusService: fss-status-update-published. 
Status update published to FSS. {trigger=CADENCE, serviceName=FleetStatusService, 
currentState=RUNNING}
```

You should use the JSON format if you want to view logs with the [Greengrass CLI logs](https://docs.aws.amazon.com/greengrass/v2/developerguide/gg-cli-logs.html) command or interact with logs programmatically. The following example outlines the JSON shape:

```
{
   "loggerName": <string>,
   "level": <"DEBUG" | "INFO" | "ERROR" | "TRACE" | "WARN">,
   "eventType": <string, optional>,
   "cause": <string, optional>,
   "contexts": {},
   "thread": <string>,
   "message": <string>,
   "timestamp": <epoch time> # Needs to be epoch time
}
```

To control the output of your component's logs, you can use the `minimumLogLevel` configuration option. To use this option, your component must write its log entries in JSON format. You should use the same format as the system log file.

## Local log file
<a name="log-manager-component-log-file"></a>

This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog
<a name="log-manager-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.12  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  2.3.11  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.10  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.9  |  Version updated for Greengrass nucleus version 2.14.0 release.  | 
|  2.3.8  |  Version updated for Greengrass nucleus version 2.13.0 release.  | 
|  2.3.7  |  Version updated for Greengrass nucleus version 2.12.0 release.  | 
|  2.3.6  |  <a name="changelog-log-manager-2.3.6"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.5  |  <a name="changelog-log-manager-2.3.5"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html) Version updated for Greengrass nucleus version 2.11.0 release.  | 
|  2.3.4  |  <a name="changelog-log-manager-2.3.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.3  |  Version updated for Greengrass nucleus version 2.10.0 release.  | 
|  2.3.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.0  |   We recommend that you upgrade to Greengrass nucleus 2.9.1 when you upgrade to log manager 2.3.0.   [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.2.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.2.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.2.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.2.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.1  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  <a name="changelog-log-manager-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.1.0  |  <a name="changelog-log-manager-2.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.0.x  |  Initial version.  |