AWS - CloudWatchLogs
This Integration is part of the AWS - CloudWatchLogs Pack.#
Use the AWS CloudWatch Logs integration to monitor, store, and access your log files from AWS Elastic Compute Cloud (Amazon EC2) instances, AWS CloudTrail, AWS Route 53, and other sources. You can then retrieve the associated log data from CloudWatch Logs.
For more information see the
CloudWatch documentation
.
For detailed instructions about setting up authentication, see: AWS Integrations - Authentication .
Configure the AWS Cloud Watch Logs Integration on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services .
- Search for AWS - CloudWatchLogs.
-
Click
Add instance
to create and configure a new integration instance.
- Name : a textual name for the integration instance.
- Default Region
- Role Arn
- Role Session Name
- Role Session Duration
- Access Key
- Secret key
- Timeout
- Retries
- Click Test to validate the URLs, token, and connection.
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.
- Create a log group: aws-logs-create-log-group
- Create a log stream: aws-logs-create-log-stream
- Delete a log group: aws-logs-delete-log-group
- Delete a log stream: aws-logs-delete-log-stream
- Get a list of log events: aws-logs-filter-log-events
- Get a list of log groups: aws-logs-describe-log-groups
- Get a list of log streams: aws-logs-describe-log-streams
- Assign a retention policy for a log group: aws-logs-put-retention-policy
- Delete a retention policy: aws-logs-delete-retention-policy
- Upload log events to a log stream: aws-logs-put-log-events
- Create or modify a metric filter: aws-logs-put-metric-filter
- Delete a metric filter: aws-logs-delete-metric-filter
- Get a list of metric filters: aws-logs-describe-metric-filters
1. Create a log group
Creates a log group with the specified name.
Base Command
aws-logs-create-log-group
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| kmsKeyId | The Amazon Resource Name (ARN) of the CMK to use when encrypting log data. | Optional |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-create-log-group logGroupName=test
Context Example
There is no context output for this command.
Human Readable Output
2. Create a log stream
Creates a log stream for the specified log group.
Base Command
aws-logs-create-log-stream
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| logStreamName | The name of the log stream. | Required |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-create-log-stream logGroupName=test logStreamName=test
Context Example
There is no context output for this command.
Human Readable Output
3. Delete a log group
Deletes the specified log group and permanently deletes all the archived log events associated with the log group.
Base Command
aws-logs-delete-log-group
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-delete-log-group logGroupName=test
Context Example
There is no context output for this command.
Human Readable Output
4. Delete a log stream
Deletes the specified log stream and permanently deletes all the archived log events associated with the log stream.
Base Command
aws-logs-delete-log-stream
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| logStreamName | The name of the log stream. | Required |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-delete-log-stream logGroupName=test logStreamName=test
Context Example
There is no context output for this command.
Human Readable Output
5. Get list of log events
Lists log events from the specified log group. You can list all the log events or filter the results using a filter pattern, a time range, and the name of the log stream.
Base Command
aws-logs-filter-log-events
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| logStreamNames | Optional list of log stream names. Separated by comma. | Optional |
| startTime | The start of the time range, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC (Unix Time). Events with a time stamp before this time are not returned. | Optional |
| endTime | The end of the time range, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC (Unix Time). Events with a time stamp later than this time are not returned. | Optional |
| filterPattern | The filter pattern to use. If not provided, all the events are matched. | Optional |
| limit | The maximum number of events to return. The default is 10,000 events. | Optional |
| interleaved | If the value is true, the operation makes a best effort to provide responses that contain events from multiple log streams within the log group, interleaved in a single response. If the value is false, all the matched log events in the first log stream are searched first, then those in the next log stream, and so on. The default is false. | Optional |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AWS.CloudWatchLogs.Events.LogStreamName | string | The name of the log stream this event belongs to. |
| AWS.CloudWatchLogs.Events.Timestamp | date | The time the event occurred, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.Events.Message | string | The data contained in the log event. |
| AWS.CloudWatchLogs.Events.IngestionTime | date | The time the event was ingested, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.Events.EventId | string | The ID of the event. |
Command Example
!aws-logs-filter-log-events logGroupName=test
Context Example
Human Readable Output
6. Get a list of log groups
Lists the specified log groups. You can list all your log groups or filter the results by prefix. The results are ASCII-sorted by log group name.
Base Command
aws-logs-describe-log-groups
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupNamePrefix | The prefix to match. | Optional |
| limit | The maximum number of items returned. If you don't specify a value, the default is up to 50 items. | Optional |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AWS.CloudWatchLogs.LogGroups.LogGroupName | string | The name of the log group. |
| AWS.CloudWatchLogs.LogGroups.CreationTime | number | The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.LogGroups.RetentionInDays | number | The number of days to retain the log events in the specified log group. |
| AWS.CloudWatchLogs.LogGroups.MetricFilterCount | number | The number of metric filters. |
| AWS.CloudWatchLogs.LogGroups.Arn | string | The Amazon Resource Name (ARN) of the log group. |
| AWS.CloudWatchLogs.LogGroups.StoredBytes | number | The number of bytes stored. |
| AWS.CloudWatchLogs.LogGroups.KmsKeyId | string | The Amazon Resource Name (ARN) of the CMK to use when encrypting log data. |
Command Example
!aws-logs-describe-log-groups
Context Example
Human Readable Output
7. Get a list of log streams
Lists the log streams for the specified log group. You can list all the log streams or filter the results by prefix. You can also control how the results are ordered.
Base Command
aws-logs-describe-log-streams
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| logStreamNamePrefix | The prefix to match. If orderBy is LastEventTime ,you cannot specify this parameter. | Optional |
| orderBy | If the value is LogStreamName , the results are ordered by log stream name. If the value is LastEventTime , the results are ordered by the event time. The default value is LogStreamName .If you order the results by event time, you cannot specify the logStreamNamePrefix parameter. | Optional |
| limit | The maximum number of items returned. If you don't specify a value, the default is up to 50 items. | Optional |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AWS.CloudWatchLogs.LogGroups.LogStreams.LogGroupName | string | The Name of the log group. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.LogStreamName | string | The name of the log stream. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.CreationTime | number | The creation time of the stream, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.Arn | string | The Amazon Resource Name (ARN) of the log stream. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.FirstEventTimestamp | date | The time of the first event, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.LastEventTimestamp | date | the time of the most recent log event in the log stream in CloudWatch Logs. This number is expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. lastEventTime updates on an eventual consistency basis. It typically updates in less than an hour from ingestion, but may take longer in some rare situations. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.LastIngestionTime | date | The ingestion time, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.UploadSequenceToken | string | The sequence token. |
| AWS.CloudWatchLogs.LogGroups.LogStreams.StoredBytes | number | The number of bytes stored. |
Command Example
!aws-logs-describe-log-streams logGroupName=test
Context Example
Human Readable Output
8. Assign a retention policy for a log group
Sets the retention of the specified log group. A retention policy allows you to configure the number of days for which to retain log events in the specified log group.
Base Command
aws-logs-put-retention-policy
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| retentionInDays | The number of days to retain the log events in the specified log group. | Required |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-put-retention-policy logGroupName=test retentionInDays=7
Context Example
There is no context output for this command.
Human Readable Output
9. Delete a retention policy
Deletes the specified retention policy. Log events do not expire if they belong to log groups without a retention policy.
Base Command
aws-logs-delete-retention-policy
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
Context Output
There is no context output for this command.
Command Example
!aws-logs-delete-retention-policy logGroupName=test
Context Example
There is no context output for this command.
Human Readable Output
10. Upload log events to a log stream
Uploads a batch of log events to the specified log stream. You must include the sequence token obtained from the response of the previous call. An upload in a newly created log stream does not require a sequence token. You can also get the sequence token using DescribeLogStreams . If you call PutLogEvents twice within a narrow time period using the same value for sequenceToken , both calls may be successful, or one may be rejected.
Base Command
aws-logs-put-log-events
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| logStreamName | The name of the log stream. | Required |
| timestamp | The time the event occurred, expressed as the number of milliseconds fter Jan 1, 1970 00:00:00 UTC. (Unix Time) | Required |
| message | The raw event message. | Required |
| sequenceToken | The sequence token obtained from the response of the previous PutLogEvents call. An upload in a newly created log stream does not require a sequence token. You can also get the sequence token using DescribeLogStreams . If you call PutLogEvents twice within a narrow time period using the same value for sequenceToken , both calls may be successful, or one may be rejected. | Optional |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AWS.CloudWatchLogs.PutLogEvents.NextSequenceToken | string | The next sequence token. |
Command Example
!aws-logs-put-log-events logGroupName=test logStreamName=test message="test message" timestamp=1536063673395
Context Example
Human Readable Output
11. Create or modify a metric filter
Creates or updates a metric filter and associates it with the specified log group. Metric filters allow you to configure rules to extract metric data from log events ingested through PutLogEvents .
Base Command
aws-logs-put-metric-filter
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| filterName | A name for the metric filter. | Required |
| filterPattern | A filter pattern for extracting metric data out of ingested log events. | Required |
| metricName | The name of the CloudWatch metric. | Required |
| metricNamespace | The namespace of the CloudWatch metric. | Required |
| metricValue | The value to publish to the CloudWatch metric when a filter pattern matches a log event. | Required |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-put-metric-filter filterName=test filterPattern="Error" logGroupName=test metricName=test metricNamespace=LogMetrics metricValue=1
Context Example
There is no context output for this command.
Human Readable Output
12. Delete a metric filter
Deletes the specified metric filter.
Base Command
aws-logs-delete-metric-filter
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Required |
| filterName | The name of the metric filter. | Required |
| region | The AWS Region, if not specified the default region will be used. | Optional |
| roleArn | The Amazon Resource Name (ARN) of the role to assume. | Optional |
| roleSessionName | An identifier for the assumed role session. | Optional |
| roleSessionDuration | The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role. | Optional |
Context Output
There is no context output for this command.
Command Example
!aws-logs-delete-metric-filter filterName=test logGroupName=test
Context Example
There is no context output for this command.
Human Readable Output
13. Get a list of metric filters
Lists the specified metric filters. You can list all the metric filters or filter the results by log name, prefix, metric name, or metric namespace.
Base Command
aws-logs-describe-metric-filters
Input
| Argument Name | Description | Required |
|---|---|---|
| logGroupName | The name of the log group. | Optional |
| filterNamePrefix | The prefix to match. | Optional |
| metricName | Filters results to include only those with the specified metric name. If you include this parameter in your request, you must also include the metricNamespace parameter. | Optional |
| metricNamespace | Filters results to include only those in the specified namespace. If you include this parameter in your request, you must also include the metricName parameter. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AWS.CloudWatchLogs.MetricFilters.filterName | string | The name of the metric filter. |
| AWS.CloudWatchLogs.MetricFilters.filterPattern | string | A symbolic description of how CloudWatch Logs should interpret the data in each log event. For example, a log event may contain time stamps, IP addresses, strings, and so on. You use the filter pattern to specify what to look for in the log event message. |
| AWS.CloudWatchLogs.MetricFilters.metricTransformations.metricName | string | The name of the CloudWatch metric. |
| AWS.CloudWatchLogs.MetricFilters.metricTransformations.metricNamespace | string | The namespace of the CloudWatch metric. |
| AWS.CloudWatchLogs.MetricFilters.metricTransformations.metricValue | string | The value to publish to the CloudWatch metric when a filter pattern matches a log event. |
| AWS.CloudWatchLogs.MetricFilters.metricTransformations.defaultValue | string | The value to emit when a filter pattern does not match a log event. This value can be null. |
| AWS.CloudWatchLogs.MetricFilters.creationTime | date | The creation time of the metric filter, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. |
| AWS.CloudWatchLogs.MetricFilters.logGroupName | string | The name of the log group. |
Command Example
!aws-logs-describe-metric-filters
Context Example
Human Readable Output
