From dbf7237dec2bfa8075ea9d170aaef860894bd30d Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Wed, 17 Jan 2024 10:49:24 +0000 Subject: [PATCH 1/4] fix(lambda): deprecate `logRetention` properties in favor of `logGroup` --- .../aws-cdk-lib/aws-lambda/lib/function.ts | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/packages/aws-cdk-lib/aws-lambda/lib/function.ts b/packages/aws-cdk-lib/aws-lambda/lib/function.ts index 54954dd5b6725..37199474aec23 100644 --- a/packages/aws-cdk-lib/aws-lambda/lib/function.ts +++ b/packages/aws-cdk-lib/aws-lambda/lib/function.ts @@ -385,6 +385,15 @@ export interface FunctionOptions extends EventInvokeConfigOptions { * remove the retention policy, set the value to `INFINITE`. * * @default logs.RetentionDays.INFINITE + * + * @deprecated instead create a fully customizable log group with `logs.LogGroup` and use the `logGroup` property to instruct the Lambda function to send logs to it. + * Migrating from `logRetention` to `logGroup` will cause the name of the log group to change. + * Users and code and referencing the name verbatim will have to adjust.\ + * In AWS CDK code, you can access the log group name directly from the LogGroup construct: + * ```ts + * declare const myLogGroup: logs.LogGroup; + * myLogGroup.logGroupName; + * ``` */ readonly logRetention?: logs.RetentionDays; @@ -393,6 +402,8 @@ export interface FunctionOptions extends EventInvokeConfigOptions { * that sets the retention policy. * * @default - A new role is created. + * + * @deprecated instead use `logGroup` to create a fully customizable log group and instruct the Lambda function to send logs to it. */ readonly logRetentionRole?: iam.IRole; @@ -401,6 +412,8 @@ export interface FunctionOptions extends EventInvokeConfigOptions { * These options control the retry policy when interacting with CloudWatch APIs. * * @default - Default AWS SDK retry options. + * + * @deprecated instead use `logGroup` to create a fully customizable log group and instruct the Lambda function to send logs to it. */ readonly logRetentionRetryOptions?: LogRetentionRetryOptions; @@ -461,26 +474,32 @@ export interface FunctionOptions extends EventInvokeConfigOptions { readonly runtimeManagementMode?: RuntimeManagementMode; /** - * Sets the log group name for the function. - * @default `/aws/lambda/${this.functionName}` default log group name created by Lambda + * The log group the function sends logs to. + * + * By default, Lambda functions send logs to an automatically created default log group named /aws/lambda/. + * However you cannot change the properties of this auto-created log group using the AWS CDK, e.g. you cannot set a different log retention. + * + * Use the `logGroup` property to create a fully customizable LogGroup ahead of time, and instruct the Lambda function to send logs to it. + * + * @default `/aws/lambda/${this.functionName}` - default log group created by Lambda */ readonly logGroup?: logs.ILogGroup; /** * Sets the logFormat for the function. - * @default Text format + * @default "Text" */ readonly logFormat?: string; /** * Sets the application log level for the function. - * @default INFO + * @default "INFO" */ readonly applicationLogLevel?: string; /** * Sets the system log level for the function. - * @default INFO + * @default "INFO" */ readonly systemLogLevel?: string; } From 8dfaa9d5d4eecae2e44c0d0c1e8d4374cbb7a505 Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Wed, 17 Jan 2024 11:14:22 +0000 Subject: [PATCH 2/4] updated readme --- packages/aws-cdk-lib/aws-lambda/README.md | 33 ++++++++++++----------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/packages/aws-cdk-lib/aws-lambda/README.md b/packages/aws-cdk-lib/aws-lambda/README.md index c3f02f90189cf..850623b053b06 100644 --- a/packages/aws-cdk-lib/aws-lambda/README.md +++ b/packages/aws-cdk-lib/aws-lambda/README.md @@ -988,24 +988,28 @@ See [the AWS documentation](https://docs.aws.amazon.com/lambda/latest/dg/invocat ## Log Group -Lambda functions automatically create a log group with the name `/aws/lambda/` upon first execution with +By default, Lambda functions automatically create a log group with the name `/aws/lambda/` upon first execution with log data set to never expire. +This is convenient, but prevents you from changing any of the properties of this auto-created log group using the AWS CDK. +For example you cannot set log retention or assign a data protection policy. -The `logRetention` property can be used to set a different expiration period. +To fully customize the logging behavior of your Lambda function, create a `logs.LogGroup` ahead of time and use the `logGroup` property to instruct the Lambda function to send logs to it. +This way you can use the full features set supported by Amazon CloudWatch Logs. -It is possible to obtain the function's log group as a `logs.ILogGroup` by calling the `logGroup` property of the -`Function` construct. - -By default, CDK uses the AWS SDK retry options when creating a log group. The `logRetentionRetryOptions` property -allows you to customize the maximum number of retries and base backoff duration. +```ts +import { LogGroup } from 'aws-cdk-lib/aws-logs'; -*Note* that, if either `logRetention` is set or `logGroup` property is called, a [CloudFormation custom -resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html) is added -to the stack that pre-creates the log group as part of the stack deployment, if it already doesn't exist, and sets the -correct log retention period (never expire, by default). +const myLogGroup = new logs.LogGroup(stack, 'MyLogGroupWithLogGroupName', { + logGroupName: 'customLogGroup', +}); -*Further note* that, if the log group already exists and the `logRetention` is not set, the custom resource will reset -the log retention to never expire even if it was configured with a different value. +new lambda.Function(this, 'Lambda', { + code: new lambda.InlineCode('foo'), + handler: 'index.handler', + runtime: lambda.Runtime.NODEJS_18_X, + logGroup: myLogGroup, +}); +``` ## FileSystem Access @@ -1082,8 +1086,7 @@ A typical use case of this function is when a higher level construct needs to de needs to guarantee that the function is declared once. However, a user of this higher level construct can declare it any number of times and with different properties. Using `SingletonFunction` here with a fixed `uuid` will guarantee this. -For example, the `LogRetention` construct requires only one single lambda function for all different log groups whose -retention it seeks to manage. +For example, the `AwsCustomResource` construct requires only one single lambda function for all api calls that are made. ## Bundling Asset Code From d92e7a64131230aef260cf0ec7401cf0a0df2208 Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Wed, 17 Jan 2024 11:49:58 +0000 Subject: [PATCH 3/4] fix whitespace --- packages/aws-cdk-lib/aws-lambda/lib/function.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/aws-cdk-lib/aws-lambda/lib/function.ts b/packages/aws-cdk-lib/aws-lambda/lib/function.ts index 37199474aec23..763085046c2fe 100644 --- a/packages/aws-cdk-lib/aws-lambda/lib/function.ts +++ b/packages/aws-cdk-lib/aws-lambda/lib/function.ts @@ -385,11 +385,11 @@ export interface FunctionOptions extends EventInvokeConfigOptions { * remove the retention policy, set the value to `INFINITE`. * * @default logs.RetentionDays.INFINITE - * + * * @deprecated instead create a fully customizable log group with `logs.LogGroup` and use the `logGroup` property to instruct the Lambda function to send logs to it. * Migrating from `logRetention` to `logGroup` will cause the name of the log group to change. * Users and code and referencing the name verbatim will have to adjust.\ - * In AWS CDK code, you can access the log group name directly from the LogGroup construct: + * In AWS CDK code, you can access the log group name directly from the LogGroup construct: * ```ts * declare const myLogGroup: logs.LogGroup; * myLogGroup.logGroupName; @@ -402,7 +402,7 @@ export interface FunctionOptions extends EventInvokeConfigOptions { * that sets the retention policy. * * @default - A new role is created. - * + * * @deprecated instead use `logGroup` to create a fully customizable log group and instruct the Lambda function to send logs to it. */ readonly logRetentionRole?: iam.IRole; @@ -412,7 +412,7 @@ export interface FunctionOptions extends EventInvokeConfigOptions { * These options control the retry policy when interacting with CloudWatch APIs. * * @default - Default AWS SDK retry options. - * + * * @deprecated instead use `logGroup` to create a fully customizable log group and instruct the Lambda function to send logs to it. */ readonly logRetentionRetryOptions?: LogRetentionRetryOptions; @@ -475,12 +475,12 @@ export interface FunctionOptions extends EventInvokeConfigOptions { /** * The log group the function sends logs to. - * + * * By default, Lambda functions send logs to an automatically created default log group named /aws/lambda/. * However you cannot change the properties of this auto-created log group using the AWS CDK, e.g. you cannot set a different log retention. - * + * * Use the `logGroup` property to create a fully customizable LogGroup ahead of time, and instruct the Lambda function to send logs to it. - * + * * @default `/aws/lambda/${this.functionName}` - default log group created by Lambda */ readonly logGroup?: logs.ILogGroup; From 4e427778b36bcb34061077d338668af5378ed787 Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Wed, 17 Jan 2024 12:18:45 +0000 Subject: [PATCH 4/4] fix readme example --- packages/aws-cdk-lib/aws-lambda/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/aws-cdk-lib/aws-lambda/README.md b/packages/aws-cdk-lib/aws-lambda/README.md index 850623b053b06..f04c725aebd6e 100644 --- a/packages/aws-cdk-lib/aws-lambda/README.md +++ b/packages/aws-cdk-lib/aws-lambda/README.md @@ -999,7 +999,7 @@ This way you can use the full features set supported by Amazon CloudWatch Logs. ```ts import { LogGroup } from 'aws-cdk-lib/aws-logs'; -const myLogGroup = new logs.LogGroup(stack, 'MyLogGroupWithLogGroupName', { +const myLogGroup = new LogGroup(this, 'MyLogGroupWithLogGroupName', { logGroupName: 'customLogGroup', });