Skip to content

docs: minor improvements and fixes #1022

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 6 commits into from
Jul 19, 2022
Merged

docs: minor improvements and fixes #1022

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
80d9265
docs: fix formatting issues in readme
saragerion Jul 19, 2022
51b4e26
docs: formatting fixes and improvements
saragerion Jul 19, 2022
69abac5
docs: metrics image caption fix
saragerion Jul 19, 2022
0a73958
docs: readme/index bottom sections fixes
saragerion Jul 19, 2022
5a0078d
docs: changed order credits
saragerion Jul 19, 2022
fd48996
docs: added CI/CD pip requirments + alt for images
saragerion Jul 19, 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
8 changes: 5 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# AWS Lambda Powertools for TypeScript

A suite of utilities for AWS Lambda functions to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.
A suite of utilities for AWS Lambda functions to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.

You can use the library in both TypeScript and JavaScript code bases.
AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).

AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available.

**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)**

Expand Down Expand Up @@ -65,7 +67,7 @@ If you are interested in contributing to this project, please refer to our [Cont
## Roadmap

The roadmap of Powertools is driven by customers’ demand.
Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/awslabs/aws-lambda-powertools-typescript/issues), or [creating new ones[(https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new/choose), in this GitHub repository.
Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/awslabs/aws-lambda-powertools-typescript/issues), or [creating new ones](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new/choose), in this GitHub repository.

## Connect

Expand Down
2 changes: 1 addition & 1 deletion docs/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
FROM squidfunk/mkdocs-material
RUN pip install mkdocs-git-revision-date-plugin
RUN pip install mkdocs-git-revision-date-plugin mkdocs-glightbox
Copy link
Contributor

Choose a reason for hiding this comment

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

What about doing RUN pip install -r requirements.txt and add the dependencies there?

During the documentation build & publish process we actually read that file, so adding it only here means we'll have the new dependency only during development.

If we centralize everything in the requirements.txt file we can pin the version as well as avoiding this kind of oversight again.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I agree with you!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

So we install utilities in 2 ways:

  • Local env: via docker, and the squidfunk/mkdocs-material image already contains some dependencies
  • Github Actions: via pip commands, installing dependencies one by one in the containers of the CI/CD pipeline

So in this case it would not make sense to reuse the same requirements.txt file as some of them would be redundant.

70 changes: 38 additions & 32 deletions docs/core/logger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,13 @@ Logger provides an opinionated logger with output structured as JSON.
* Appending additional keys to structured logs at any point in time.
* Providing a custom log formatter (Bring Your Own Formatter) to output logs in a structure compatible with your organization’s Logging RFC.

<br />

<figure>
<img src="../../media/logger_utility_showcase.png" loading="lazy" />
Copy link
Contributor

Choose a reason for hiding this comment

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

Can we also add a alt attribute to each image?

The alt attribute holds a text description of the image, which isn't mandatory but is incredibly useful for accessibility — screen readers read this description out to their users so they know what the image means. Alt text is also displayed on the page if the image can't be loaded for some reason: for example, network errors, content blocking, or linkrot.

source

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes! Absolutely. Well spotted.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Let me know if they look good enough!

<figcaption>Logger showcase - Log attributes</figcaption>
</figure>

## Getting started

### Installation
Expand All @@ -25,7 +32,7 @@ npm install @aws-lambda-powertools/logger

### Usage

The `Logger` utility must always be instantiated outside of the Lambda handler. In doing this, subsequent invocations processed by the same instance of your function can reuse these resources. This saves cost by reducing function run time. In addition, `Logger` can keep track of a cold start and inject the appropriate fields into logs.
The `Logger` utility must always be instantiated outside the Lambda handler. By doing this, subsequent invocations processed by the same instance of your function can reuse these resources. This saves cost by reducing function run time. In addition, `Logger` can keep track of a cold start and inject the appropriate fields into logs.

=== "handler.ts"

Expand All @@ -45,10 +52,10 @@ The library requires two settings. You can set them as environment variables, or

These settings will be used across all logs emitted:

Setting | Description | Environment variable | Constructor parameter
------------------------------------------------- |------------------------------------------------------------------------------------------------------------------| ------------------------------------------------- | -------------------------------------------------
**Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel`
**Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName`
| Setting | Description | Environment variable | Constructor parameter |
|-------------------|------------------------------------------------------------------------------------------------------------------|---------------------------|-----------------------|
| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel` |
| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `serviceName` |

For a **complete list** of supported environment variables, refer to [this section](./../index.md#environment-variables).

Expand Down Expand Up @@ -87,15 +94,15 @@ For a **complete list** of supported environment variables, refer to [this secti

Your Logger will include the following keys to your structured logging (default log formatter):

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` | `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` | X-Ray Trace ID. This value is always presented in Lambda environment, whether [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"} or not. Logger will always log this value.
**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
| 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` | `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` | X-Ray Trace ID. This value is always presented in Lambda environment, whether [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"} or not. Logger will always log this value. |
| **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 |

### Capturing Lambda context info

Expand All @@ -111,27 +118,11 @@ Key | Example
**function_arn**: `string` | `arn:aws:lambda:eu-west-1:123456789012:function:shopping-cart-api-lambda-prod-eu-west-1`
**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`

=== "Manual"

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

const logger = new Logger();

export const handler = async (_event, context): Promise<void> => {

logger.addContext(context);

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

};
```

=== "Middy Middleware"

!!! tip "Using Middy for the first time?"
You can install Middy by running `npm i @middy/core`.
Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.

```typescript hl_lines="1-2 10-11"
import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
Expand Down Expand Up @@ -167,6 +158,21 @@ Key | Example
export const myFunction = new Lambda();
export const handler = myFunction.handler;
```
=== "Manual"

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

const logger = new Logger();

export const handler = async (_event, context): Promise<void> => {

logger.addContext(context);

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

};
```

In each case, the printed log will look like this:

Expand All @@ -189,7 +195,7 @@ In each case, the printed log will look like this:

#### Log incoming event

When debugging in non-production environments, you can instruct Logger to log the incoming event with the middleware/decorator parameter `logEvent` or via POWERTOOLS_LOGGER_LOG_EVENT env var set to `true`.
When debugging in non-production environments, you can instruct Logger to log the incoming event with the middleware/decorator parameter `logEvent` or via `POWERTOOLS_LOGGER_LOG_EVENT` env var set to `true`.

???+ warning
This is disabled by default to prevent sensitive info being logged
Expand Down
Loading