Skip to content

docs: readability improvements #130

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.

Sign up for GitHub

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 8 commits into from
Aug 23, 2020
Merged

docs: readability improvements #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
64f7aa8
docs: move concurrent asynchronous under escape hatch
heitorlessa Aug 23, 2020
3faf915
docs: create Patching modules section; cleanup response wording
heitorlessa Aug 23, 2020
10cb3a9
docs: make sensitive info more explicit with an example
heitorlessa Aug 23, 2020
44db087
docs: fix typos, log_event & sampling wording
heitorlessa Aug 23, 2020
705371e
docs: subtle rewording for better clarity
heitorlessa Aug 23, 2020
ac0aba9
docs: add blog post, and quick example
heitorlessa Aug 23, 2020
e89fbea
docs: use table for clarity
heitorlessa Aug 23, 2020
efd38d8
docs: move tenets; remove extra space
heitorlessa Aug 23, 2020
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
37 changes: 19 additions & 18 deletions docs/content/core/logger.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Key | Type | Example | Description
**sampling_rate** | int | 0.1 | Debug logging sampling rate in percentage e.g. 1% in this case
**message** | any | "Collecting payment" | Log statement value. Unserializable JSON values will be casted to string

## Capturing context Lambda info
## Capturing Lambda context info

You can enrich your structured logs with key Lambda context information via `inject_lambda_context`.

Expand All @@ -79,22 +79,6 @@ def handler(event, context):
...
```

You can also explicitly log any incoming event using `log_event` param or via `POWERTOOLS_LOGGER_LOG_EVENT` env var.

<Note type="warning">
This is disabled by default to prevent sensitive info being logged.
</Note><br/>

```python:title=log_handler_event.py
from aws_lambda_powertools import Logger

logger = Logger()

@logger.inject_lambda_context(log_event=True) # highlight-start
def handler(event, context):
...
```

When used, this will include the following keys:

Key | Type | Example
Expand Down Expand Up @@ -145,6 +129,23 @@ Key | Type | Example
}
```
</details>
<br/>

You can also explicitly log any incoming event using `log_event` param or via `POWERTOOLS_LOGGER_LOG_EVENT` env var.

<Note type="warning">
This is disabled by default to prevent sensitive info being logged.
</Note><br/>

```python:title=log_handler_event.py
from aws_lambda_powertools import Logger

logger = Logger()

@logger.inject_lambda_context(log_event=True) # highlight-line
def handler(event, context):
...
```

## Appending additional keys

Expand Down Expand Up @@ -222,7 +223,7 @@ If you ever forget to use `child` param, we will return an existing `Logger` wit

You can dynamically set a percentage of your logs to **DEBUG** level using `sample_rate` param or via env var `POWERTOOLS_LOGGER_SAMPLE_RATE`.

This happens on an entire request basis, and <strong>DEBUG</strong> level is set at the constructor. That means, concurrent requests or infrequent invocations are more likely to occur as [new Lambda execution contexts are created](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html), not reused.
Sampling calculation happens at the Logger class initialization. This means, when configured it, sampling it's more likely to happen during concurrent requests, or infrequent invocations as [new Lambda execution contexts are created](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html), not reused.

<Note type="info">
If you want this logic to happen on every invocation regardless whether Lambda reuses the execution environment or not, then create your Logger inside your Lambda handler.
Expand Down
10 changes: 7 additions & 3 deletions docs/content/core/metrics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ description: Core utility

import Note from "../../src/components/Note"

Metrics creates custom metrics asynchronously via logging metrics to standard output following Amazon CloudWatch Embedded Metric Format (EMF).
Metrics creates custom metrics asynchronously by logging metrics to standard output following Amazon CloudWatch Embedded Metric Format (EMF).

