aws-powertools · dreamorosi · Apr 15, 2025 · Feb 27, 2025 · Apr 8, 2025 · Apr 8, 2025
diff --git a/docs/contributing/conventions.md b/docs/contributing/conventions.md
@@ -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
 

diff --git a/docs/environment-variables.md b/docs/environment-variables.md
@@ -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`                                                                                                                                 |
diff --git a/docs/utilities/batch.md → docs/features/batch.md b/docs/utilities/batch.md → docs/features/batch.md
diff --git a/docs/core/event-handler/api-gateway.md → docs/features/event-handler/api-gateway.md b/docs/core/event-handler/api-gateway.md → docs/features/event-handler/api-gateway.md
@@ -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

diff --git a/docs/utilities/idempotency.md → docs/features/idempotency.md b/docs/utilities/idempotency.md → docs/features/idempotency.md
diff --git a/docs/features/index.md b/docs/features/index.md
@@ -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>
diff --git a/docs/utilities/jmespath.md → docs/features/jmespath.md b/docs/utilities/jmespath.md → docs/features/jmespath.md
diff --git a/docs/core/logger.md → docs/features/logger.md b/docs/core/logger.md → docs/features/logger.md
@@ -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)

diff --git a/docs/core/metrics.md → docs/features/metrics.md b/docs/core/metrics.md → docs/features/metrics.md
diff --git a/docs/utilities/parameters.md → docs/features/parameters.md b/docs/utilities/parameters.md → docs/features/parameters.md
@@ -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"

diff --git a/docs/utilities/parser.md → docs/features/parser.md b/docs/utilities/parser.md → docs/features/parser.md
diff --git a/docs/core/tracer.md → docs/features/tracer.md b/docs/core/tracer.md → docs/features/tracer.md
diff --git a/docs/utilities/validation.md → docs/features/validation.md b/docs/utilities/validation.md → docs/features/validation.md
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -0,0 +1,32 @@
+---
+title: Installation
+description: Installing Powertools for AWS Lambda
+---
+
+<!-- markdownlint-disable MD043 -->
+
+You can use Powertools for AWS Lambda (TypeScript) by installing it with your favorite dependency management, or via [Lambda Layers](./lambda-layers.md).
+
+The toolkit is compatible with both TypeScript and JavaScript code bases, and supports both CommonJS and ES modules.
+
+All features are available as individual packages, so you can install only the ones you need, for example:
+
+* **Logger**: `npm i @aws-lambda-powertools/logger`{.copyMe}:clipboard:
+* **Metrics**: `npm i @aws-lambda-powertools/metrics`{.copyMe}:clipboard:
+* **Tracer**: `npm i @aws-lambda-powertools/tracer`{.copyMe}:clipboard:
+
+See the [Features](../features/index.md) page for a complete list of available utilities.
+
+### Extra dependencies
+
+Some features use additional dependencies like the AWS SDK for JavaScript v3, which might you need to install separately. Below is a list of utilities that use external dependencies, and the packages you need to install to use them.
+
+| Feature                                                              | Install                                                                                                           | Default dependency  |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- |
+| **[Tracer](../features/tracer.md)**                                   | **`npm i @aws-lambda-powertools/tracer`**{.copyMe}:clipboard:                                                     | `aws-xray-sdk-core` |
+| **[Idempotency](../features/idempotency.md)**                         | **`npm i @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb`**{.copyMe}:clipboard: |                     |
+| **[Parameters (SSM)](../features/parameters.md)**                     | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-ssm`**{.copyMe}:clipboard:                             |                     |
+| **[Parameters (Secrets Manager)](../features/parameters.md)**         | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager`**{.copyMe}:clipboard:                 |                     |
+| **[Parameters (AppConfig)](../features/parameters.md)**               | **`npm i @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata`**{.copyMe}:clipboard:                   |                     |
+| **[Parser](../features/parser.md)**                                   | **`npm i @aws-lambda-powertools/parser zod@~3`**{.copyMe}:clipboard:                                              |                     |
+| **[Validation](../features/validation.md)**                           | **`npm i @aws-lambda-powertools/validation`**{.copyMe}:clipboard:                                                 | `ajv`               |