Skip to content

Commit a08bf76

Browse files
dreamorosiflochazsaragerionijemmy
authored
docs(all): make docs more coherent (#387)
* chore(test): test * docs(metrics): remove serializeMetrics and fix cloudwatch excerpt * fix: tracer construct initializer * Conformed tracer & logger * Added changes from #376 * Added lambdaInterface to logger examples * docs: update docs/core/logger.md Co-authored-by: Sara Gerion <[email protected]> * docs: updated return type for all async handlers * docs: update docs/core/metrics.md Co-authored-by: Sara Gerion <[email protected]> * docs: update docs/core/metrics.md Co-authored-by: Sara Gerion <[email protected]> * docs: update docs/core/metrics.md Co-authored-by: Sara Gerion <[email protected]> * docs: updated all references to publishStoredMetrics * docs: replaced extends w/ implements keyword in classes * docs: switched to serviceName according to #401 * docs: switched to serviceName according to #401 * docs: update docs/core/tracer.md Co-authored-by: Florian Chazal <[email protected]> * docs: update docs/core/metrics.md Co-authored-by: Florian Chazal <[email protected]> * docs: update docs/core/tracer.md Co-authored-by: Florian Chazal <[email protected]> * docs: update docs/core/logger.md Co-authored-by: Florian Chazal <[email protected]> * docs: update note on patching all modules * docs: updated text in captureMethod section * docs: update docs/core/metrics.md Co-authored-by: ijemmy <[email protected]> * docs: update docs/core/metrics.md Co-authored-by: ijemmy <[email protected]> * docs: updated other references to serverlessAirline Co-authored-by: Florian CHAZAL <[email protected]> Co-authored-by: Sara Gerion <[email protected]> Co-authored-by: ijemmy <[email protected]>
1 parent a498779 commit a08bf76

File tree

3 files changed

+384
-329
lines changed

3 files changed

+384
-329
lines changed

Diff for: ‎docs/core/logger.md

+63-57
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ For a **complete list** of supported environment variables, refer to [this secti
5959
// You can also pass the parameters in the constructor
6060
// const logger = new Logger({
6161
// logLevel: "WARN",
62-
// serviceName: "shopping-cart-api"
62+
// serviceName: "serverlessAirline"
6363
// });
6464
```
6565

@@ -74,7 +74,7 @@ For a **complete list** of supported environment variables, refer to [this secti
7474
Environment:
7575
Variables:
7676
LOG_LEVEL: WARN
77-
POWERTOOLS_SERVICE_NAME: shopping-cart-api
77+
POWERTOOLS_SERVICE_NAME: serverlessAirline
7878
```
7979

8080
### Standard structured keys
@@ -86,7 +86,7 @@ Key | Example | Note
8686
**level**: `string` | `INFO` | Logging level set for the Lambda function"s invocation
8787
**message**: `string` | `Query performed to DynamoDB` | A descriptive, human-readable representation of this log item
8888
**sampling_rate**: `float` | `0.1` | When enabled, it prints all the logs of a percentage of invocations, e.g. 10%
89-
**service**: `string` | `shopping-cart-api` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`
89+
**service**: `string` | `serverlessAirline` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`
9090
**timestamp**: `string` | `2011-10-05T14:48:00.000Z` | Timestamp string in simplified extended ISO format (ISO 8601)
9191
**xray_trace_id**: `string` | `1-5759e988-bd862e3fe1be46a994272793` | When [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"}, it shows X-Ray Trace ID
9292
**error**: `Object` | `{ name: "Error", location: "/my-project/handler.ts:18", message: "Unexpected error #1", stack: "[stacktrace]"}` | Optional - An object containing information about the Error passed to the logger
@@ -105,7 +105,23 @@ Key | Example
105105
**function_arn**: `string` | `arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1`
106106
**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
107107

108-
=== "Middleware"
108+
=== "Manual"
109+
110+
```typescript hl_lines="7"
111+
import { Logger } from "@aws-lambda-powertools/logger";
112+
113+
const logger = new Logger();
114+
115+
export const handler = async (_event, context) => {
116+
117+
logger.addContext(context);
118+
119+
logger.info("This is an INFO log with some context");
120+
121+
};
122+
```
123+
124+
=== "Middy Middleware"
109125

110126
!!! note
111127
Middy comes bundled with Logger, so you can just import it when using the middleware.
@@ -119,45 +135,33 @@ Key | Example
119135

120136
const logger = new Logger();
121137

122-
const lambdaHandler = async () => {
138+
const lambdaHandler = async (_event: any, _context: any) => {
123139
logger.info("This is an INFO log with some context");
124140
};
125141

126-
const handler = middy(lambdaHandler)
142+
export const handler = middy(lambdaHandler)
127143
.use(injectLambdaContext(logger));
128144
```
129145

130-
=== "Manual"
131-
132-
```typescript hl_lines="7"
133-
import { Logger } from "@aws-lambda-powertools/logger";
134-
135-
const logger = new Logger();
136-
137-
const lambdaHandler = async (_event, context) => {
138-
139-
logger.addContext(context);
140-
141-
logger.info("This is an INFO log with some context");
142-
143-
};
144-
```
145-
146146
=== "Decorator"
147147

148-
```typescript hl_lines="7"
148+
```typescript hl_lines="8"
149149
import { Logger } from "@aws-lambda-powertools/logger";
150+
import { LambdaInterface } from '@aws-lambda-powertools/commons';
150151

151152
const logger = new Logger();
152153

153-
class Lambda {
154-
154+
class Lambda implements LambdaInterface {
155+
// Decorate your handler class method
155156
@logger.injectLambdaContext()
156-
public handler() {
157+
public async handler(_event: any, _context: any): Promise<void> {
157158
logger.info("This is an INFO log with some context");
158159
}
159160

160161
}
162+
163+
export const myFunction = new Lambda();
164+
export const handler = myFunction.handler;
161165
```
162166

163167
In each case, the printed log will look like this:
@@ -173,7 +177,7 @@ In each case, the printed log will look like this:
173177
"function_name": "shopping-cart-api-lambda-prod-eu-central-1",
174178
"level": "INFO",
175179
"message": "This is an INFO log with some context",
176-
"service": "shopping-cart-api",
180+
"service": "serverlessAirline",
177181
"timestamp": "2021-12-12T21:21:08.921Z",
178182
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
179183
}
@@ -213,7 +217,7 @@ You can append additional persistent keys and values in the logs generated durin
213217
// }
214218
// });
215219

216-
const lambdaHandler: Handler = async () => {
220+
export const handler = async (_event: any, _context: any) => {
217221

218222
// This info log will print all extra custom attributes added above
219223
// Extra attributes: logger object with name and version of the logger library, awsAccountId, awsRegion
@@ -232,7 +236,7 @@ You can append additional persistent keys and values in the logs generated durin
232236
{
233237
"level": "INFO",
234238
"message": "This is an INFO log",
235-
"service": "shopping-cart-api",
239+
"service": "serverlessAirline",
236240
"timestamp": "2021-12-12T21:49:58.084Z",
237241
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
238242
"aws_account_id": "123456789012",
@@ -245,7 +249,7 @@ You can append additional persistent keys and values in the logs generated durin
245249
{
246250
"level": "INFO",
247251
"message": "This is another INFO log",
248-
"service": "shopping-cart-api",
252+
"service": "serverlessAirline",
249253
"timestamp": "2021-12-12T21:49:58.088Z",
250254
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
251255
"aws_account_id": "123456789012",
@@ -271,7 +275,7 @@ You can append additional keys and values in a single log item passing them as p
271275

272276
const logger = new Logger();
273277

274-
const lambdaHandler = async () => {
278+
export const handler = async (_event: any, _context: any) => {
275279

276280
const myImportantVariable = {
277281
foo: "bar"
@@ -300,15 +304,15 @@ You can append additional keys and values in a single log item passing them as p
300304
{
301305
"level": "INFO",
302306
"message": "This is a log with an extra variable",
303-
"service": "shopping-cart-api",
307+
"service": "serverlessAirline",
304308
"timestamp": "2021-12-12T22:06:17.463Z",
305309
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
306310
"data": { foo: "bar" }
307311
}
308312
{
309313
"level": "INFO",
310314
"message": "This is a log with 2 extra variables",
311-
"service": "shopping-cart-api",
315+
"service": "serverlessAirline",
312316
"timestamp": "2021-12-12T22:06:17.466Z",
313317
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
314318
"data": { "foo": "bar" },
@@ -328,7 +332,7 @@ The error will be logged with default key name `error`, but you can also pass yo
328332

329333
const logger = new Logger();
330334

331-
const lambdaHandler = async () => {
335+
export const handler = async (_event: any, _context: any) => {
332336

333337
try {
334338
throw new Error("Unexpected error #1");
@@ -353,7 +357,7 @@ The error will be logged with default key name `error`, but you can also pass yo
353357
{
354358
"level": "ERROR",
355359
"message": "This is an ERROR log #1",
356-
"service": "shopping-cart-api",
360+
"service": "serverlessAirline",
357361
"timestamp": "2021-12-12T22:12:39.345Z",
358362
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
359363
"error": {
@@ -366,7 +370,7 @@ The error will be logged with default key name `error`, but you can also pass yo
366370
{
367371
"level": "ERROR",
368372
"message": "This is an ERROR log #2",
369-
"service": "shopping-cart-api",
373+
"service": "serverlessAirline",
370374
"timestamp": "2021-12-12T22:12:39.377Z",
371375
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
372376
"myCustomErrorKey": {
@@ -400,7 +404,7 @@ This can be useful for example if you want to enable multiple Loggers with diffe
400404
logLevel: "ERROR"
401405
});
402406

403-
const lambdaHandler: Handler = async () => {
407+
export const handler = async (_event: any, _context: any) => {
404408

405409
logger.info("This is an INFO log, from the parent logger");
406410
logger.error("This is an ERROR log, from the parent logger");
@@ -417,21 +421,21 @@ This can be useful for example if you want to enable multiple Loggers with diffe
417421
{
418422
"level": "INFO",
419423
"message": "This is an INFO log, from the parent logger",
420-
"service": "shopping-cart-api",
424+
"service": "serverlessAirline",
421425
"timestamp": "2021-12-12T22:32:54.667Z",
422426
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
423427
}
424428
{
425429
"level": "ERROR",
426430
"message": "This is an ERROR log, from the parent logger",
427-
"service": "shopping-cart-api",
431+
"service": "serverlessAirline",
428432
"timestamp": "2021-12-12T22:32:54.670Z",
429433
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
430434
}
431435
{
432436
"level": "ERROR",
433437
"message": "This is an ERROR log, from the child logger",
434-
"service": "shopping-cart-api",
438+
"service": "serverlessAirline",
435439
"timestamp": "2021-12-12T22:32:54.670Z",
436440
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
437441
}
@@ -465,7 +469,7 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
465469
sampleRateValue: 0.5
466470
});
467471

468-
const lambdaHandler = async () => {
472+
export const handler = async (_event: any, _context: any) => {
469473

470474
// This log item (equal to log level 'ERROR') will be printed to standard output
471475
// in all Lambda invocations
@@ -490,31 +494,31 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
490494
"level": "ERROR",
491495
"message": "This is an ERROR log",
492496
"sampling_rate": "0.5",
493-
"service": "shopping-cart-api",
497+
"service": "serverlessAirline",
494498
"timestamp": "2021-12-12T22:59:06.334Z",
495499
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
496500
}
497501
{
498502
"level": "DEBUG",
499503
"message": "This is a DEBUG log that has 50% chance of being printed",
500504
"sampling_rate": "0.5",
501-
"service": "shopping-cart-api",
505+
"service": "serverlessAirline",
502506
"timestamp": "2021-12-12T22:59:06.337Z",
503507
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
504508
}
505509
{
506510
"level": "INFO",
507511
"message": "This is an INFO log that has 50% chance of being printed",
508512
"sampling_rate": "0.5",
509-
"service": "shopping-cart-api",
513+
"service": "serverlessAirline",
510514
"timestamp": "2021-12-12T22:59:06.338Z",
511515
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
512516
}
513517
{
514518
"level": "WARN",
515519
"message": "This is a WARN log that has 50% chance of being printed",
516520
"sampling_rate": "0.5",
517-
"service": "shopping-cart-api",
521+
"service": "serverlessAirline",
518522
"timestamp": "2021-12-12T22:59:06.338Z",
519523
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
520524
}
@@ -527,7 +531,7 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
527531
"level": "ERROR",
528532
"message": "This is an ERROR log",
529533
"sampling_rate": "0.5",
530-
"service": "shopping-cart-api",
534+
"service": "serverlessAirline",
531535
"timestamp": "2021-12-12T22:59:06.334Z",
532536
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
533537
}
@@ -540,31 +544,31 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
540544
"level": "ERROR",
541545
"message": "This is an ERROR log",
542546
"sampling_rate": "0.5",
543-
"service": "shopping-cart-api",
547+
"service": "serverlessAirline",
544548
"timestamp": "2021-12-12T22:59:06.334Z",
545549
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
546550
}
547551
{
548552
"level": "DEBUG",
549553
"message": "This is a DEBUG log that has 50% chance of being printed",
550554
"sampling_rate": "0.5",
551-
"service": "shopping-cart-api",
555+
"service": "serverlessAirline",
552556
"timestamp": "2021-12-12T22:59:06.337Z",
553557
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
554558
}
555559
{
556560
"level": "INFO",
557561
"message": "This is an INFO log that has 50% chance of being printed",
558562
"sampling_rate": "0.5",
559-
"service": "shopping-cart-api",
563+
"service": "serverlessAirline",
560564
"timestamp": "2021-12-12T22:59:06.338Z",
561565
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
562566
}
563567
{
564568
"level": "WARN",
565569
"message": "This is a WARN log that has 50% chance of being printed",
566570
"sampling_rate": "0.5",
567-
"service": "shopping-cart-api",
571+
"service": "serverlessAirline",
568572
"timestamp": "2021-12-12T22:59:06.338Z",
569573
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
570574
}
@@ -577,15 +581,15 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
577581
"level": "ERROR",
578582
"message": "This is an ERROR log",
579583
"sampling_rate": "0.5",
580-
"service": "shopping-cart-api",
584+
"service": "serverlessAirline",
581585
"timestamp": "2021-12-12T22:59:06.334Z",
582586
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
583587
}
584588
```
585589

586590
### Custom Log formatter (Bring Your Own Formatter)
587591

588-
You can customize the structure (keys and values) of your log items by passing a custom log formatter, an object that extends the `LogFormatter` abstract class.
592+
You can customize the structure (keys and values) of your log items by passing a custom log formatter, an object that implements the `LogFormatter` abstract class.
589593

590594
=== "handler.ts"
591595

@@ -596,7 +600,7 @@ You can customize the structure (keys and values) of your log items by passing a
596600
const logger = new Logger({
597601
logFormatter: new MyCompanyLogFormatter(),
598602
logLevel: "DEBUG",
599-
serviceName: "shopping-cart-api",
603+
serviceName: "serverlessAirline",
600604
sampleRateValue: 0.5,
601605
persistentLogAttributes: {
602606
awsAccountId: process.env.AWS_ACCOUNT_ID,
@@ -607,10 +611,12 @@ You can customize the structure (keys and values) of your log items by passing a
607611
},
608612
});
609613

610-
const lambdaHandler: Handler = async (event, context) => {
614+
export const handler = async (event, _context) => {
615+
611616
logger.addContext(context);
612617
613618
logger.info("This is an INFO log", { correlationIds: { myCustomCorrelationId: "foo-bar-baz" } });
619+
614620
};
615621
```
616622

@@ -625,7 +631,7 @@ This is how the `MyCompanyLogFormatter` (dummy name) would look like:
625631
// Replace this line with your own type
626632
type MyCompanyLog = LogAttributes;
627633

628-
class MyCompanyLogFormatter extends LogFormatter {
634+
class MyCompanyLogFormatter implements LogFormatter {
629635

630636
public formatAttributes(attributes: UnformattedAttributes): MyCompanyLog {
631637
return {
@@ -666,7 +672,7 @@ This is how the printed log would look:
666672
```json
667673
{
668674
"message": "This is an INFO log",
669-
"service": "shopping-cart-api",
675+
"service": "serverlessAirline",
670676
"awsRegion": "eu-central-1",
671677
"correlationIds": {
672678
"awsRequestId": "c6af9ac6-7b61-11e6-9a41-93e812345678",
@@ -722,7 +728,7 @@ describe('MyUnitTest', () => {
722728

723729
test('Lambda invoked successfully', async () => {
724730

725-
const testEvent = { test: 'test' };
731+
const testEvent = { test: 'test' };
726732
await handler(testEvent, dummyContext);
727733

728734
});

0 commit comments

Comments
 (0)