Skip to content

docs: add getting started section #3818

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.

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
Apr 15, 2025
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
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
2 changes: 1 addition & 1 deletion docs/contributing/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ There are also a few other workspaces that are not utilities published to npm, b

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

## Testing definition

Expand Down
43 changes: 43 additions & 0 deletions docs/environment-variables.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: Environment Variables
description: Environment Variables for Powertools for AWS Lambda
---

<!-- markdownlint-disable MD043 -->

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.

???+ info
Explicit parameters in your code take precedence over environment variables

| Environment variable | Description | Utility | Default |
| -------------------------------------------- |------------------------------------------------------------------------------------------| -------------------------------------- |------------------------------------------------|
| **POWERTOOLS_SERVICE_NAME** | Set service name used for tracing namespace, metrics dimension and structured logging | All | `service_undefined` |
| **POWERTOOLS_METRICS_NAMESPACE** | Set namespace used for metrics | [Metrics](features/metrics.md) | `default_namespace` |
| **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) |
| **POWERTOOLS_METRICS_ENABLED** | Explicitly disables emitting metrics to stdout | [Metrics](features/metrics.md) | `true` |
| **POWERTOOLS_TRACE_ENABLED** | Explicitly disables tracing | [Tracer](features/tracer.md) | `true` |
| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Capture Lambda or method return as metadata. | [Tracer](features/tracer.md) | `true` |
| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Capture Lambda or method exception as metadata. | [Tracer](features/tracer.md) | `true` |
| **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Capture HTTP(s) requests as segments. | [Tracer](features/tracer.md) | `true` |
| **POWERTOOLS_LOGGER_LOG_EVENT** | Log incoming event | [Logger](features/logger.md) | `false` |
| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logger](features/logger.md) | `0` |
| **POWERTOOLS_DEV** | Pretty-print logs, disable metrics flushing, and disable traces - use for dev only | See section below | `false` |
| **POWERTOOLS_LOG_LEVEL** | Sets how verbose Logger should be, from the most verbose to the least verbose (no logs) | [Logger](features/logger.md) | `INFO` |
| **POWERTOOLS_PARAMETERS_MAX_AGE** | Adjust how long values are kept in cache (in seconds) | [Parameters](features/parameters.md) | `5` |
| **POWERTOOLS_PARAMETERS_SSM_DECRYPT** | Set whether to decrypt or not values retrieved from AWS Systems Manager Parameters Store | [Parameters](features/parameters.md) | `false` |
| **POWERTOOLS_IDEMPOTENCY_DISABLED** | Disable the Idempotency logic without changing your code, useful for testing | [Idempotency](features/idempotency.md) | `false` |

Each Utility page provides information on example values and allowed values.

## Dev Mode

Whether you're prototyping locally or against a non-production environment, you can use `POWERTOOLS_DEV` to increase verbosity across multiple utilities.

When `POWERTOOLS_DEV` is set to a truthy value (`1`, `true`), it'll have the following effects:

| Utility | Effect |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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 |
| **Tracer** | Disables tracing operations in non-Lambda environments. This already happens automatically in the Tracer utility |
| **Metrics** | Disables emitting metrics to stdout. Can be overridden by setting `POWERTOOLS_METRICS_ENABLED` to `true` |
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Bala

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

## Getting started
Expand Down
14 changes: 0 additions & 14 deletions docs/utilities/idempotency.md → docs/features/idempotency.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,13 +162,6 @@ The function this example has two arguments, note that while wrapping it with th

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

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

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.

If this is not the desired behavior, you can use one of the other patterns to make your logic idempotent.

=== "index.ts"

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

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.
The configuration options for the `@idempotent` decorator are the same as the ones for the `makeIdempotent` function wrapper.

### MakeHandlerIdempotent Middy middleware

!!! tip "A note about Middy"
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
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"}.

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.

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.
Expand Down
82 changes: 82 additions & 0 deletions docs/features/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
title: Features
description: Features of Powertools for AWS Lambda
---

<!-- markdownlint-disable MD043 -->

<div class="grid cards" markdown>

- __Tracer__

---

Instrument your code with minimal effort. Capture traces and metadata to understand the performance of your Lambda functions.

[:octicons-arrow-right-24: Read more](./tracer.md)

- __Logger__

---

JSON Structured logging made easier, key management, buffering, and Middy.js middleware to enrich structured logging with key Lambda context details.

[:octicons-arrow-right-24: Read more](./logger.md)

- __Metrics__

---

Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)

