logRetention: Deprecated or not?

[rowansc1]

Describe the bug

Hi All,

I have looked through various previous GitHub PRs and issues, and I'd like to confirm whether logRetention is going to be deprecated again, or if it is staying.

At the moment, we get:

[WARNING] aws-cdk-lib.aws_lambda.FunctionOptions#logRetention is deprecated.
use `logGroup` instead
This API will be removed in the next major release.

We can move to logGroup, but the reason why I'm asking is I've seen that it got reverted, so I'm just curious if its an old message which can be discarded.

Thanks for your help!

REF: #28783 #28737 #28934 #28783

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

Either this message to be accurate, or discarded.

Current Behavior

Included above

Reproduction Steps

Use logRetention in any capacity.

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.221.1

AWS CDK CLI version

N/A

Node.js Version

N/A

OS

N/A

Language

TypeScript

Language Version

No response

Other information

No response

[pahud]

Hi,

After checking the history. This is the timeline.

Phase 1: Initial Deprecation (2024)

• PRs feat(lambda): deprecate logRetention properties in favor of logGroup #28737 and feat(core): custom resources deprecate logRetention in favor of logGroup #28783 deprecated logRetention in favor of logGroup
• Added @deprecated JSDoc tags to the code

Phase 2: Complete Reversion (January 31, 2024)

• PR fix: revert deprecation of logRetention properties #28934 successfully reverted the deprecation
• Removed both documentation references AND the @deprecated JSDoc tags
• logRetention was no longer deprecated

Phase 3: Re-deprecation (June 25, 2025)

• PR feat(lambda): function log removal policy #34723 added logRemovalPolicy property
• Re-added @deprecated tags to logRetention, logRetentionRole, and logRetentionRetryOptions
• Reinforced deprecation guidance toward logGroup

So, YES logRetention is deprecated and the annotations are correct.

The situation:

• For standard AWS regions: Use logGroup (more features, better control)
• For some specific regions where logGroup not available: Must use logRetention (only option available)

Let me know if it clarifies.

[mrgrain]

We can move to logGroup, but the reason why I'm asking is I've seen that it got reverted, so I'm just curious if its an old message which can be discarded.

Definitely move to logGroup if you can. The old LogRetention implementation was a bad crutch that only really works for the most basic use cases.

[rowansc1]

Hi @pahud and @mrgrain,

Thank you very much for your detailed reply and help with this issue!

Are you able to confirm in what major version LogRetention will be removed?

We have quite a large codebase which uses it, so if it won't be getting removed, then it probably isn't worth switching as a priority, but if it's soon, then we will make it a priority.

It seems like the history of the deprecation of LogRetention is complex, so thank you very much for your clarifications.

In your previous message @pahud - you said that The logRetention property is fully supported and not being removed. The deprecation warning you're seeing should be a bug, which was deleted. I assume that this information is incorrect, and it will be getting removed?

Again, thank you for your help on this!

[pahud]

Hi @rowansc1

The deleted message was incorrect.

Please refer to my latest comment #36106 (comment) and let's make sure we use LogGroup.

LogRetention is deprecated now but generally won't be removed until next major release. Let's make sure we avoid that and start the migration plan as early as possible.

[rowansc1]

Thank you very much @pahud - I will ensure we switch over to LogGroup :)

Thanks for all your help!