feat(lambda): deprecate logRetention properties in favor of logGroup

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/<function-name>` upon first execution with
+By default, Lambda functions automatically create a log group with the name `/aws/lambda/<function-name>` 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
 

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/<function name>.
+   * 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;
 }