[:octicons-arrow-right-24: Read more](./metrics.md)

- __Parameters__

---

High-level functions to retrieve one or more parameters from AWS SSM Parameter Store, AWS Secrets Manager, AWS AppConfig, and Amazon DynamoDB

[:octicons-arrow-right-24: Read more](./parameters.md)

- __Idempotency__

---

Class method decorator, Middy middleware, and function wrapper to make your Lambda functions idempotent and prevent duplicate execution based on payload content.

[:octicons-arrow-right-24: Read more](./idempotency.md)

- __Batch Processing__

---

Simplify the processing of batches of events with built-in support for SQS and DynamoDB Streams.

[:octicons-arrow-right-24: Read more](./batch.md)

- __JMESPath Functions__

---

Built-in JMESPath functions to easily deserialize common encoded JSON payloads in Lambda functions.

[:octicons-arrow-right-24: Read more](./jmespath.md)

- __Parser__

---

Utility to parse and validate AWS Lambda event payloads using Zod, a TypeScript-first schema declaration and validation library.

[:octicons-arrow-right-24: Read more](./parser.md)

- __Validation__

---

JSON Schema validation for events and responses, including JMESPath support to unwrap events before validation.

[:octicons-arrow-right-24: Read more](./validation.md)

</div>
File renamed without changes.
14 changes: 2 additions & 12 deletions docs/core/logger.md → docs/features/logger.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@ These settings will be used across all logs emitted:
???+ info
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.

See all environment variables in the [Environment variables](../index.md/#environment-variables) section.
See all environment variables in the [Environment variables](../environment-variables.md) section.

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

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

=== "Middy Middleware"

!!! tip "A note about Middy"
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
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"}.

```typescript hl_lines="2 14"
--8<-- "examples/snippets/logger/middy.ts"
```

=== "Decorator"

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

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.

If this is not the desired behavior, you can call the `logger.injectLambdaContext()` method directly in your handler.

```typescript hl_lines="8"
--8<-- "examples/snippets/logger/decorator.ts"
```
Expand Down
11 changes: 0 additions & 11 deletions docs/core/metrics.md → docs/features/metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,10 +201,6 @@ You can add default dimensions to your metrics by passing them as parameters in

=== "Middy middleware"

!!! tip "A note about Middy"
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
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"}.

```typescript hl_lines="24-26"
--8<-- "examples/snippets/metrics/defaultDimensionsMiddy.ts"
```
Expand All @@ -217,13 +213,6 @@ You can add default dimensions to your metrics by passing them as parameters in

=== "with logMetrics decorator"

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

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.

If this is not the desired behavior, you can use the `logMetrics` middleware instead.

```typescript hl_lines="12"
--8<-- "examples/snippets/metrics/defaultDimensionsDecorator.ts"
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -413,7 +413,7 @@ You can use the `awsSdkV3Client` parameter via any of the available [Provider Cl
| [DynamoDBProvider](#dynamodbprovider) | `new DynamoDBClient();` |

???+ question "When is this useful?"
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.
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.

=== "SSMProvider"
```typescript hl_lines="5 7"
Expand Down
File renamed without changes.
11 changes: 1 addition & 10 deletions docs/core/tracer.md → docs/features/tracer.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,21 +153,12 @@ You can quickly start by importing the `Tracer` class, initialize it outside the

=== "Middy Middleware"

!!! tip "A note about Middy"
We guarantee support for Middy.js `v4.x` through `v6.x` versions.
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"}.

```typescript hl_lines="2 15 17"
--8<-- "examples/snippets/tracer/middy.ts"
```

=== "Decorator"

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

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.

```typescript hl_lines="8"
--8<-- "examples/snippets/tracer/decorator.ts"
```
Expand All @@ -185,7 +176,7 @@ When using the `captureLambdaHandler` decorator or middleware, Tracer performs t
* Handles the lifecycle of the subsegment
* Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
* Creates a `Service` annotation to easily filter traces that have a specific service name
* Captures any response, or full exceptions generated by the handler, and include them as tracing metadata
* Captures any response, or full exceptions generated by the handler, and includes them as tracing metadata

### Annotations & Metadata

Expand Down
5 changes: 0 additions & 5 deletions docs/utilities/validation.md → docs/features/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,6 @@ The `@validator` decorator is a class method decorator that you can use to valid

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

??? note "A note on class method decorators"
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.

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.

=== "gettingStartedDecorator.ts"

```typescript hl_lines="1 11-14"
Expand Down
Loading
Loading