From a2ec6fa997a1bc856b2ce3ae4bec4dd9baa2e537 Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Fri, 4 Aug 2023 18:18:34 +0200 Subject: [PATCH 1/7] Include Tracer environment variables Clarifies Tracer's documentation page by including its related environment variables. --- docs/core/tracer.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/core/tracer.md b/docs/core/tracer.md index 413434718db..f7163564e6b 100644 --- a/docs/core/tracer.md +++ b/docs/core/tracer.md @@ -103,6 +103,18 @@ You can trace asynchronous functions and generator functions (including context --8<-- "examples/tracer/src/capture_method_generators.py" ``` +### Environment variables + +The following environment variables are available to configure Tracer at a global scope: + +| Setting | Description | Environment variable | Default | +|-----------------------|--------------------------------------------------|--------------------------------------|---------| +| **Disable Tracing** | Explicitly disables all tracing. | `POWERTOOLS_TRACE_DISABLED` | `false` | +| **Response Capture** | Captures Lambda or method return as metadata. | `POWERTOOLS_TRACER_CAPTURE_RESPONSE` | `true` | +| **Exception Capture** | Captures Lambda or method exception as metadata. | `POWERTOOLS_TRACER_CAPTURE_ERROR` | `true` | + +Both [`POWERTOOLS_TRACER_CAPTURE_RESPONSE`](#disabling-response-auto-capture) and [`POWERTOOLS_TRACER_CAPTURE_ERROR`](#disabling-exception-auto-capture) can be set on a per-method basis, consequently overriding the environment variable value. + ## Advanced ### Patching modules From 220c6bafb4bdea5bfd32e92662ba9ec60ea2785d Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Fri, 4 Aug 2023 18:19:05 +0200 Subject: [PATCH 2/7] Include Logger environment variables Clarifies Logger's documentation page by including its related environment variables. --- docs/core/logger.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/core/logger.md b/docs/core/logger.md index 30a43a5817c..579eaefe6f5 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -341,6 +341,18 @@ You can easily change the date format using one of the following parameters: --8<-- "examples/logger/src/date_formatting_output.json" ``` +### Environment variables + +The following environment variables are available to configure Logger at a global scope: + +| Setting | Description | Environment variable | Default | +|---------------------------|------------------------------------------------------------------------------|-----------------------------------------|---------| +| **Event Logging** | Whether to log the incoming event. | `POWERTOOLS_LOGGER_LOG_EVENT` | `false` | +| **Debug Sample Rate** | Sets the debug log sampling. | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` | +| **Disable Deduplication** | Disables log deduplication filter protection to use Pytest Live Log feature. | `POWERTOOLS_LOG_DEDUPLICATION_DISABLED` | `false` | + +[`POWERTOOLS_LOGGER_LOG_EVENT`](#logging-incoming-event) can also be set on a per-method basis, and [`POWERTOOLS_LOGGER_SAMPLE_RATE`](#sampling-debug-logs) on a per-instance basis. These parameter values will override the environment variable value. + ## Advanced ### Built-in Correlation ID expressions From b1e4d38aded84943e5b54ac5063a6ed817637edb Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Fri, 4 Aug 2023 18:19:15 +0200 Subject: [PATCH 3/7] Include Metrics environment variables Clarifies Metrics' documentation page by including its related environment variables. --- docs/core/metrics.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 63ee307e789..2fd4cfc98d1 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -193,6 +193,16 @@ This has the advantage of keeping cold start metric separate from your applicati ???+ info We do not emit 0 as a value for ColdStart metric for cost reasons. [Let us know](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2C+triage&template=feature_request.md&title=){target="_blank"} if you'd prefer a flag to override it. +### Environment variables + +The following environment variable is available to configure Metrics at a global scope: + +| Setting | Description | Environment variable | Default | +|--------------------|------------------------------------------------------------------------------|-----------------------------------------|---------| +| **Namespace Name** | Sets namespace used for metrics. | `POWERTOOLS_METRICS_NAMESPACE` | `None` | + +`POWERTOOLS_METRICS_NAMESPACE` is also available on a per-instance basis with the `namespace` parameter, which will consequently override the environment variable value. + ## Advanced ### Adding metadata @@ -319,7 +329,7 @@ That is why `Metrics` shares data across instances by default, as that covers 80 ## Testing your code -### Environment variables +### Setting environment variables ???+ tip Ignore this section, if: From 3e098c1debdb5a779b73858f74ca7a864474dc35 Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Fri, 4 Aug 2023 18:23:52 +0200 Subject: [PATCH 4/7] Include middleware factory environment variables Clarifies middleware factory's documentation page by including its related environment variables. --- docs/utilities/middleware_factory.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/utilities/middleware_factory.md b/docs/utilities/middleware_factory.md index 6b0847ddb47..30bb14a207e 100644 --- a/docs/utilities/middleware_factory.md +++ b/docs/utilities/middleware_factory.md @@ -19,6 +19,16 @@ Middleware factory provides a decorator factory to create your own middleware to You might need a custom middleware to abstract non-functional code. These are often custom authorization or any reusable logic you might need to run before/after a Lambda function invocation. +### Environment variables + +The following environment variable is available to configure the middleware factory at a global scope: + +| Setting | Description | Environment variable | Default | +|----------------------|------------------------------------------------------------------------------|-----------------------------------------|---------| +| **Middleware Trace** | Creates sub-segment for each custom middleware. | `POWERTOOLS_TRACE_MIDDLEWARES` | `false` | + +You can also use [`POWERTOOLS_TRACE_MIDDLEWARES`](#tracing-middleware-execution) on a per-method basis, which will consequently override the environment variable value. + ### Middleware with no params You can create your own middleware using `lambda_handler_decorator`. The decorator factory expects 3 arguments in your function signature: From 7491929cbd406268b431cead1c64fbe3f135ef9c Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Fri, 4 Aug 2023 18:31:59 +0200 Subject: [PATCH 5/7] Include parameters utility environment variables Clarifies parameters utility's documentation page by including its related environment variables. --- docs/utilities/parameters.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/utilities/parameters.md b/docs/utilities/parameters.md index fa3241f43a8..d2d80230c77 100644 --- a/docs/utilities/parameters.md +++ b/docs/utilities/parameters.md @@ -107,6 +107,17 @@ The following will retrieve the latest version and store it in the cache. --8<-- "examples/parameters/src/getting_started_appconfig.py" ``` +### Environment variables + +The following environment variables are available to configure the parameter utility at a global scope: + +| Setting | Description | Environment variable | Default | +|-----------------------|--------------------------------------------------------------------------------|-------------------------------------|---------| +| **Max Age** | Adjusts for how long values are kept in cache (in seconds). | `POWERTOOLS_PARAMETERS_MAX_AGE` | `5` | +| **Debug Sample Rate** | Sets whether to decrypt or not values retrieved from AWS SSM Parameters Store. | `POWERTOOLS_PARAMETERS_SSM_DECRYPT` | `false` | + +You can also use [`POWERTOOLS_PARAMETERS_MAX_AGE`](#adjusting-cache-ttl) through the `max_age` parameter and [`POWERTOOLS_PARAMETERS_SSM_DECRYPT`](#ssmprovider) through the `decrypt` parameter to override the environment variable values. + ## Advanced ### Adjusting cache TTL From 1eb0948ade3902ad90b81037826076b21c343129 Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Tue, 8 Aug 2023 17:01:50 +0200 Subject: [PATCH 6/7] Move environment variables section It should be the last one under Getting Started and right before Advanced. --- docs/utilities/middleware_factory.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/utilities/middleware_factory.md b/docs/utilities/middleware_factory.md index 30bb14a207e..35e5453af65 100644 --- a/docs/utilities/middleware_factory.md +++ b/docs/utilities/middleware_factory.md @@ -19,16 +19,6 @@ Middleware factory provides a decorator factory to create your own middleware to You might need a custom middleware to abstract non-functional code. These are often custom authorization or any reusable logic you might need to run before/after a Lambda function invocation. -### Environment variables - -The following environment variable is available to configure the middleware factory at a global scope: - -| Setting | Description | Environment variable | Default | -|----------------------|------------------------------------------------------------------------------|-----------------------------------------|---------| -| **Middleware Trace** | Creates sub-segment for each custom middleware. | `POWERTOOLS_TRACE_MIDDLEWARES` | `false` | - -You can also use [`POWERTOOLS_TRACE_MIDDLEWARES`](#tracing-middleware-execution) on a per-method basis, which will consequently override the environment variable value. - ### Middleware with no params You can create your own middleware using `lambda_handler_decorator`. The decorator factory expects 3 arguments in your function signature: @@ -78,6 +68,16 @@ You can also have your own keyword arguments after the mandatory arguments. --8<-- "examples/middleware_factory/src/getting_started_middleware_with_params_payload.json" ``` +### Environment variables + +The following environment variable is available to configure the middleware factory at a global scope: + +| Setting | Description | Environment variable | Default | +|----------------------|------------------------------------------------------------------------------|-----------------------------------------|---------| +| **Middleware Trace** | Creates sub-segment for each custom middleware. | `POWERTOOLS_TRACE_MIDDLEWARES` | `false` | + +You can also use [`POWERTOOLS_TRACE_MIDDLEWARES`](#tracing-middleware-execution) on a per-method basis, which will consequently override the environment variable value. + ## Advanced For advanced use cases, you can instantiate [Tracer](../core/tracer.md){target="_blank"} inside your middleware, and add annotations as well as metadata for additional operational insights. From 2f46fcf981f0d1a57776bd6fea567a741274d108 Mon Sep 17 00:00:00 2001 From: Diego Barreiro Date: Tue, 8 Aug 2023 17:03:27 +0200 Subject: [PATCH 7/7] Link basic configuration to environment variables As basic configuration mentions a few environment variables, it may be useful to provide a link to all the other available ones. --- docs/core/logger.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/core/logger.md b/docs/core/logger.md index 579eaefe6f5..6fc48e8898f 100644 --- a/docs/core/logger.md +++ b/docs/core/logger.md @@ -24,6 +24,8 @@ Logger requires two settings: | **Logging level** | Sets how verbose Logger should be (INFO, by default) | `LOG_LEVEL` | `level` | | **Service** | Sets **service** key that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `service` | +There are some [other environment variables](#environment-variables) which can be set to modify Logger's settings at a global scope. + ```yaml hl_lines="12-13" title="AWS Serverless Application Model (SAM) example" --8<-- "examples/logger/sam/template.yaml" ``` @@ -351,7 +353,7 @@ The following environment variables are available to configure Logger at a globa | **Debug Sample Rate** | Sets the debug log sampling. | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` | | **Disable Deduplication** | Disables log deduplication filter protection to use Pytest Live Log feature. | `POWERTOOLS_LOG_DEDUPLICATION_DISABLED` | `false` | -[`POWERTOOLS_LOGGER_LOG_EVENT`](#logging-incoming-event) can also be set on a per-method basis, and [`POWERTOOLS_LOGGER_SAMPLE_RATE`](#sampling-debug-logs) on a per-instance basis. These parameter values will override the environment variable value. +[`POWERTOOLS_LOGGER_LOG_EVENT`](#logging-incoming-event) can also be set on a per-method basis, and [`POWERTOOLS_LOGGER_SAMPLE_RATE`](#sampling-debug-logs) on a per-instance basis. These parameter values will override the environment variable value. ## Advanced