Skip to content

Commit de38d4a

Browse files
am29ddreamorosi
am29d
and
dreamorosi
authored
docs(logger): review API docs & README for Logger (#2984)
Co-authored-by: Andrea Amorosi <[email protected]>
1 parent 0e5422a commit de38d4a

11 files changed

+399
-244
lines changed

‎packages/logger/README.md

+189-45
Original file line numberDiff line numberDiff line change
@@ -4,79 +4,219 @@ Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serve
44

55
You can use the library in both TypeScript and JavaScript code bases.
66

7-
> Also available in [Python](https://github.com/aws-powertools/powertools-lambda-python), [Java](https://github.com/aws-powertools/powertools-lambda-java), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet).
8-
9-
**[Documentation](https://docs.powertools.aws.dev/lambda/typescript/)** | **[npm](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://docs.powertools.aws.dev/lambda/typescript/latest/roadmap)** | **[Examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)**
10-
11-
## Table of contents <!-- omit in toc -->
12-
13-
- [Features](#features)
14-
- [Getting started](#getting-started)
15-
- [Installation](#installation)
16-
- [Examples](#examples)
17-
- [Demo applications](#demo-applications)
7+
- [Intro](#intro)
8+
- [Usage](#usage)
9+
- [Basic usage](#basic-usage)
10+
- [Inject Lambda context](#inject-lambda-context)
11+
- [Logging incoming event](#logging-incoming-event)
12+
- [Append additional keys and data](#append-additional-keys-and-data)
1813
- [Contribute](#contribute)
1914
- [Roadmap](#roadmap)
2015
- [Connect](#connect)
2116
- [How to support Powertools for AWS Lambda (TypeScript)?](#how-to-support-powertools-for-aws-lambda-typescript)
2217
- [Becoming a reference customer](#becoming-a-reference-customer)
2318
- [Sharing your work](#sharing-your-work)
2419
- [Using Lambda Layer](#using-lambda-layer)
25-
- [Credits](#credits)
2620
- [License](#license)
2721

28-
## Features
22+
## Intro
2923

30-
- **[Tracer](https://docs.powertools.aws.dev/lambda/typescript/latest/core/tracer/)** - Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
31-
- **[Logger](https://docs.powertools.aws.dev/lambda/typescript/latest/core/logger/)** - Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context
32-
- **[Metrics](https://docs.powertools.aws.dev/lambda/typescript/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
33-
- **[Parameters](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/)** - High-level functions to retrieve one or more parameters from AWS SSM, Secrets Manager, AppConfig, and DynamoDB
24+
The Logger utility provides a structured logging experience with additional features tailored for AWS Lambda functions.
3425

35-
## Getting started
26+
## Usage
3627

37-
Find the complete project's [documentation here](https://docs.powertools.aws.dev/lambda/typescript).
28+
To get started, install the library by running:
29+
30+
```sh
31+
npm i @aws-lambda-powertools/logger
32+
```
3833

39-
### Installation
34+
### Basic usage
4035

41-
The Powertools for AWS Lambda (TypeScript) utilities follow a modular approach, similar to the official [AWS SDK v3 for JavaScript](https://github.com/aws/aws-sdk-js-v3).
36+
Initialize the logger with a service name and log messages:
4237

43-
Each TypeScript utility is installed as standalone npm package.
38+
```ts
39+
import { Logger } from '@aws-lambda-powertools/logger';
4440

45-
Install all three core utilities at once with this single command:
41+
const logger = new Logger({ serviceName: 'serverlessAirline' });
4642

47-
```shell
48-
npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
43+
export const handler = async (_event, _context): Promise<void> => {
44+
logger.info('Hello World');
45+
46+
};
4947
```
5048

51-
Or refer to the installation guide of each utility:
49+
You can also log errors and additional data:
50+
51+
```ts
52+
import { Logger } from '@aws-lambda-powertools/logger';
53+
54+
const logger = new Logger();
55+
56+
export const handler = async (
57+
_event: unknown,
58+
_context: unknown
59+
): Promise<void> => {
60+
try {
61+
throw new Error('Unexpected error #1');
62+
} catch (error) {
63+
// Log information about the error using the default "error" key
64+
logger.error('This is the first error', error as Error);
65+
}
66+
67+
try {
68+
throw new Error('Unexpected error #2');
69+
} catch (error) {
70+
// Log information about the error using a custom "myCustomErrorKey" key
71+
logger.error('This is the second error', {
72+
myCustomErrorKey: error as Error,
73+
});
74+
}
75+
};
76+
```
77+
78+
### Inject Lambda context
5279

53-
👉 [Installation guide for the **Tracer** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/core/tracer#getting-started)
80+
You can enrich your structured logs with key Lambda context information:
5481

55-
👉 [Installation guide for the **Logger** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/core/logger#getting-started)
82+
```ts
83+
import { Logger } from '@aws-lambda-powertools/logger';
84+
import type { Context } from 'aws-lambda';
5685

57-
👉 [Installation guide for the **Metrics** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/core/metrics#getting-started)
86+
const logger = new Logger();
5887

59-
👉 [Installation guide for the **Parameters** utility](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/#getting-started)
88+
export const handler = async (
89+
_event: unknown,
90+
context: Context
91+
): Promise<void> => {
92+
logger.addContext(context);
93+
94+
logger.info('This is an INFO log with some context');
95+
};
96+
```
6097

61-
### Examples
98+
The log statement will look like this:
99+
100+
```json
101+
{
102+
"cold_start": true,
103+
"function_arn": "arn:aws:lambda:eu-west-1:123456789012:function:shopping-cart-api-lambda-prod-eu-west-1",
104+
"function_memory_size": 128,
105+
"function_request_id": "c6af9ac6-7b61-11e6-9a41-93e812345678",
106+
"function_name": "shopping-cart-api-lambda-prod-eu-west-1",
107+
"level": "INFO",
108+
"message": "This is an INFO log with some context",
109+
"service": "serverlessAirline",
110+
"timestamp": "2021-12-12T21:21:08.921Z",
111+
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
112+
}
113+
```
114+
115+
### Logging incoming event
116+
117+
You can log the incoming event with (here as decorator, works also as middy middleware):
118+
119+
```ts
120+
import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
121+
import { Logger } from '@aws-lambda-powertools/logger';
122+
123+
const logger = new Logger();
124+
125+
class Lambda implements LambdaInterface {
126+
// Set the log event flag to true
127+
@logger.injectLambdaContext({ logEvent: true })
128+
public async handler(_event: unknown, _context: unknown): Promise<void> {
129+
logger.info('This is an INFO log with some context');
130+
}
131+
}
132+
133+
const myFunction = new Lambda();
134+
export const handler = myFunction.handler.bind(myFunction); //
135+
```
62136

63-
You can find examples of how to use Powertools for AWS Lambda (TypeScript) in the [examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/app) directory. The application is a simple REST API that can be deployed via either AWS CDK or AWS SAM.
137+
### Append additional keys and data
64138

65-
### Demo applications
139+
Append additional keys:
66140

67-
The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Powertools for AWS Lambda (TypeScript).
68-
You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo).
141+
```ts
142+
import { Logger } from '@aws-lambda-powertools/logger';
69143

70-
The [AWS Lambda performance tuning](https://github.com/aws-samples/optimizations-for-lambda-functions) repository also uses Powertools for AWS Lambda (TypeScript) as well as demonstrating other performance tuning techniques for Lambda functions written in TypeScript.
144+
const logger = new Logger();
145+
146+
export const handler = async (
147+
event: unknown,
148+
_context: unknown
149+
): Promise<unknown> => {
150+
const myImportantVariable = {
151+
foo: 'bar',
152+
};
153+
154+
// Log additional data in single log items
155+
// As second parameter
156+
logger.info('This is a log with an extra variable', {
157+
data: myImportantVariable,
158+
});
159+
160+
// You can also pass multiple parameters containing arbitrary objects
161+
logger.info(
162+
'This is a log with 3 extra objects',
163+
{ data: myImportantVariable },
164+
{ correlationIds: { myCustomCorrelationId: 'foo-bar-baz' } },
165+
{ lambdaEvent: event }
166+
);
167+
168+
// Simply pass a string for logging additional data
169+
logger.info('This is a log with additional string value', 'string value');
170+
171+
// Directly passing an object containing both the message and the additional info
172+
const logObject = {
173+
message: 'This is a log message',
174+
additionalValue: 42,
175+
};
176+
177+
logger.info(logObject);
178+
179+
return {
180+
foo: 'bar',
181+
};
182+
};
183+
```
184+
185+
Add **persistent keys** to the logger instance:
186+
187+
```ts
188+
import { Logger } from '@aws-lambda-powertools/logger';
189+
190+
const logger = new Logger({
191+
serviceName: 'serverlessAirline',
192+
persistentKeys: {
193+
environment: 'prod',
194+
version: process.env.BUILD_VERSION,
195+
},
196+
});
197+
198+
export const handler = async (
199+
_event: unknown,
200+
_context: unknown
201+
): Promise<void> => {
202+
logger.info('processing transaction');
203+
204+
// ... your business logic
205+
};
206+
```
71207

72208
## Contribute
73209

74-
If you are interested in contributing to this project, please refer to our [Contributing Guidelines](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md).
210+
If you are interested in contributing to this project, please refer to
211+
our [Contributing Guidelines](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md).
75212

76213
## Roadmap
77214

78215
The roadmap of Powertools for AWS Lambda (TypeScript) is driven by customers’ demand.
79-
Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/aws-powertools/powertools-lambda-typescript/issues), or [creating new ones](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), in this GitHub repository.
216+
Help us prioritize upcoming functionalities or utilities
217+
by [upvoting existing RFCs and feature requests](https://github.com/aws-powertools/powertools-lambda-typescript/issues),
218+
or [creating new ones](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), in this GitHub
219+
repository.
80220

81221
## Connect
82222

@@ -87,7 +227,10 @@ Help us prioritize upcoming functionalities or utilities by [upvoting existing R
87227

88228
### Becoming a reference customer
89229

90-
Knowing which companies are using this library is important to help prioritize the project internally. If your company is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by raising a [Support Lambda Powertools for AWS Lambda (TypeScript) (become a reference)](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=customer-reference&template=support_powertools.yml&title=%5BSupport+Lambda+Powertools%5D%3A+%3Cyour+organization+name%3E) issue.
230+
Knowing which companies are using this library is important to help prioritize the project internally. If your company
231+
is using Powertools for AWS Lambda (TypeScript), you can request to have your name and logo added to the README file by
232+
raising a [Support Powertools for AWS Lambda (TypeScript) (become a reference)](https://s12d.com/become-reference-pt-ts)
233+
issue.
91234

92235
The following companies, among others, use Powertools:
93236

@@ -109,15 +252,16 @@ The following companies, among others, use Powertools:
109252

110253
### Sharing your work
111254

112-
Share what you did with Powertools for AWS Lambda (TypeScript) 💞💞. Blog post, workshops, presentation, sample apps and others. Check out what the community has already shared about Powertools for AWS Lambda (TypeScript) [here](https://docs.powertools.aws.dev/lambda/typescript/latest/we_made_this).
255+
Share what you did with Powertools for AWS Lambda (TypeScript) 💞💞. Blog post, workshops, presentation, sample apps and
256+
others. Check out what the community has already shared about Powertools for AWS Lambda (
257+
TypeScript) [here](https://docs.powertools.aws.dev/lambda/typescript/latest/we_made_this).
113258

114259
### Using Lambda Layer
115260

116-
This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When [using Layers](#lambda-layers), you can add Powertools for AWS Lambda (TypeScript) as a dev dependency (or as part of your virtual env) to not impact the development process.
117-
118-
## Credits
119-
120-
Credits for the Powertools for AWS Lambda (TypeScript) idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
261+
This helps us understand who uses Powertools for AWS Lambda (TypeScript) in a non-intrusive way, and helps us gain
262+
future investments for other Powertools for AWS Lambda languages.
263+
When [using Layers](https://docs.powertools.aws.dev/lambda/typescript/latest/#lambda-layer), you can add Powertools as a
264+
dev dependency to not impact the development process.
121265

122266
## License
123267

0 commit comments

Comments
 (0)