diff --git a/packages/aws-cdk-lib/aws-lambda/README.md b/packages/aws-cdk-lib/aws-lambda/README.md index c3f02f90189cf..f04c725aebd6e 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 LogGroup(this, '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 diff --git a/packages/aws-cdk-lib/aws-lambda/lib/function.ts b/packages/aws-cdk-lib/aws-lambda/lib/function.ts index 54954dd5b6725..763085046c2fe 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; }