Skip to content

Commit 8f45be8

Browse files
saragerionsaragerion
authored
docs: minor improvements and fixes (#1022)
* docs: fix formatting issues in readme * docs: formatting fixes and improvements * docs: metrics image caption fix * docs: readme/index bottom sections fixes * docs: changed order credits * docs: added CI/CD pip requirments + alt for images
1 parent 58bfcdf commit 8f45be8

15 files changed

+212
-156
lines changed

Diff for: ‎README.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# AWS Lambda Powertools for TypeScript
22

3-
A suite of utilities for AWS Lambda functions to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.
3+
A suite of utilities for AWS Lambda functions to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.
4+
45
You can use the library in both TypeScript and JavaScript code bases.
5-
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).
6+
7+
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.
68

79
**[📜 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)**
810

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

6769
The roadmap of Powertools is driven by customers’ demand.
68-
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.
70+
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.
6971

7072
## Connect
7173

@@ -78,4 +80,4 @@ Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn)
7880

7981
## License
8082

81-
This library is licensed under the MIT-0 License. See the LICENSE file.
83+
This library is licensed under the MIT-0 License. See the [LICENSE](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/LICENSE) file.

Diff for: ‎docs/Dockerfile

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
FROM squidfunk/mkdocs-material
2-
RUN pip install mkdocs-git-revision-date-plugin
2+
RUN pip install mkdocs-git-revision-date-plugin mkdocs-glightbox

Diff for: ‎docs/core/logger.md

+38-32
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,13 @@ Logger provides an opinionated logger with output structured as JSON.
1313
* Appending additional keys to structured logs at any point in time.
1414
* Providing a custom log formatter (Bring Your Own Formatter) to output logs in a structure compatible with your organization’s Logging RFC.
1515

16+
<br />
17+
18+
<figure>
19+
<img src="../../media/logger_utility_showcase.png" loading="lazy" alt="Screenshot of the Amazon CloudWatch Console showing an example of error logged with various log attributes" />
20+
<figcaption>Logger showcase - Log attributes</figcaption>
21+
</figure>
22+
1623
## Getting started
1724

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

2633
### Usage
2734

28-
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.
35+
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.
2936

3037
=== "handler.ts"
3138

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

4653
These settings will be used across all logs emitted:
4754

48-
Setting | Description | Environment variable | Constructor parameter
49-
------------------------------------------------- |------------------------------------------------------------------------------------------------------------------| ------------------------------------------------- | -------------------------------------------------
50-
**Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel`
51-
**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`
55+
| Setting | Description | Environment variable | Constructor parameter |
56+
|-------------------|------------------------------------------------------------------------------------------------------------------|---------------------------|-----------------------|
57+
| **Logging level** | Sets how verbose Logger should be (INFO, by default). Supported values are: `DEBUG`, `INFO`, `WARN`, `ERROR` | `LOG_LEVEL` | `logLevel` |
58+
| **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` |
5259

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

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

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

90-
Key | Example | Note
91-
------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
92-
**level**: `string` | `INFO` | Logging level set for the Lambda function"s invocation
93-
**message**: `string` | `Query performed to DynamoDB` | A descriptive, human-readable representation of this log item
94-
**sampling_rate**: `float` | `0.1` | When enabled, it prints all the logs of a percentage of invocations, e.g. 10%
95-
**service**: `string` | `serverlessAirline` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined`
96-
**timestamp**: `string` | `2011-10-05T14:48:00.000Z` | Timestamp string in simplified extended ISO format (ISO 8601)
97-
**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.
98-
**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
97+
| Key | Example | Note |
98+
|-----------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
99+
| **level**: `string` | `INFO` | Logging level set for the Lambda function"s invocation |
100+
| **message**: `string` | `Query performed to DynamoDB` | A descriptive, human-readable representation of this log item |
101+
| **sampling_rate**: `float` | `0.1` | When enabled, it prints all the logs of a percentage of invocations, e.g. 10% |
102+
| **service**: `string` | `serverlessAirline` | A unique name identifier of the service this Lambda function belongs to, by default `service_undefined` |
103+
| **timestamp**: `string` | `2011-10-05T14:48:00.000Z` | Timestamp string in simplified extended ISO format (ISO 8601) |
104+
| **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. |
105+
| **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 |
99106

100107
### Capturing Lambda context info
101108

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

114-
=== "Manual"
115-
116-
```typescript hl_lines="7"
117-
import { Logger } from '@aws-lambda-powertools/logger';
118-
119-
const logger = new Logger();
120-
121-
export const handler = async (_event, context): Promise<void> => {
122-
123-
logger.addContext(context);
124-
125-
logger.info('This is an INFO log with some context');
126-
127-
};
128-
```
129-
130121
=== "Middy Middleware"
131122

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

136127
```typescript hl_lines="1-2 10-11"
137128
import { Logger, injectLambdaContext } from '@aws-lambda-powertools/logger';
@@ -167,6 +158,21 @@ Key | Example
167158
export const myFunction = new Lambda();
168159
export const handler = myFunction.handler;
169160
```
161+
=== "Manual"
162+
163+
```typescript hl_lines="7"
164+
import { Logger } from '@aws-lambda-powertools/logger';
165+
166+
const logger = new Logger();
167+
168+
export const handler = async (_event, context): Promise<void> => {
169+
170+
logger.addContext(context);
171+
172+
logger.info('This is an INFO log with some context');
173+
174+
};
175+
```
170176

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

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

190196
#### Log incoming event
191197

192-
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`.
198+
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`.
193199

194200
???+ warning
195201
This is disabled by default to prevent sensitive info being logged

0 commit comments

Comments
 (0)