Skip to content

docs(all): make docs more coherent #387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 27 commits into from
Jan 5, 2022
Merged

docs(all): make docs more coherent #387

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
1e17d07
chore(test): test
flochaz Dec 30, 2021
62d6c9e
docs(metrics): remove serializeMetrics and fix cloudwatch excerpt
flochaz Jan 3, 2022
b1bc7f9
fix: tracer construct initializer
dreamorosi Jan 3, 2022
c63fdd6
Conformed tracer & logger
dreamorosi Jan 3, 2022
80ae556
Merge branch 'docs/fixMetrics' of github.com:awslabs/aws-lambda-power…
dreamorosi Jan 4, 2022
a93e905
Added changes from #376
dreamorosi Jan 4, 2022
a0e8615
Fixed merge conflicts
dreamorosi Jan 4, 2022
8d7a93e
Added lambdaInterface to logger examples
dreamorosi Jan 4, 2022
479820f
docs: update docs/core/logger.md
dreamorosi Jan 4, 2022
6b473bd
docs: updated return type for all async handlers
dreamorosi Jan 4, 2022
1714eb6
docs: update docs/core/metrics.md
dreamorosi Jan 4, 2022
f07c545
docs: update docs/core/metrics.md
dreamorosi Jan 4, 2022
d0d0c29
docs: update docs/core/metrics.md
dreamorosi Jan 4, 2022
482b6d8
docs: updated all references to publishStoredMetrics
dreamorosi Jan 4, 2022
ac7587a
docs: replaced extends w/ implements keyword in classes
dreamorosi Jan 4, 2022
2539fbb
docs: switched to serviceName according to #401
dreamorosi Jan 4, 2022
6e06130
docs: switched to serviceName according to #401
dreamorosi Jan 4, 2022
a5dbd92
docs: update docs/core/tracer.md
dreamorosi Jan 5, 2022
faee189
docs: update docs/core/metrics.md
dreamorosi Jan 5, 2022
d05e421
docs: update docs/core/tracer.md
dreamorosi Jan 5, 2022
2145f90
docs: update docs/core/logger.md
dreamorosi Jan 5, 2022
bfe774a
docs: update note on patching all modules
dreamorosi Jan 5, 2022
fffc291
docs: updated text in captureMethod section
dreamorosi Jan 5, 2022
d982318
docs: update docs/core/metrics.md
dreamorosi Jan 5, 2022
7853925
docs: update docs/core/metrics.md
dreamorosi Jan 5, 2022
ce9e3d8
docs: updated other references to serverlessAirline
dreamorosi Jan 5, 2022
6b7a800
Merge branch 'docs/general_improv' of github.com:awslabs/aws-lambda-p…
dreamorosi Jan 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 63 additions & 57 deletions docs/core/logger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ For a **complete list** of supported environment variables, refer to [this secti
// You can also pass the parameters in the constructor
// const logger = new Logger({
// logLevel: "WARN",
// serviceName: "shopping-cart-api"
// serviceName: "serverlessAirline"
// });
```

Expand All @@ -74,7 +74,7 @@ For a **complete list** of supported environment variables, refer to [this secti
Environment:
Variables:
LOG_LEVEL: WARN
POWERTOOLS_SERVICE_NAME: shopping-cart-api
POWERTOOLS_SERVICE_NAME: serverlessAirline
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(minor) There are a few more "shopping-cart-api" left in the doc.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, I've missed those. I've now removed all of the ones in the serviceName but left the ones in the function name

```

### Standard structured keys
Expand All @@ -86,7 +86,7 @@ Key | Example | Note
**level**: `string` | `INFO` | Logging level set for the Lambda function"s invocation
**message**: `string` | `Query performed to DynamoDB` | A descriptive, human-readable representation of this log item
**sampling_rate**: `float` | `0.1` | When enabled, it prints all the logs of a percentage of invocations, e.g. 10%
**service**: `string` | `shopping-cart-api` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`
**service**: `string` | `serverlessAirline` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`
**timestamp**: `string` | `2011-10-05T14:48:00.000Z` | Timestamp string in simplified extended ISO format (ISO 8601)
**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
**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
Expand All @@ -105,7 +105,23 @@ Key | Example
**function_arn**: `string` | `arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1`
**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`

=== "Middleware"
=== "Manual"

```typescript hl_lines="7"
import { Logger } from "@aws-lambda-powertools/logger";

const logger = new Logger();

export const handler = async (_event, context) => {

logger.addContext(context);

logger.info("This is an INFO log with some context");

};
```

=== "Middy Middleware"

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

const logger = new Logger();

const lambdaHandler = async () => {
const lambdaHandler = async (_event: any, _context: any) => {
logger.info("This is an INFO log with some context");
};

const handler = middy(lambdaHandler)
export const handler = middy(lambdaHandler)
.use(injectLambdaContext(logger));
```

=== "Manual"

```typescript hl_lines="7"
import { Logger } from "@aws-lambda-powertools/logger";

const logger = new Logger();

const lambdaHandler = async (_event, context) => {

logger.addContext(context);

logger.info("This is an INFO log with some context");

};
```

=== "Decorator"

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

const logger = new Logger();

class Lambda {

class Lambda implements LambdaInterface {
// Decorate your handler class method
@logger.injectLambdaContext()
public handler() {
public async handler(_event: any, _context: any): Promise<void> {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch.

logger.info("This is an INFO log with some context");
}

}

export const myFunction = new Lambda();
export const handler = myFunction.handler;
```

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

const lambdaHandler: Handler = async () => {
export const handler = async (_event: any, _context: any) => {

// This info log will print all extra custom attributes added above
// Extra attributes: logger object with name and version of the logger library, awsAccountId, awsRegion
Expand All @@ -232,7 +236,7 @@ You can append additional persistent keys and values in the logs generated durin
{
"level": "INFO",
"message": "This is an INFO log",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T21:49:58.084Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
"aws_account_id": "123456789012",
Expand All @@ -245,7 +249,7 @@ You can append additional persistent keys and values in the logs generated durin
{
"level": "INFO",
"message": "This is another INFO log",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T21:49:58.088Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
"aws_account_id": "123456789012",
Expand All @@ -271,7 +275,7 @@ You can append additional keys and values in a single log item passing them as p

const logger = new Logger();

const lambdaHandler = async () => {
export const handler = async (_event: any, _context: any) => {

const myImportantVariable = {
foo: "bar"
Expand Down Expand Up @@ -300,15 +304,15 @@ You can append additional keys and values in a single log item passing them as p
{
"level": "INFO",
"message": "This is a log with an extra variable",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:06:17.463Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
"data": { foo: "bar" }
}
{
"level": "INFO",
"message": "This is a log with 2 extra variables",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:06:17.466Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
"data": { "foo": "bar" },
Expand All @@ -328,7 +332,7 @@ The error will be logged with default key name `error`, but you can also pass yo

const logger = new Logger();

const lambdaHandler = async () => {
export const handler = async (_event: any, _context: any) => {

try {
throw new Error("Unexpected error #1");
Expand All @@ -353,7 +357,7 @@ The error will be logged with default key name `error`, but you can also pass yo
{
"level": "ERROR",
"message": "This is an ERROR log #1",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:12:39.345Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
"error": {
Expand All @@ -366,7 +370,7 @@ The error will be logged with default key name `error`, but you can also pass yo
{
"level": "ERROR",
"message": "This is an ERROR log #2",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:12:39.377Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456",
"myCustomErrorKey": {
Expand Down Expand Up @@ -400,7 +404,7 @@ This can be useful for example if you want to enable multiple Loggers with diffe
logLevel: "ERROR"
});

const lambdaHandler: Handler = async () => {
export const handler = async (_event: any, _context: any) => {

logger.info("This is an INFO log, from the parent logger");
logger.error("This is an ERROR log, from the parent logger");
Expand All @@ -417,21 +421,21 @@ This can be useful for example if you want to enable multiple Loggers with diffe
{
"level": "INFO",
"message": "This is an INFO log, from the parent logger",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:32:54.667Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "ERROR",
"message": "This is an ERROR log, from the parent logger",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:32:54.670Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "ERROR",
"message": "This is an ERROR log, from the child logger",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:32:54.670Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
Expand Down Expand Up @@ -465,7 +469,7 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
sampleRateValue: 0.5
});

const lambdaHandler = async () => {
export const handler = async (_event: any, _context: any) => {

// This log item (equal to log level 'ERROR') will be printed to standard output
// in all Lambda invocations
Expand All @@ -490,31 +494,31 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
"level": "ERROR",
"message": "This is an ERROR log",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.334Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "DEBUG",
"message": "This is a DEBUG log that has 50% chance of being printed",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.337Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "INFO",
"message": "This is an INFO log that has 50% chance of being printed",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.338Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "WARN",
"message": "This is a WARN log that has 50% chance of being printed",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.338Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
Expand All @@ -527,7 +531,7 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
"level": "ERROR",
"message": "This is an ERROR log",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.334Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
Expand All @@ -540,31 +544,31 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
"level": "ERROR",
"message": "This is an ERROR log",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.334Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "DEBUG",
"message": "This is a DEBUG log that has 50% chance of being printed",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.337Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "INFO",
"message": "This is an INFO log that has 50% chance of being printed",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.338Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
{
"level": "WARN",
"message": "This is a WARN log that has 50% chance of being printed",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.338Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
Expand All @@ -577,15 +581,15 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i
"level": "ERROR",
"message": "This is an ERROR log",
"sampling_rate": "0.5",
"service": "shopping-cart-api",
"service": "serverlessAirline",
"timestamp": "2021-12-12T22:59:06.334Z",
"xray_trace_id": "abcdef123456abcdef123456abcdef123456"
}
```

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

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.
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.

=== "handler.ts"

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

const lambdaHandler: Handler = async (event, context) => {
export const handler = async (event, _context) => {

logger.addContext(context);

logger.info("This is an INFO log", { correlationIds: { myCustomCorrelationId: "foo-bar-baz" } });

};
```

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

class MyCompanyLogFormatter extends LogFormatter {
class MyCompanyLogFormatter implements LogFormatter {

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

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

const testEvent = { test: 'test' };
const testEvent = { test: 'test' };
await handler(testEvent, dummyContext);

});
Expand Down
Loading