Skip to content

Commit 85d4df8

Browse files
heitorlessaleandrodamascena
heitorlessa
and
leandrodamascena
authored
docs(logger): improve ALC messaging in the PT context (#3359)
* fix(parameters): make cache aware of single vs multiple calls Signed-off-by: heitorlessa <[email protected]> * chore: cleanup, add test for single and nested Signed-off-by: heitorlessa <[email protected]> * docs(logger): improve messaging on ALC usefulness in PT ctx --------- Signed-off-by: heitorlessa <[email protected]> Co-authored-by: Leandro Damascena <[email protected]>
1 parent 879e5c8 commit 85d4df8

File tree

1 file changed

+38
-28
lines changed

1 file changed

+38
-28
lines changed

‎docs/core/logger.md

+38-28
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ Logger provides an opinionated logger with output structured as JSON.
1919

2020
Logger requires two settings:
2121

22-
| Setting | Description | Environment variable | Constructor parameter |
23-
| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------- | --------------------- |
24-
| **Logging level** | Sets how verbose Logger should be (INFO, by default) | `POWERTOOLS_LOG_LEVEL` | `level` |
25-
| **Service** | Sets **service** key that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `service` |
22+
| Setting | Description | Environment variable | Constructor parameter |
23+
| ----------------- | ------------------------------------------------------------------- | ------------------------- | --------------------- |
24+
| **Logging level** | Sets how verbose Logger should be (INFO, by default) | `POWERTOOLS_LOG_LEVEL` | `level` |
25+
| **Service** | Sets **service** key that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `service` |
2626

2727
There are some [other environment variables](#environment-variables) which can be set to modify Logger's settings at a global scope.
2828

@@ -39,7 +39,7 @@ Your Logger will include the following keys to your structured logging:
3939
| **level**: `str` | `INFO` | Logging level |
4040
| **location**: `str` | `collect.handler:1` | Source code location where statement was executed |
4141
| **message**: `Any` | `Collecting payment` | Unserializable JSON values are casted as `str` |
42-
| **timestamp**: `str` | `2021-05-03 10:20:19,650+0000` | Timestamp with milliseconds, by default uses default AWS Lambda timezone (UTC) |
42+
| **timestamp**: `str` | `2021-05-03 10:20:19,650+0000` | Timestamp with milliseconds, by default uses default AWS Lambda timezone (UTC) |
4343
| **service**: `str` | `payment` | Service name defined, by default `service_undefined` |
4444
| **xray_trace_id**: `str` | `1-5759e988-bd862e3fe1be46a994272793` | When [tracing is enabled](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html){target="_blank"}, it shows X-Ray Trace ID |
4545
| **sampling_rate**: `float` | `0.1` | When enabled, it shows sampling rate in percentage e.g. 10% |
@@ -280,13 +280,13 @@ The default log level is `INFO`. It can be set using the `level` constructor opt
280280

281281
We support the following log levels:
282282

283-
| Level | Numeric value | Standard logging
284-
| ---------- | ------------- | -----------------
285-
| `DEBUG` | 10 | `logging.DEBUG`
286-
| `INFO` | 20 | `logging.INFO`
287-
| `WARNING` | 30 | `logging.WARNING`
288-
| `ERROR` | 40 | `logging.ERROR`
289-
| `CRITICAL` | 50 | `logging.CRITICAL`
283+
| Level | Numeric value | Standard logging |
284+
| ---------- | ------------- | ------------------ |
285+
| `DEBUG` | 10 | `logging.DEBUG` |
286+
| `INFO` | 20 | `logging.INFO` |
287+
| `WARNING` | 30 | `logging.WARNING` |
288+
| `ERROR` | 40 | `logging.ERROR` |
289+
| `CRITICAL` | 50 | `logging.CRITICAL` |
290290

291291
If you want to access the numeric value of the current log level, you can use the `log_level` property. For example, if the current log level is `INFO`, `logger.log_level` property will return `10`.
292292

@@ -304,39 +304,49 @@ If you want to access the numeric value of the current log level, you can use th
304304

305305
#### AWS Lambda Advanced Logging Controls (ALC)
306306

307+
!!! question "When is it useful?"
308+
When you want to set a logging policy to drop informational or verbose logs for one or all AWS Lambda functions, regardless of runtime and logger used.
309+
307310
<!-- markdownlint-disable MD013 -->
308-
With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced){target="_blank"}, you can control the output format of your logs as either `TEXT` or `JSON` and specify the minimum accepted log level for your application. Regardless of the output format setting in Lambda, we will always output JSON formatted logging messages.
309-
<!-- markdownlint-enable MD013 -->
311+
With [AWS Lambda Advanced Logging Controls (ALC)](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-advanced){target="_blank"}, you can enforce a minimum log level that Lambda will accept from your application code.
310312

311-
When you have this feature enabled, log messages that don’t meet the configured log level are discarded by Lambda. For example, if you set the minimum log level to `WARN`, you will only receive `WARN` and `ERROR` messages in your AWS CloudWatch Logs, all other log levels will be discarded by Lambda.
313+
When enabled, you should keep `Logger` and ALC log level in sync to avoid data loss.
314+
315+
Here's a sequence diagram to demonstrate how ALC will drop both `INFO` and `DEBUG` logs emitted from `Logger`, when ALC log level is stricter than `Logger`.
316+
<!-- markdownlint-enable MD013 -->
312317

313318
```mermaid
314319
sequenceDiagram
315320
title Lambda ALC allows WARN logs only
316321
participant Lambda service
317322
participant Lambda function
318323
participant Application Logger
324+
319325
Note over Lambda service: AWS_LAMBDA_LOG_LEVEL="WARN"
326+
Note over Application Logger: POWERTOOLS_LOG_LEVEL="DEBUG"
327+
320328
Lambda service->>Lambda function: Invoke (event)
321329
Lambda function->>Lambda function: Calls handler
322-
Lambda function->>Application Logger: logger.warn("Something happened")
330+
Lambda function->>Application Logger: logger.error("Something happened")
323331
Lambda function-->>Application Logger: logger.debug("Something happened")
324332
Lambda function-->>Application Logger: logger.info("Something happened")
325-
Lambda service->>Lambda service: DROP INFO and DEBUG logs
333+
Lambda service--xLambda service: DROP INFO and DEBUG logs
326334
Lambda service->>CloudWatch Logs: Ingest error logs
327335
```
328336

329337
**Priority of log level settings in Powertools for AWS Lambda**
330338

331-
When the Advanced Logging Controls feature is enabled, we are unable to increase the minimum log level below the `AWS_LAMBDA_LOG_LEVEL` environment variable value, see [AWS Lambda service documentation](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-log-level){target="_blank"} for more details.
332-
333339
We prioritise log level settings in this order:
334340

335341
1. `AWS_LAMBDA_LOG_LEVEL` environment variable
336-
2. Setting the log level in code using the `level` constructor option, or by calling the `logger.setLevel()` method
342+
2. Explicit log level in `Logger` constructor, or by calling the `logger.setLevel()` method
337343
3. `POWERTOOLS_LOG_LEVEL` environment variable
338344

339-
In the event you have set a log level in Powertools to a level that is lower than the ACL setting, we will output a warning log message informing you that your messages will be discarded by Lambda.
345+
If you set `Logger` level lower than ALC, we will emit a warning informing you that your messages will be discarded by Lambda.
346+
347+
> **NOTE**
348+
>
349+
> With ALC enabled, we are unable to increase the minimum log level below the `AWS_LAMBDA_LOG_LEVEL` environment variable value, see [AWS Lambda service documentation](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html#monitoring-cloudwatchlogs-log-level){target="_blank"} for more details.
340350
341351
### Logging exceptions
342352

@@ -427,12 +437,12 @@ You can easily change the date format using one of the following parameters:
427437

428438
The following environment variables are available to configure Logger at a global scope:
429439

430-
| Setting | Description | Environment variable | Default |
431-
|---------------------------|------------------------------------------------------------------------------|-----------------------------------------|---------|
432-
| **Event Logging** | Whether to log the incoming event. | `POWERTOOLS_LOGGER_LOG_EVENT` | `false` |
433-
| **Debug Sample Rate** | Sets the debug log sampling. | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` |
434-
| **Disable Deduplication** | Disables log deduplication filter protection to use Pytest Live Log feature. | `POWERTOOLS_LOG_DEDUPLICATION_DISABLED` | `false` |
435-
| **TZ** | Sets timezone when using Logger, e.g., `US/Eastern`. Timezone is defaulted to UTC when `TZ` is not set | `TZ` | `None` (UTC) |
440+
| Setting | Description | Environment variable | Default |
441+
| ------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- | ------------ |
442+
| **Event Logging** | Whether to log the incoming event. | `POWERTOOLS_LOGGER_LOG_EVENT` | `false` |
443+
| **Debug Sample Rate** | Sets the debug log sampling. | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` |
444+
| **Disable Deduplication** | Disables log deduplication filter protection to use Pytest Live Log feature. | `POWERTOOLS_LOG_DEDUPLICATION_DISABLED` | `false` |
445+
| **TZ** | Sets timezone when using Logger, e.g., `US/Eastern`. Timezone is defaulted to UTC when `TZ` is not set | `TZ` | `None` (UTC) |
436446

437447
[`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.
438448

@@ -529,7 +539,7 @@ If you prefer configuring it separately, or you'd want to bring this JSON Format
529539
| **`json_default`** | function to coerce unserializable values, when no custom serializer/deserializer is set | `str` |
530540
| **`datefmt`** | string directives (strftime) to format log timestamp | `%Y-%m-%d %H:%M:%S,%F%z`, where `%F` is a custom ms directive |
531541
| **`use_datetime_directive`** | format the `datefmt` timestamps using `datetime`, not `time` (also supports the custom `%F` directive for milliseconds) | `False` |
532-
| **`utc`** | enforce logging timestamp to UTC (ignore `TZ` environment variable) | `False` |
542+
| **`utc`** | enforce logging timestamp to UTC (ignore `TZ` environment variable) | `False` |
533543
| **`log_record_order`** | set order of log keys when logging | `["level", "location", "message", "timestamp"]` |
534544
| **`kwargs`** | key-value to be included in log messages | `None` |
535545

0 commit comments

Comments
 (0)