feat(cloudtrail): enable CloudTrail Insights on Trail (#23099)

After an issue is submitted, the specification is added and the implementation is such that the InsightType is selected.

fixes #8335 

----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [x] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [x] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-cloudtrail/README.md

@@ -197,3 +197,17 @@ new cloudtrail.Trail(this, 'OrganizationTrail', {
   isOrganizationTrail: true,
 });
 ```
+
+## CloudTrail Insights
+
+Set `InsightSelector` to enable Insight.
+Insights selector values can be `ApiCallRateInsight`, `ApiErrorRateInsight`, or both.
+
+```ts
+new Trail(stack, 'Insights', {
+    insightTypes: [
+      InsightType.API_CALL_RATE,
+      InsightType.API_ERROR_RATE,
+    ],
+});
+```

packages/@aws-cdk/aws-cloudtrail/lib/cloudtrail.ts

@@ -127,6 +127,13 @@ export interface TrailProps {
    * @default - false
    */
   readonly isOrganizationTrail?: boolean
+
+  /**
+   * A JSON string that contains the insight types you want to log on a trail.
+   *
+   * @default - No Value.
+   */
+  readonly insightTypes?: InsightType[]
 }
 
 /**
@@ -158,6 +165,23 @@ export enum ReadWriteType {
   NONE = 'None',
 }
 
+/**
+ * Util element for InsightSelector
+ */
+export class InsightType {
+  /**
+   * The type of insights to log on a trail. (API Call Rate)
+   */
+  public static readonly API_CALL_RATE = new InsightType('ApiCallRateInsight');
+
+  /**
+   * The type of insights to log on a trail. (API Error Rate)
+   */
+  public static readonly API_ERROR_RATE = new InsightType('ApiErrorRateInsight');
+
+  protected constructor(public readonly value: string) {}
+}
+
 /**
  * Cloud trail allows you to log events that happen in your AWS account
  * For example:
@@ -213,6 +237,7 @@ export class Trail extends Resource {
   private s3bucket: s3.IBucket;
   private eventSelectors: EventSelector[] = [];
   private topic: sns.ITopic | undefined;
+  private insightTypeValues: InsightSelector[] | undefined;
 
   constructor(scope: Construct, id: string, props: TrailProps = {}) {
     super(scope, id, {
@@ -283,6 +308,12 @@ export class Trail extends Resource {
       throw new Error('Both kmsKey and encryptionKey must not be specified. Use only encryptionKey');
     }
 
+    if (props.insightTypes) {
+      this.insightTypeValues = props.insightTypes.map(function(t) {
+        return { insightType: t.value };
+      });
+    }
+
     // TODO: not all regions support validation. Use service configuration data to fail gracefully
     const trail = new CfnTrail(this, 'Resource', {
       isLogging: true,
@@ -298,6 +329,7 @@ export class Trail extends Resource {
       snsTopicName: this.topic?.topicName,
       eventSelectors: this.eventSelectors,
       isOrganizationTrail: props.isOrganizationTrail,
+      insightSelectors: this.insightTypeValues,
     });
 
     this.trailArn = this.getResourceArnAttribute(trail.attrArn, {
@@ -502,3 +534,7 @@ interface EventSelectorData {
   readonly type: string;
   readonly values: string[];
 }
+
+interface InsightSelector {
+  readonly insightType?: string;
+}

packages/@aws-cdk/aws-cloudtrail/package.json

@@ -115,7 +115,8 @@
   },
   "awslint": {
     "exclude": [
-      "events-method-signature:@aws-cdk/aws-cloudtrail.Trail.onEvent"
+      "events-method-signature:@aws-cdk/aws-cloudtrail.Trail.onEvent",
+      "docs-public-apis:@aws-cdk/aws-cloudtrail.InsightType.value"
     ]
   },
   "engines": {

packages/@aws-cdk/aws-cloudtrail/test/cloudtrail.test.ts

@@ -7,7 +7,7 @@ import * as s3 from '@aws-cdk/aws-s3';
 import * as sns from '@aws-cdk/aws-sns';
 import { testDeprecated } from '@aws-cdk/cdk-build-tools';
 import { Stack } from '@aws-cdk/core';
-import { ManagementEventSources, ReadWriteType, Trail } from '../lib';
+import { ManagementEventSources, ReadWriteType, Trail, InsightType } from '../lib';
 
 const ExpectedBucketPolicyProperties = {
   PolicyDocument: {
@@ -702,4 +702,79 @@ describe('cloudtrail', () => {
       });
     });
   });
-});
+  describe('insights ', () => {
+    test('no properties', () => {
+      const stack = getTestStack();
+      new Trail(stack, 'MyAmazingCloudTrail', {
+        insightTypes: [],
+      });
+      Template.fromStack(stack).hasResourceProperties('AWS::CloudTrail::Trail', {
+        InsightSelectors: [],
+      });
+    });
+    test('API Call Rate properties', () => {
+      const stack = getTestStack();
+      new Trail(stack, 'MyAmazingCloudTrail', {
+        insightTypes: [
+          InsightType.API_CALL_RATE,
+        ],
+      });
+      Template.fromStack(stack).hasResourceProperties('AWS::CloudTrail::Trail', {
+        InsightSelectors: [{
+          InsightType: 'ApiCallRateInsight',
+        }],
+      });
+    });
+    test('API Error Rate properties', () => {
+      const stack = getTestStack();
+      new Trail(stack, 'MyAmazingCloudTrail', {
+        insightTypes: [
+          InsightType.API_ERROR_RATE,
+        ],
+      });
+      Template.fromStack(stack).hasResourceProperties('AWS::CloudTrail::Trail', {
+        InsightSelectors: [{
+          InsightType: 'ApiErrorRateInsight',
+        }],
+      });
+    });
+    test('duplicate properties', () => {
+      const stack = getTestStack();
+      new Trail(stack, 'MyAmazingCloudTrail', {
+        insightTypes: [
+          InsightType.API_CALL_RATE,
+          InsightType.API_CALL_RATE,
+        ],
+      });
+      Template.fromStack(stack).hasResourceProperties('AWS::CloudTrail::Trail', {
+        InsightSelectors: [
+          {
+            InsightType: 'ApiCallRateInsight',
+          },
+          {
+            InsightType: 'ApiCallRateInsight',
+          },
+        ],
+      });
+    });
+    test('ALL properties', () => {
+      const stack = getTestStack();
+      new Trail(stack, 'MyAmazingCloudTrail', {
+        insightTypes: [
+          InsightType.API_CALL_RATE,
+          InsightType.API_ERROR_RATE,
+        ],
+      });
+      Template.fromStack(stack).hasResourceProperties('AWS::CloudTrail::Trail', {
+        InsightSelectors: [
+          {
+            InsightType: 'ApiCallRateInsight',
+          },
+          {
+            InsightType: 'ApiErrorRateInsight',
+          },
+        ],
+      });
+    });
+  });
+});

packages/@aws-cdk/aws-cloudtrail/test/integ.cloudtrail-insight.js.snapshot/aws-cdk-cloudtrail-inshights-test.assets.json

@@ -0,0 +1,32 @@
+{
+  "version": "22.0.0",
+  "files": {
+    "33e2651435a0d472a75c1e033c9832b21321d9e56711926b04c5705e5f63874c": {
+      "source": {
+        "path": "asset.33e2651435a0d472a75c1e033c9832b21321d9e56711926b04c5705e5f63874c",
+        "packaging": "zip"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "33e2651435a0d472a75c1e033c9832b21321d9e56711926b04c5705e5f63874c.zip",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    },
+    "9e54867c184c79374c51ba171db494a5736a30294e618efa94e199b94e58868e": {
+      "source": {
+        "path": "aws-cdk-cloudtrail-inshights-test.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "9e54867c184c79374c51ba171db494a5736a30294e618efa94e199b94e58868e.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}