# LogGroup

Define a CloudWatch Log Group.

Extends: Construct › Resource › LogGroup
Implements: IResource, IResourceWithPolicy, IResourceWithPolicyV2, ILogGroup, IEnvironmentAware, ILogGroupRef, IConstruct, IDependable

- CloudFormation: [`AWS::Logs::LogGroup`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-logs-loggroup.html)
- L1 type: [`CfnLogGroup`](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.CfnLogGroup.html)
- Source: [`aws-logs/lib/log-group.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-logs/lib/log-group.ts#L637)
- Type last changed: v2.227.0 · 21 Nov 2025

## Example

```ts
import * as logs from 'aws-cdk-lib/aws-logs';

const logGroup = new logs.LogGroup(this, 'Log Group');
const logBucket = new s3.Bucket(this, 'S3 Bucket')

new tasks.EmrContainersStartJobRun(this, 'EMR Containers Start Job Run', {
  virtualCluster: tasks.VirtualClusterInput.fromVirtualClusterId('de92jdei2910fwedz'),
  releaseLabel: tasks.ReleaseLabel.EMR_6_2_0,
  jobDriver: {
    sparkSubmitJobDriver: {
      entryPoint: sfn.TaskInput.fromText('local:///usr/lib/spark/examples/src/main/python/pi.py'),
      sparkSubmitParameters: '--conf spark.executor.instances=2 --conf spark.executor.memory=2G --conf spark.executor.cores=2 --conf spark.driver.cores=1',
    },
  },
  monitoring: {
    logGroup: logGroup,
    logBucket: logBucket,
  },
});
```

## Initializer

```ts
new LogGroup(scope: Construct, id: string, props?: LogGroupProps)
```

## Construct Props

- `dataProtectionPolicy`: [DataProtectionPolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.DataProtectionPolicy.html) — Data Protection Policy for this log group.

  **Default:** no data protection policy

- `deletionProtectionEnabled`: boolean = false — Indicates whether deletion protection is enabled for this log group.

  When enabled,
  deletion protection blocks all deletion operations until it is explicitly disabled.

- `encryptionKey`: [IKeyRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_kms.IKeyRef.html) — The KMS customer managed key to encrypt the log group with.

  **Default:** Server-side encryption managed by the CloudWatch Logs service

- `fieldIndexPolicies`: [FieldIndexPolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.FieldIndexPolicy.html)[] — Field Index Policies for this log group.

  **Default:** no field index policies for this log group.

- `logGroupClass`: [LogGroupClass](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroupClass.html) = LogGroupClass.STANDARD — The class of the log group. Possible values are: STANDARD, INFREQUENT_ACCESS and DELIVERY.

  INFREQUENT_ACCESS class provides customers a cost-effective way to consolidate
  logs which supports querying using Logs Insights. The logGroupClass property cannot
  be changed once the log group is created.

  DELIVERY class is used to deliver logs to a destination such as Amazon S3 or Amazon
  Data Firehose (for example, Lambda vended logs). A Delivery log group forwards events
  to a destination instead of storing them, so it does not support `retention`,
  `dataProtectionPolicy`, or `fieldIndexPolicies`; setting any of these together with
  `LogGroupClass.DELIVERY` results in a synthesis-time error.

- `logGroupName`: string — Name of the log group.

  **Default:** Automatically generated

- `removalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) = RemovalPolicy.Retain — Determine the removal policy of this log group.

  Normally you want to retain the log group so you can diagnose issues
  from logs even after a deployment that no longer includes the log group.
  In that case, use the normal date-based retention policy to age out your
  logs.

- `retention`: [RetentionDays](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.RetentionDays.html) = RetentionDays.TWO_YEARS — How long, in days, the log contents will be retained.

  To retain all logs, set this value to RetentionDays.INFINITE.

## Properties

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `grants`: [LogGroupGrants](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroupGrants.html) — Collection of grant methods for a LogGroup.

- `logGroupArn`: string — The ARN of this log group.

- `logGroupName`: string — The name of this log group.

- `logGroupRef`: [LogGroupReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_logs.LogGroupReference.html) — A reference to a LogGroup resource.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this resource is defined.

## Methods

- `addMetricFilter(id: string, props: MetricFilterOptions): MetricFilter` — Create a new Metric Filter on this Log Group.

  **Parameters**

  - `id` — Unique identifier for the construct in its parent.
  - `props` — Properties for creating the MetricFilter.

- `addStream(id: string, props?: StreamOptions): LogStream` — Create a new Log Stream for this Log Group.

  **Parameters**

  - `id` — Unique identifier for the construct in its parent.
  - `props` — Properties for creating the LogStream.

