feat(logs): add support for fieldIndexPolicies in log group L2 Construct

packages/@aws-cdk-testing/framework-integ/test/aws-logs/test/integ.log-group.js.snapshot/aws-cdk-log-group-integ.template.json

@@ -112,6 +112,14 @@
       ]
      }
     },
+    "FieldIndexPolicies": [
+     {
+      "Fields": [
+       "Operation",
+       "RequestId"
+      ]
+     }
+    ],
     "RetentionInDays": 731
    },
    "UpdateReplacePolicy": "Retain",

packages/@aws-cdk-testing/framework-integ/test/aws-logs/test/integ.log-group.ts

@@ -1,7 +1,7 @@
 import { Bucket } from 'aws-cdk-lib/aws-s3';
 import { App, Stack, StackProps } from 'aws-cdk-lib';
 import { IntegTest } from '@aws-cdk/integ-tests-alpha';
-import { LogGroup, DataProtectionPolicy, DataIdentifier, CustomDataIdentifier } from 'aws-cdk-lib/aws-logs';
+import { LogGroup, DataProtectionPolicy, DataIdentifier, CustomDataIdentifier, FieldIndexPolicy } from 'aws-cdk-lib/aws-logs';
 
 class LogGroupIntegStack extends Stack {
   constructor(scope: App, id: string, props?: StackProps) {
@@ -19,8 +19,13 @@ class LogGroupIntegStack extends Stack {
       s3BucketAuditDestination: bucket,
     });
 
+    const fieldIndexPolicy = new FieldIndexPolicy({
+      fields: ['Operation', 'RequestId'],
+    });
+
     new LogGroup(this, 'LogGroupLambda', {
       dataProtectionPolicy: dataProtectionPolicy,
+      fieldIndexPolicies: [fieldIndexPolicy],
     });
   }
 }

packages/aws-cdk-lib/aws-logs/README.md

