You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/upgrade.md
+299-2Lines changed: 299 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -3,5 +3,302 @@ title: Upgrade guide
3
3
description: Guide to update between major Powertools for AWS Lambda (TypeScript) versions
4
4
---
5
5
6
-
!!! warning
7
-
This guide is a work in progress. We'll update it as we get closer to the 2.0 release. If you have any questions, or want to follow the progress, please join the discussion on the [GitHub issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1714).
6
+
!!! note "We expect to release v2 by the end of February 2024."
7
+
8
+
## Migrate from v1 to v2
9
+
10
+
V2 is focused on official support for ESM (ECMAScript modules). We've made other minimal breaking changes to make your transition to v2 as smooth as possible.
In v2, we improved tree-shaking support to help you reduce your function bundle size. We would love to hear your feedback on further improvements we could make.
49
+
50
+
### Unable to use ESM?
51
+
52
+
!!! note "We recommend using ESM for the best experience _(top-level await, smaller bundle size etc.)_."
53
+
54
+
If you're unable to use ESM, you can still use the `require` syntax to import the package. We will continue to support it by shipping CommonJS modules alongside ESM.
55
+
56
+
You might still need the `require` syntax when using a dependency or a transitive dependency that doesn't support ESM. For example, Tracer _(`@aws-lambda-powertools/tracer`)_ relies on the AWS X-Ray SDK for Node.js which uses `require`.
57
+
58
+
When that happens, you can instruct your bundler to use the `require` syntax for specific dependencies while using ESM for everything else. This is commonly known as [polyfill](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill){target="_blank"}.
59
+
Here is an example using `esbuild` bundler.
60
+
61
+
=== "With AWS CDK"
62
+
63
+
```typescript hl_lines="15 20-21"
64
+
import { Stack, type StackProps } from 'aws-cdk-lib';
65
+
import { Construct } from 'constructs';
66
+
import { NodejsFunction, OutputFormat } from 'aws-cdk-lib/aws-lambda-nodejs';
67
+
import { Runtime } from 'aws-cdk-lib/aws-lambda';
68
+
69
+
export class MyStack extends Stack {
70
+
public constructor(scope: Construct, id: string, props?: StackProps) {
71
+
super(scope, id, props);
72
+
73
+
const handler = new NodejsFunction(this, 'helloWorldFunction', {
1. `esbuild` will include this arbitrary code at the top of your bundle to maximize CommonJS compatibility _(`require` keyword)_.
118
+
119
+
## Scoped imports
120
+
121
+
### Middy.js middleware imports
122
+
123
+
???+ note "Disregard if you are not using Middy.js middlewares."
124
+
In v2, we've added support for subpath exports. This means if you don't import Middy.js middlewares, you will benefit from a smaller bundle size.
125
+
126
+
In v1, you could import Middy.js middlewares from the default export of a package _(e.g., `logger`)_. For example, you'd import `injectLambdaContext` Logger middleware from `@aws-lambda-powertools/logger`.
127
+
128
+
In v2, you can now import only the Middy.js middlewares you want to use from a subpath export, _e.g., `@aws-lambda-powertools/logger/middleware`_, leading to a smaller bundle size.
129
+
130
+
=== "Before"
131
+
132
+
```typescript
133
+
import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
134
+
import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
135
+
import { Metrics, logMetrics } from '@aws-lambda-powertools/metrics';
136
+
```
137
+
138
+
=== "After"
139
+
140
+
```typescript hl_lines="2 5 8"
141
+
import { Logger } from '@aws-lambda-powertools/logger';
142
+
import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';
143
+
144
+
import { Tracer } from '@aws-lambda-powertools/tracer';
145
+
import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
146
+
147
+
import { Metrics } from '@aws-lambda-powertools/metrics';
148
+
import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
149
+
```
150
+
151
+
### Types imports
152
+
153
+
In v1, you could import package types from each package under `/lib`, for example `@aws-lambda-powertools/logger/lib/types`.
154
+
155
+
In v2, you can now directly import from the `types` subpath export, e.g., `@aws-lambda-powertools/logger/types`. This will optimize your bundle size, standardize types import across packages, future-proofing growth.
156
+
157
+
=== "Before"
158
+
159
+
```typescript
160
+
import { LogAttributes, UnformattedAttributes } from '@aws-lambda-powertools/logger/lib/types';
161
+
```
162
+
163
+
=== "After"
164
+
165
+
```typescript
166
+
import { LogAttributes, UnformattedAttributes } from '@aws-lambda-powertools/logger/types';
167
+
```
168
+
169
+
## Logger
170
+
171
+
### Log sampling
172
+
173
+
!!! note "Disregard if you are not using the [log sampling feature](./core/logger.md#sampling-logs)."
174
+
175
+
In v1, log sampling implementation was inconsistent from other Powertools for AWS Lambda languages _(Python, .NET, and Java)_.
176
+
177
+
In v2, we changed these behaviors for consistency across languages:
| Log Level | Log level remains unchanged but any log statement is printed | Log level changes to `DEBUG`|
182
+
| Log sampling indication | No indication | Debug message indicates sampling is in effect |
183
+
184
+
Logger `sampleRateValue`**continues** to determine the percentage of concurrent/cold start invocations that logs will be sampled, _e.g., log level set to `DEBUG`_.
185
+
186
+
### Custom log formatter
187
+
188
+
!!! note "Disregard if you are not customizing log output with a [custom log formatter](./core/logger.md#custom-log-formatter-bring-your-own-formatter)."
189
+
190
+
In v1, `Logger` exposed the [standard](./core/logger.md#standard-structured-keys) as a single argument, _e.g., `formatAttributes(attributes: UnformattedAttributes)`_. It expected a plain object with keys and values you wanted in the final log output.
191
+
192
+
In v2, you have more control over **standard** (`attributes`) and [**custom keys**](./core/logger.md#appending-persistent-additional-log-keys-and-values) (`additionalLogAttributes`) in the `formatAttributes` method. Also, you now return a `LogItem` object to increase type safety when defining the final log output.
193
+
194
+
=== "Before"
195
+
196
+
```typescript hl_lines="5 8"
197
+
import { LogFormatter } from '@aws-lambda-powertools/logger';
198
+
import {
199
+
LogAttributes,
200
+
UnformattedAttributes,
201
+
} from '@aws-lambda-powertools/logger/lib/types';
202
+
203
+
class MyCompanyLogFormatter extends LogFormatter {
204
+
public formatAttributes(attributes: UnformattedAttributes): LogAttributes {
1. This new argument contains all [your custom keys](./core/logger.md#appending-persistent-additional-log-keys-and-values).
281
+
2. `LogItem` is the new return object instead of a plain object.
282
+
3. If you prefer adding at the initialization, use: <br/><br/> **`LogItem({persistentAttributes: additionalLogAttributes, attributes: baseAttributes})`**
283
+
284
+
## Helper functions
285
+
286
+
We removed the deprecated `createLogger` and `createTracer` heper functions.
0 commit comments