- `addSubscriptionFilter(id: string, props: SubscriptionFilterOptions): SubscriptionFilter` — Create a new Subscription Filter on this Log Group.

  **Parameters**

  - `id` — Unique identifier for the construct in its parent.
  - `props` — Properties for creating the SubscriptionFilter.

- `addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult` — Adds a statement to the resource policy associated with this log group.

  A resource policy will be automatically created upon the first call to `addToResourcePolicy`.

  Any ARN Principals inside of the statement will be converted into AWS Account ID strings
  because CloudWatch Logs Resource Policies do not accept ARN principals.

  **Parameters**

  - `statement` — The policy statement to add.

- `addTransformer(id: string, props: TransformerOptions): Transformer` — Create a new Transformer on this Log Group.

  **Parameters**

  - `id` — Unique identifier for the construct in its parent.
  - `props` — Properties for creating the Transformer.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — Apply the given removal policy to this resource.

  The Removal Policy controls what happens to this resource when it stops
  being managed by CloudFormation, either because you've removed it from the
  CDK application or because you've made a change that requires the resource
  to be replaced.

  The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS
  account for data recovery and cleanup later (`RemovalPolicy.RETAIN`).

- `extractMetric(jsonField: string, metricNamespace: string, metricName: string): Metric` — Extract a metric from structured log events in the LogGroup.

  Creates a MetricFilter on this LogGroup that will extract the value
  of the indicated JSON field in all records where it occurs.

  The metric will be available in CloudWatch Metrics under the
  indicated namespace and name.

  **Parameters**

  - `jsonField` — JSON field to extract (example: '$.myfield').
  - `metricNamespace` — Namespace to emit the metric under.
  - `metricName` — Name to emit the metric under.

  **Returns:** A Metric object representing the extracted metric

- `fromLogGroupArn(scope: Construct, id: string, logGroupArn: string): ILogGroup` (static) — Import an existing LogGroup given its ARN.

- `fromLogGroupName(scope: Construct, id: string, logGroupName: string): ILogGroup` (static) — Import an existing LogGroup given its name.

- `grant(grantee: IGrantable, ...actions: string[]): Grant` — Give the indicated permissions on this log group and all streams.

  [disable-awslint:no-grants]

- `grantRead(grantee: IGrantable): Grant` — Give permissions to read and filter events from this log group.

  The use of this method is discouraged. Please use `grants.read()` instead.

  [disable-awslint:no-grants]

- `grantWrite(grantee: IGrantable): Grant` — Give permissions to create and write to streams in this log group.

  The use of this method is discouraged. Please use `grants.write()` instead.

  [disable-awslint:no-grants]

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `logGroupPhysicalName(): string` — Public method to get the physical name of this log group.

  **Returns:** Physical name of log group

- `metric(metricName: string, props?: MetricOptions): Metric` — Creates a CloudWatch metric for this log group.

  **Parameters**

  - `metricName` — - The name of the metric to create.
  - `props` — - Optional.

  **Returns:** A CloudWatch Metric object representing the specified metric for this log group. This method creates a CloudWatch Metric object with predefined settings for the log group. It sets the namespace to 'AWS/Logs' and the statistic to 'Sum' by default. The created metric is automatically associated with this log group using the `attachTo` method. Common metric names for log groups include: - 'IncomingBytes': The volume of log data in bytes ingested into the log group. - 'IncomingLogEvents': The number of log events ingested into the log group. ```

- `metricIncomingBytes(props?: MetricOptions): Metric` — Creates a CloudWatch metric for the volume of incoming log data in bytes to this log group.

  **Parameters**

  - `props` — - Optional.

  **Returns:** A CloudWatch Metric object representing the IncomingBytes metric. This method allows you to monitor the volume of data being ingested into the log group. It's useful for understanding the size of your logs, which can impact storage costs and help in identifying unexpectedly large log entries. Example usage: ``` const logGroup = new logs.LogGroup(this, 'MyLogGroup'); logGroup.metricIncomingBytes().createAlarm(stack, 'IncomingBytesPerInstanceAlarm', { threshold: 1, evaluationPeriods: 1, }); ```

- `metricIncomingLogEvents(props?: MetricOptions): Metric` — Creates a CloudWatch metric for the number of incoming log events to this log group.

  **Parameters**

  - `props` — - Optional.

  **Returns:** A CloudWatch Metric object representing the IncomingLogEvents metric. This method allows you to monitor the rate at which log events are being ingested into the log group. It's useful for understanding the volume of logging activity and can help in capacity planning or detecting unusual spikes in logging. Example usage: ``` const logGroup = new logs.LogGroup(this, 'MyLogGroup'); logGroup.metricIncomingLogEvents().createAlarm(stack, 'IncomingEventsPerInstanceAlarm', { threshold: 1, evaluationPeriods: 1, }); ```

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.