Skip to content

Commit bf5ad24

Browse files
dreamorosiam29d
dreamorosi
and
am29d
authored
docs: add getting started section (#3818)
Co-authored-by: Alexander Schueren <[email protected]>
1 parent 8545d49 commit bf5ad24

23 files changed

+715
-431
lines changed

Diff for: ‎docs/contributing/conventions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ There are also a few other workspaces that are not utilities published to npm, b
3636

3737
* `examples/snippets`: contains the documentation code snippets
3838
* `examples/app`: contains an example project that can be deployed via AWS CDK or AWS SAM
39-
* `layers`: contains the code used to build and publish the [Lambda layers](../index.md#lambda-layer)
39+
* `layers`: contains the code used to build and publish the [Lambda layers](../getting-started/lambda-layers.md)
4040

4141
## Testing definition
4242

Diff for: ‎docs/environment-variables.md

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Environment Variables
3+
description: Environment Variables for Powertools for AWS Lambda
4+
---
5+
6+
<!-- markdownlint-disable MD043 -->
7+
8+
You can configure Powertools for AWS Lambda using environment variables. This is useful when you want to set configuration values in your Infrastructure as Code (IaC) templates or when you want to override default values without changing your code.
9+
10+
???+ info
11+
Explicit parameters in your code take precedence over environment variables
12+
13+
| Environment variable | Description | Utility | Default |
14+
| -------------------------------------------- |------------------------------------------------------------------------------------------| -------------------------------------- |------------------------------------------------|
15+
| **POWERTOOLS_SERVICE_NAME** | Set service name used for tracing namespace, metrics dimension and structured logging | All | `service_undefined` |
16+
| **POWERTOOLS_METRICS_NAMESPACE** | Set namespace used for metrics | [Metrics](features/metrics.md) | `default_namespace` |
17+
| **POWERTOOLS_METRICS_FUNCTION_NAME** | Function name used as dimension for the `ColdStart` metric | [Metrics](features/metrics.md) | [See docs](features/metrics.md#setting-function-name) |
18+
| **POWERTOOLS_METRICS_ENABLED** | Explicitly disables emitting metrics to stdout | [Metrics](features/metrics.md) | `true` |
19+
| **POWERTOOLS_TRACE_ENABLED** | Explicitly disables tracing | [Tracer](features/tracer.md) | `true` |
20+
| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Capture Lambda or method return as metadata. | [Tracer](features/tracer.md) | `true` |
21+
| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Capture Lambda or method exception as metadata. | [Tracer](features/tracer.md) | `true` |
22+
| **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Capture HTTP(s) requests as segments. | [Tracer](features/tracer.md) | `true` |
23+
| **POWERTOOLS_LOGGER_LOG_EVENT** | Log incoming event | [Logger](features/logger.md) | `false` |
24+
| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](features/logger.md) | `0` |
25+
| **POWERTOOLS_DEV** | Pretty-print logs, disable metrics flushing, and disable traces - use for dev only | See section below | `false` |
26+
| **POWERTOOLS_LOG_LEVEL** | Sets how verbose Logger should be, from the most verbose to the least verbose (no logs) | [Logger](features/logger.md) | `INFO` |
27+
| **POWERTOOLS_PARAMETERS_MAX_AGE** | Adjust how long values are kept in cache (in seconds) | [Parameters](features/parameters.md) | `5` |
28+
| **POWERTOOLS_PARAMETERS_SSM_DECRYPT** | Set whether to decrypt or not values retrieved from AWS Systems Manager Parameters Store | [Parameters](features/parameters.md) | `false` |
29+
| **POWERTOOLS_IDEMPOTENCY_DISABLED** | Disable the Idempotency logic without changing your code, useful for testing | [Idempotency](features/idempotency.md) | `false` |
30+
31+
Each Utility page provides information on example values and allowed values.
32+
33+
## Dev Mode
34+
35+
Whether you're prototyping locally or against a non-production environment, you can use `POWERTOOLS_DEV` to increase verbosity across multiple utilities.
36+
37+
When `POWERTOOLS_DEV` is set to a truthy value (`1`, `true`), it'll have the following effects:
38+
39+
| Utility | Effect |
40+
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41+
| **Logger** | Increase JSON indentation to 4 and uses global `console` to emit logs to ease testing and local debugging when running functions locally. However, Amazon CloudWatch Logs view will degrade as each new line is treated as a new message |
42+
| **Tracer** | Disables tracing operations in non-Lambda environments. This already happens automatically in the Tracer utility |
43+
| **Metrics** | Disables emitting metrics to stdout. Can be overridden by setting `POWERTOOLS_METRICS_ENABLED` to `true` |

Diff for: ‎docs/utilities/batch.md renamed to ‎docs/features/batch.md

File renamed without changes.

Diff for: ‎docs/core/event-handler/api-gateway.md renamed to ‎docs/features/event-handler/api-gateway.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Bala
1313

1414
* Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs.
1515
* Support for CORS, binary and Gzip compression, Decimals JSON encoding and bring your own JSON serializer
16-
* Built-in integration with [Parser](../../utilities/parser.md){target="_blank"} for easy payload validation and parsing
16+
* Built-in integration with [Parser](../../features/parser.md){target="_blank"} for easy payload validation and parsing
1717
* Works with micro function (one or a few routes) and monolithic functions (all routes)
1818

1919
## Getting started

Diff for: ‎docs/utilities/idempotency.md renamed to ‎docs/features/idempotency.md

-14
Original file line numberDiff line numberDiff line change
@@ -162,13 +162,6 @@ The function this example has two arguments, note that while wrapping it with th
162162

163163
You can also use the `@idempotent` decorator to make your Lambda handler idempotent, similar to the `makeIdempotent` function wrapper.
164164

165-
!!! info
166-
The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
167-
168-
Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
169-
170-
If this is not the desired behavior, you can use one of the other patterns to make your logic idempotent.
171-
172165
=== "index.ts"
173166

174167
```typescript hl_lines="17"
@@ -181,15 +174,8 @@ You can also use the `@idempotent` decorator to make your Lambda handler idempot
181174
--8<-- "examples/snippets/idempotency/types.ts"
182175
```
183176

184-
You can use the decorator on your Lambda handler or on any function that returns a response to make it idempotent. This is useful when you want to make a specific logic idempotent, for example when your Lambda handler performs multiple side effects and you only want to make a specific one idempotent.
185-
The configuration options for the `@idempotent` decorator are the same as the ones for the `makeIdempotent` function wrapper.
186-
187177
### MakeHandlerIdempotent Middy middleware
188178

189-
!!! tip "A note about Middy"
190-
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
191-
Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
192-
193179
If you are using [Middy.js](https://middy.js.org){target="_blank"} as your middleware engine, you can use the `makeHandlerIdempotent` middleware to make your Lambda handler idempotent.
194180

195181
Similar to the `makeIdempotent` function wrapper, you can quickly make your Lambda handler idempotent by initializing the `DynamoDBPersistenceLayer` class and using it with the `makeHandlerIdempotent` middleware.

Diff for: ‎docs/features/index.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Features
3+
description: Features of Powertools for AWS Lambda
4+
---
5+
6+
<!-- markdownlint-disable MD043 -->
7+
8+
<div class="grid cards" markdown>
9+
10+
- __Tracer__
11+
12+
---
13+
14+
Instrument your code with minimal effort. Capture traces and metadata to understand the performance of your Lambda functions.
15+
16+
[:octicons-arrow-right-24: Read more](./tracer.md)
17+
18+
- __Logger__
19+
20+
---
21+
22+
JSON Structured logging made easier, key management, buffering, and Middy.js middleware to enrich structured logging with key Lambda context details.
23+
24+
[:octicons-arrow-right-24: Read more](./logger.md)
25+
26+
- __Metrics__
27+
28+
---
29+
30+
Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
31+
32+
[:octicons-arrow-right-24: Read more](./metrics.md)
33+
34+
- __Parameters__
35+
36+
---
37+
38+
High-level functions to retrieve one or more parameters from AWS SSM Parameter Store, AWS Secrets Manager, AWS AppConfig, and Amazon DynamoDB
39+
40+
[:octicons-arrow-right-24: Read more](./parameters.md)
41+
42+
- __Idempotency__
43+
44+
---
45+
46+
Class method decorator, Middy middleware, and function wrapper to make your Lambda functions idempotent and prevent duplicate execution based on payload content.
47+
48+
[:octicons-arrow-right-24: Read more](./idempotency.md)
49+
50+
- __Batch Processing__
51+
52+
---
53+
54+
Simplify the processing of batches of events with built-in support for SQS and DynamoDB Streams.
55+
56+
[:octicons-arrow-right-24: Read more](./batch.md)
57+
58+
- __JMESPath Functions__
59+
60+
---
61+
62+
Built-in JMESPath functions to easily deserialize common encoded JSON payloads in Lambda functions.
63+
64+
[:octicons-arrow-right-24: Read more](./jmespath.md)
65+
66+
- __Parser__
67+
68+
---
69+
70+
Utility to parse and validate AWS Lambda event payloads using Zod, a TypeScript-first schema declaration and validation library.
71+
72+
[:octicons-arrow-right-24: Read more](./parser.md)
73+
74+
- __Validation__
75+
76+
---
77+
78+
JSON Schema validation for events and responses, including JMESPath support to unwrap events before validation.
79+
80+
[:octicons-arrow-right-24: Read more](./validation.md)
81+
82+
</div>

Diff for: ‎docs/utilities/jmespath.md renamed to ‎docs/features/jmespath.md

File renamed without changes.

Diff for: ‎docs/core/logger.md renamed to ‎docs/features/logger.md

+2-12
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,8 @@ These settings will be used across all logs emitted:
5656
???+ info
5757
When `POWERTOOLS_DEV` environment variable is present and set to `"true"` or `"1"`, Logger will pretty-print log messages for easier readability. We recommend to use this setting only when debugging on local environments.
5858

59-
See all environment variables in the [Environment variables](../index.md/#environment-variables) section.
59+
See all environment variables in the [Environment variables](../environment-variables.md) section.
60+
6061
Check API docs to learn more about [Logger constructor options](https://docs.powertools.aws.dev/lambda/typescript/latest/api/types/_aws_lambda_powertools_logger.types.ConstructorOptions.html){target="_blank"}.
6162

6263
#### Example using AWS Serverless Application Model (SAM)
@@ -114,23 +115,12 @@ This functionality will include the following keys in your structured logs:
114115

115116
=== "Middy Middleware"
116117

117-
!!! tip "A note about Middy"
118-
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
119-
Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
120-
121118
```typescript hl_lines="2 14"
122119
--8<-- "examples/snippets/logger/middy.ts"
123120
```
124121

125122
=== "Decorator"
126123

127-
!!! note
128-
The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
129-
130-
Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
131-
132-
If this is not the desired behavior, you can call the `logger.injectLambdaContext()` method directly in your handler.
133-
134124
```typescript hl_lines="8"
135125
--8<-- "examples/snippets/logger/decorator.ts"
136126
```

Diff for: ‎docs/core/metrics.md renamed to ‎docs/features/metrics.md

-11
Original file line numberDiff line numberDiff line change
@@ -201,10 +201,6 @@ You can add default dimensions to your metrics by passing them as parameters in
201201

202202
=== "Middy middleware"
203203

204-
!!! tip "A note about Middy"
205-
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
206-
Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
207-
208204
```typescript hl_lines="24-26"
209205
--8<-- "examples/snippets/metrics/defaultDimensionsMiddy.ts"
210206
```
@@ -217,13 +213,6 @@ You can add default dimensions to your metrics by passing them as parameters in
217213

218214
=== "with logMetrics decorator"
219215

220-
!!! note
221-
The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
222-
223-
Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
224-
225-
If this is not the desired behavior, you can use the `logMetrics` middleware instead.
226-
227216
```typescript hl_lines="12"
228217
--8<-- "examples/snippets/metrics/defaultDimensionsDecorator.ts"
229218
```

Diff for: ‎docs/utilities/parameters.md renamed to ‎docs/features/parameters.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -413,7 +413,7 @@ You can use the `awsSdkV3Client` parameter via any of the available [Provider Cl
413413
| [DynamoDBProvider](#dynamodbprovider) | `new DynamoDBClient();` |
414414

415415
???+ question "When is this useful?"
416-
Injecting a custom AWS SDK v3 client allows you to [apply tracing](../core/tracer.md#patching-aws-sdk-clients) or make unit/snapshot testing easier, including SDK customizations.
416+
Injecting a custom AWS SDK v3 client allows you to [apply tracing](../features/tracer.md#patching-aws-sdk-clients) or make unit/snapshot testing easier, including SDK customizations.
417417

418418
=== "SSMProvider"
419419
```typescript hl_lines="5 7"

Diff for: ‎docs/utilities/parser.md renamed to ‎docs/features/parser.md

File renamed without changes.

Diff for: ‎docs/core/tracer.md renamed to ‎docs/features/tracer.md

+1-10
Original file line numberDiff line numberDiff line change
@@ -153,21 +153,12 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
153153

154154
=== "Middy Middleware"
155155

156-
!!! tip "A note about Middy"
157-
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
158-
Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
159-
160156
```typescript hl_lines="2 15 17"
161157
--8<-- "examples/snippets/tracer/middy.ts"
162158
```
163159

164160
=== "Decorator"
165161

166-
!!! note
167-
The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript.
168-
169-
Additionally, they are implemented to decorate async methods. When decorating a synchronous one, the decorator replaces its implementation with an async one causing the caller to have to `await` the now decorated method.
170-
171162
```typescript hl_lines="8"
172163
--8<-- "examples/snippets/tracer/decorator.ts"
173164
```
@@ -185,7 +176,7 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
185176
* Handles the lifecycle of the subsegment
186177
* Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
187178
* Creates a `Service` annotation to easily filter traces that have a specific service name
188-
* Captures any response, or full exceptions generated by the handler, and include them as tracing metadata
179+
* Captures any response, or full exceptions generated by the handler, and includes them as tracing metadata
189180

190181
### Annotations & Metadata
191182

Diff for: ‎docs/utilities/validation.md renamed to ‎docs/features/validation.md

-5
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,6 @@ The `@validator` decorator is a class method decorator that you can use to valid
3434

3535
If the validation fails, we will throw a `SchemaValidationError`.
3636

37-
??? note "A note on class method decorators"
38-
The class method decorators in this project follow the experimental implementation enabled via the [`experimentalDecorators` compiler option](https://www.typescriptlang.org/tsconfig#experimentalDecorators) in TypeScript. We will add support for the newer Stage 3 decorators proposal in the next major release.
39-
40-
All our decorators assume that the method they are decorating is an async method. This means that even when decorating a synchronous method, it will return a promise. If this is not the desired behavior, you can use one of the other patterns to validate your payloads.
41-
4237
=== "gettingStartedDecorator.ts"
4338

4439
```typescript hl_lines="1 11-14"

0 commit comments

Comments
 (0)