@@ -441,6 +441,29 @@ new logs.LogGroup(this, 'LogGroupLambda', {
 });
 ```
 
+## Field Index Policies
+
+Creates or updates a field index policy for the specified log group. You can use field index policies to create field indexes on fields found in log events in the log group. Creating field indexes lowers the costs for CloudWatch Logs Insights queries that reference those field indexes, because these queries attempt to skip the processing of log events that are known to not match the indexed field. Good fields to index are fields that you often need to query for and fields that have high cardinality of values.
+
+For more information, see [Create field indexes to improve query performance and reduce costs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs-Field-Indexing.html).
+
+Only log groups in the Standard log class support field index policies.
+Currently, this array supports only one field index policy object.
+
+Example:
+
+```ts
+
+const fieldIndexPolicy = new logs.FieldIndexPolicy({
+  fields: ['Operation', 'RequestId'],
+});
+
+new logs.LogGroup(this, 'LogGroup', {
+  logGroupName: 'cdkIntegLogGroup',
+  fieldIndexPolicies: [fieldIndexPolicy],
+});
+```
+
 ## Notes
 
 Be aware that Log Group ARNs will always have the string `:*` appended to

packages/aws-cdk-lib/aws-logs/lib/field-index-policy.ts

@@ -0,0 +1,34 @@
+import { Construct } from 'constructs';
+
+/**
+ * Creates a field index policy for CloudWatch Logs log groups.
+ */
+export class FieldIndexPolicy {
+  private readonly fieldIndexPolicyProps: FieldIndexPolicyProps;
+
+  constructor(props: FieldIndexPolicyProps) {
+    if (props.fields.length > 20) {
+      throw new Error('A maximum of 20 fields can be indexed per log group');
+    }
+    this.fieldIndexPolicyProps = props;
+  }
+
+  /**
+   * @internal
+   */
+  public _bind(_scope: Construct) {
+    return { Fields: this.fieldIndexPolicyProps.fields };
+  }
+}
+
+/**
+ * Properties for creating field index policies
+ */
+export interface FieldIndexPolicyProps {
+  /**
+   * List of fields to index in log events.
+   *
+   * @default no fields
+   */
+  readonly fields: string[];
+}

packages/aws-cdk-lib/aws-logs/lib/index.ts

@@ -8,6 +8,7 @@ export * from './log-retention';
 export * from './policy';
 export * from './query-definition';
 export * from './data-protection-policy';
+export * from './field-index-policy';
 
 // AWS::Logs CloudFormation Resources:
 export * from './logs.generated';

packages/aws-cdk-lib/aws-logs/lib/log-group.ts

@@ -1,5 +1,6 @@
 import { Construct } from 'constructs';
 import { DataProtectionPolicy } from './data-protection-policy';
+import { FieldIndexPolicy } from './field-index-policy';
 import { LogStream } from './log-stream';
 import { CfnLogGroup } from './logs.generated';
 import { MetricFilter } from './metric-filter';
@@ -506,6 +507,13 @@ export interface LogGroupProps {
    */
   readonly dataProtectionPolicy?: DataProtectionPolicy;
 
+  /**
+   * Field Index Policies for this log group.
+   *
+   * @default - no field index policies for this log group.
+   */
+  readonly fieldIndexPolicies?: FieldIndexPolicy[];
+
   /**
    * How long, in days, the log contents will be retained.
    *
@@ -630,6 +638,12 @@ export class LogGroup extends LogGroupBase {
     }
 
     const dataProtectionPolicy = props.dataProtectionPolicy?._bind(this);
+    const fieldIndexPolicies: any[] = [];
+    if (props.fieldIndexPolicies) {
+      props.fieldIndexPolicies.forEach((fieldIndexPolicy) => {
+        fieldIndexPolicies.push(fieldIndexPolicy._bind(this));
+      });
+    }
 
     const resource = new CfnLogGroup(this, 'Resource', {
       kmsKeyId: props.encryptionKey?.keyArn,
@@ -643,6 +657,7 @@ export class LogGroup extends LogGroupBase {
         Statement: dataProtectionPolicy?.statement,
         Configuration: dataProtectionPolicy?.configuration,
       } : undefined,
+      ...(props.fieldIndexPolicies && { fieldIndexPolicies: fieldIndexPolicies }),
     });
 
     resource.applyRemovalPolicy(props.removalPolicy);

packages/aws-cdk-lib/aws-logs/test/loggroup.test.ts

@@ -4,7 +4,7 @@ import * as iam from '../../aws-iam';
 import * as kms from '../../aws-kms';
 import { Bucket } from '../../aws-s3';
 import { App, CfnParameter, Fn, RemovalPolicy, Stack } from '../../core';
-import { LogGroup, RetentionDays, LogGroupClass, DataProtectionPolicy, DataIdentifier, CustomDataIdentifier, ILogGroup, ILogSubscriptionDestination, FilterPattern } from '../lib';
+import { LogGroup, RetentionDays, LogGroupClass, DataProtectionPolicy, DataIdentifier, CustomDataIdentifier, ILogGroup, ILogSubscriptionDestination, FilterPattern, FieldIndexPolicy } from '../lib';
 
 describe('log group', () => {
   test('set kms key when provided', () => {
@@ -921,6 +921,66 @@ describe('log group', () => {
   });
 });
 
+test('set field index policy with four fields indexed', () => {
+  // GIVEN
+  const stack = new Stack();
+
+  const fieldIndexPolicy = new FieldIndexPolicy({
+    fields: ['Operation', 'RequestId', 'timestamp', 'message'],
+  });
+
+  // WHEN
+  const logGroupName = 'test-field-index-log-group';
+  new LogGroup(stack, 'LogGroup', {
+    logGroupName: logGroupName,
+    fieldIndexPolicies: [fieldIndexPolicy],
+  });
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::Logs::LogGroup', {
+    LogGroupName: logGroupName,
+    FieldIndexPolicies: [{
+      Fields: [
+        'Operation',
+        'RequestId',
+        'timestamp',
+        'message',
+      ],
+    }],
+  });
+});
+
+test('set more than 20 field indexes in a field index policy', () => {
+  let message;
+  try {
+    // GIVEN
+    const stack = new Stack();
+    const fieldIndexPolicy = new FieldIndexPolicy({
+      fields: createMoreThan20FieldIndexes(),
+    });
+
+    // WHEN
+    const logGroupName = 'test-field-multiple-field-index-policies';
+    new LogGroup(stack, 'LogGroup', {
+      logGroupName: logGroupName,
+      fieldIndexPolicies: [fieldIndexPolicy],
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::Logs::LogGroup', {
+      LogGroupName: logGroupName,
+      FieldIndexPolicies: [{
+        Fields: ['abc'],
+      }],
+    });
+  } catch (e) {
+    message = (e as Error).message;
+  }
+
+  expect(message).toBeDefined();
+  expect(message).toEqual('A maximum of 20 fields can be indexed per log group');
+});
+
 describe('subscription filter', () => {
   test('add subscription filter with custom name', () => {
     // GIVEN
@@ -953,6 +1013,14 @@ function dataDrivenTests(cases: string[], body: (suffix: string) => void): void
   }
 }
 
+function createMoreThan20FieldIndexes(): string[] {
+  let arr: string[] = [];
+  for (let i = 0; i < 23; i++) {
+    arr.push('abc' + i.toString());
+  }
+  return arr;
+}
+
 class FakeDestination implements ILogSubscriptionDestination {
   public bind(_scope: Construct, _sourceLogGroup: ILogGroup) {
     return {