These metrics can be visualized through [Amazon CloudWatch Console](https://console.aws.amazon.com/cloudwatch/).

**Key features**

Expand All @@ -32,7 +34,9 @@ Resources:
```

We recommend you use your application or main service as a metric namespace.
You can explicitly set a namespace name via `namespace` param or via `POWERTOOLS_METRICS_NAMESPACE` env var. This sets **namespace** key that will be used for all metrics.
You can explicitly set a namespace name via `namespace` param or via `POWERTOOLS_METRICS_NAMESPACE` env var.

This sets **namespace** key that will be used for all metrics.
You can also pass a service name via `service` param or `POWERTOOLS_SERVICE_NAME` env var. This will create a dimension with the service name.

```python:title=app.py
Expand Down Expand Up @@ -67,7 +71,7 @@ metrics.add_metric(name="SuccessfulBooking", unit=MetricUnit.Count, value=1)

`MetricUnit` enum facilitate finding a supported metric unit by CloudWatch. Alternatively, you can pass the value as a string if you already know them e.g. "Count".

CloudWatch EMF supports a max of 100 metrics. Metrics will automatically flush all metrics when adding the 100th metric, where subsequent metrics will be aggregated into a new EMF object.
CloudWatch EMF supports a max of 100 metrics. Metrics utility will flush all metrics when adding the 100th metric while subsequent metrics will be aggregated into a new EMF object, for your convenience.

## Creating a metric with a different dimension

Expand Down
38 changes: 29 additions & 9 deletions docs/content/core/tracer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,6 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray Python SDK](https://github.
* Support tracing async methods, generators, and context managers
* Auto patch supported modules, or a tuple of explicit modules supported by AWS X-Ray

<Note type="warning">
<strong>Returning sensitive information from your Lambda handler or functions, where Tracer is used?</strong>
<br/><br/>
You can disable Tracer from capturing their responses as tracing metadata with <strong><code>capture_response=False</code></strong> parameter in both capture_lambda_handler and capture_method decorators.
</Note><br/>

## Initialization

Your AWS Lambda function must have permission to send traces to AWS X-Ray - Here is an example using AWS Serverless Application Model (SAM)
Expand Down Expand Up @@ -58,7 +52,7 @@ You can trace your Lambda function handler via `capture_lambda_handler`.
When using this decorator, Tracer performs these additional tasks to ease operations:

* Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
* Adds any response, or full exceptions generated by the handler as metadata
* Captures any response, or full exceptions generated by the handler, and include as tracing metadata

```python:title=lambda_handler.py
from aws_lambda_powertools import Tracer
Expand All @@ -69,7 +63,17 @@ def handler(event, context):
charge_id = event.get('charge_id')
payment = collect_payment(charge_id)
...
```

<Note type="warning">
<strong>Returning sensitive information from your Lambda handler or functions, where Tracer is used?</strong>
<br/><br/>
You can disable Tracer from capturing their responses as tracing metadata with <strong><code>capture_response=False</code></strong> parameter in both capture_lambda_handler and capture_method decorators.
</Note><br/>

```python:title=do_not_capture_response_as_metadata.py
# Disables Tracer from capturing response and adding as metadata
# Useful when dealing with sensitive data
@tracer.capture_lambda_handler(capture_response=False) # highlight-line
def handler(event, context):
return "sensitive_information"
Expand Down Expand Up @@ -170,7 +174,23 @@ def handler(evt, ctx): # highlight-line
another_result = list(collect_payment_gen())
```

## Tracing aiohttp requests
## Patching modules

Tracer automatically patches all [supported libraries by X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-patching.html) during initialization, by default. Underneath, AWS X-Ray SDK checks whether a supported library has been imported before patching.

If you're looking to shave a few microseconds, or milliseconds depending on your function memory configuration, you can patch specific modules using `patch_modules` param:

```python:title=app.py
import boto3
import requests

from aws_lambda_powertools import Tracer

modules_to_be_patched = ["boto3", "requests"]
tracer = Tracer(patch_modules=modules_to_be_patched) # highlight-line
```

### Tracing aiohttp requests

<Note type="info">
This snippet assumes you have <strong>aiohttp</strong> as a dependency
Expand Down Expand Up @@ -199,7 +219,7 @@ You can use `tracer.provider` attribute to access all methods provided by AWS X-

This is useful when you need a feature available in X-Ray that is not available in the Tracer utility, for example [thread-safe](https://github.com/aws/aws-xray-sdk-python/#user-content-trace-threadpoolexecutor), or [context managers](https://github.com/aws/aws-xray-sdk-python/#user-content-start-a-custom-segmentsubsegment).

## Concurrent asynchronous functions
### Concurrent asynchronous functions

<Note type="info">
<a href="https://github.com/aws/aws-xray-sdk-python/issues/164">As of now, X-Ray SDK will raise an exception when async functions are run and traced concurrently</a>.
Expand Down
50 changes: 32 additions & 18 deletions docs/content/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,44 +3,47 @@ title: Homepage
description: AWS Lambda Powertools Python
---

import Note from "../src/components/Note"

Powertools is a suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.

<Note type="info">
<strong>Looking for a quick run through of the core utilities?</strong><br/><br/>
Check out <a href="https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-lambda-powertools/">this detailed blog post</a> with a practical example.
</Note>

## Install

Powertools is available in PyPi. You can use your favourite dependency management tool to install it

* [poetry](https://python-poetry.org/): `poetry add aws-lambda-powertools`
* [pip](https://pip.pypa.io/en/latest/index.html): `pip install aws-lambda-powertools`

## Features

* [Tracing](./core/tracer) - Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
* [Logging](./core/logger) - Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
* [Metrics](./core/metrics) - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
* [Bring your own middleware](./utilities/middleware_factory) - Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
* [Parameters utility](./utilities/parameters) - Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time

## Tenets
**Quick hello world example using SAM CLI**
```bash:title=hello_world.sh
sam init --location https://github.com/aws-samples/cookiecutter-aws-sam-python
```

* **AWS Lambda only** – We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
* **Eases the adoption of best practices** – The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
* **Keep it lean** – Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
* **We strive for backwards compatibility** – New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
* **We work backwards from the community** – We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
* **Idiomatic** – Utilities follow programming language idioms and language-specific best practices.
## Features

_`*` Core utilities are Tracer, Logger and Metrics. Optional utilities may vary across languages._
Utility | Description
------------------------------------------------- | ---------------------------------------------------------------------------------
[Tracing](./core/tracer) | Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
[Logging](./core/logger) | Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
[Metrics](./core/metrics) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
[Bring your own middleware](.//utilities/middleware_factory) | Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
[Parameters utility](./utilities/parameters) | Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time

## Environment variables

**Environment variables** used across suite of utilities.

Environment variable | Description | Utility
------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------
**POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | all
**POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All
**POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics)
**POWERTOOLS_TRACE_DISABLED** | Disables tracing | [Tracing](./core/tracer)
**POWERTOOLS_TRACE_MIDDLEWARES** | Creates sub-segment for each custom middleware | [middleware_factory](./utilities/middleware_factory)
**POWERTOOLS_TRACE_MIDDLEWARES** | Creates sub-segment for each custom middleware | [Middleware factory](./utilities/middleware_factory)
**POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logging](./core/logger)
**POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logging](./core/logger)
**LOG_LEVEL** | Sets logging level | [Logging](./core/logger)
Expand All @@ -54,3 +57,14 @@ from aws_lambda_powertools.logging.logger import set_package_logger

set_package_logger()
```

## Tenets

* **AWS Lambda only** – We optimise for AWS Lambda function environments and supported runtimes only. Utilities might work with web frameworks and non-Lambda environments, though they are not officially supported.
* **Eases the adoption of best practices** – The main priority of the utilities is to facilitate best practices adoption, as defined in the AWS Well-Architected Serverless Lens; all other functionality is optional.
* **Keep it lean** – Additional dependencies are carefully considered for security and ease of maintenance, and prevent negatively impacting startup time.
* **We strive for backwards compatibility** – New features and changes should keep backwards compatibility. If a breaking change cannot be avoided, the deprecation and migration process should be clearly defined.
* **We work backwards from the community** – We aim to strike a balance of what would work best for 80% of customers. Emerging practices are considered and discussed via Requests for Comment (RFCs)
* **Idiomatic** – Utilities follow programming language idioms and language-specific best practices.

_`*` Core utilities are Tracer, Logger and Metrics. Optional utilities may vary across languages._