Merge pull request #130 from heitorlessa/docs/readability-improvements

heitorlessa · web-flow · commit d0aaad53fe86 · 2020-08-23T20:05:22.000+02:00
docs: readability improvements
diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx
@@ -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`.
 
@@ -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
@@ -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
 
@@ -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.
diff --git a/docs/content/core/metrics.mdx b/docs/content/core/metrics.mdx
@@ -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**
 
@@ -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
@@ -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
 
diff --git a/docs/content/core/tracer.mdx b/docs/content/core/tracer.mdx
@@ -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)
@@ -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
@@ -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"
@@ -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
@@ -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>.
diff --git a/docs/content/index.mdx b/docs/content/index.mdx
@@ -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)
@@ -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._
