docs: add getting started section (#3818)

Co-authored-by: Alexander Schueren <[email protected]>

Author: dreamorosi

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
 

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`                                                                                                                                 |

docs/utilities/batch.md renamed to docs/features/batch.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

docs/core/event-handler/api-gateway.md renamed to docs/features/event-handler/api-gateway.md

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

docs/utilities/idempotency.md renamed to docs/features/idempotency.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>

docs/features/index.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)
@@ -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"
     ```

docs/utilities/jmespath.md renamed to docs/features/jmespath.md

@@ -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"
     ```
@@ -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"
     ```

docs/core/logger.md renamed to docs/features/logger.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"

docs/core/metrics.md renamed to docs/features/metrics.md

@@ -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"
     ```
@@ -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
 

docs/utilities/parameters.md renamed to docs/features/parameters.md

@@ -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"