Added documentation skeleton

Author: dreamorosi

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format for changes and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [Unreleased]
+
+## [0.1.0] - 2019-11-15
+### Added
+- Public beta release

docs/Dockerfile

@@ -0,0 +1,2 @@
+FROM squidfunk/mkdocs-material
+RUN pip install mkdocs-git-revision-date-plugin

docs/changelog.md

@@ -0,0 +1,2 @@
+[comment]: <> (Includes Changelog content entire file as a snippet)
+--8<-- "CHANGELOG.md"

docs/core/logger.md

@@ -0,0 +1,68 @@
+---
+title: Logger
+description: Core utility
+---
+
+Logger provides an opinionated logger with output structured as JSON.
+
+## Key features
+
+* Capture key fields from Lambda context, cold start and structures logging output as JSON
+* Log Lambda event when instructed (disabled by default)
+* Log sampling enables DEBUG log level for a percentage of requests (disabled by default)
+* Append additional keys to structured log at any point in time
+
+## Getting started
+
+Logger requires two settings:
+
+Setting | Description | Environment variable | Constructor parameter
+------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
+**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`
+
+> Example using AWS Serverless Application Model (SAM)
+
+=== "template.yaml"
+	```yaml hl_lines="9 10"
+    Resources:
+      HelloWorldFunction:
+        Type: AWS::Serverless::Function
+        Properties:
+          Runtime: nodejs14.x
+          Environment:
+            Variables:
+              LOG_LEVEL: INFO
+              POWERTOOLS_SERVICE_NAME: example
+	```
+=== "app.py"
+	```typescript hl_lines="3 4"
+	import { Logger } from '@aws-lambda-powertools/logger';
+	
+	const logger = Logger(); // Sets service via env var
+	// OR const logger = Logger({ service: 'example' });
+	```
+
+### Standard structured keys
+
+Your Logger will include the following keys to your structured logging:
+
+Key | Example | Note
+------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
+**level**: `str` | `INFO` | Logging level
+**location**: `str` | `collect.handler:1` | Source code location where statement was executed
+**message**: `Any` | `Collecting payment` | Unserializable JSON values are casted as `str`
+**timestamp**: `str` | `2021-05-03 10:20:19,650+0200` | Timestamp with milliseconds, by default uses local timezone
+**service**: `str` | `payment` | Service name defined, by default `service_undefined`
+**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
+**sampling_rate**: `float` |  `0.1` | When enabled, it shows sampling rate in percentage e.g. 10%
+**exception_name**: `str` | `ValueError` | When `logger.exception` is used and there is an exception
+**exception**: `str` | `Traceback (most recent call last)..` | When `logger.exception` is used and there is an exception
+
+:construction: WIP :construction:
+
+**How do I aggregate and search Powertools logs across accounts?**
+
+As of now, ElasticSearch (ELK) or 3rd party solutions are best suited to this task.
+
+Please see this discussion for more information: https://github.com/awslabs/aws-lambda-powertools-python/issues/460

docs/core/metrics.md

@@ -0,0 +1,59 @@
+---
+title: Metrics
+description: Core utility
+---
+
+Metrics creates custom metrics asynchronously by logging metrics to standard output following [Amazon CloudWatch Embedded Metric Format (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html).
+
+These metrics can be visualized through [Amazon CloudWatch Console](https://console.aws.amazon.com/cloudwatch/).
+
+## Key features
+
+* Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
+* Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)
+* Metrics are created asynchronously by CloudWatch service, no custom stacks needed
+* Context manager to create a one off metric with a different dimension
+
+## Terminologies
+
+If you're new to Amazon CloudWatch, there are two terminologies you must be aware of before using this utility:
+
+* **Namespace**. It's the highest level container that will group multiple metrics from multiple services for a given application, for example `ServerlessEcommerce`.
+* **Dimensions**. Metrics metadata in key-value format. They help you slice and dice metrics visualization, for example `ColdStart` metric by Payment `service`.
+
+<figure>
+  <img src="../../media/metrics_terminology.png" />
+  <figcaption>Metric terminology, visually explained</figcaption>
+</figure>
+
+
+## Getting started
+
+Metric has two global settings that will be used across all metrics emitted:
+
+Setting | Description | Environment variable | Constructor parameter
+------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
+**Metric namespace** | Logical container where all metrics will be placed e.g. `ServerlessAirline` |  `POWERTOOLS_METRICS_NAMESPACE` | `namespace`
+**Service** | Optionally, sets **service** metric dimension across all metrics e.g. `payment` | `POWERTOOLS_SERVICE_NAME` | `service`
+
+!!! tip "Use your application or main service as the metric namespace to easily group all metrics"
+
+> Example using AWS Serverless Application Model (SAM)
+
+=== "template.yml"
+
+    ```yaml hl_lines="9 10"
+    Resources:
+      HelloWorldFunction:
+        Type: AWS::Serverless::Function
+        Properties:
+          Runtime: nodejs14.x
+          Environment:
+          Variables:
+            POWERTOOLS_SERVICE_NAME: payment
+            POWERTOOLS_METRICS_NAMESPACE: ServerlessAirline
+    ```
+
+:construction: WIP :construction:
+
+!!! tip "For more elaborate assertions and comparisons, check out [our functional testing for Metrics utility](https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/tests/functional/test_metrics.py)"

docs/core/tracer.md

@@ -0,0 +1,114 @@
+---
+title: Tracer
+description: Core utility
+---
+
+Tracer is an opinionated thin wrapper for [AWS X-Ray Python SDK](https://github.com/aws/aws-xray-sdk-node/).
+
+![Tracer showcase](../media/tracer_utility_showcase.png)
+
+## Key features
+
+* Auto capture cold start as annotation, and responses or full exceptions as metadata
+* Run functions locally with SAM CLI without code change to disable tracing
+* Explicitly disable tracing via env var `POWERTOOLS_TRACE_ENABLED="false"`
+* Support tracing async methods, generators, and context managers
+* Auto patch supported modules by AWS X-Ray
+
+## Getting started
+
+### Permissions
+
+Before your use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray.
+
+> Example using AWS Serverless Application Model (SAM)
+
+=== "template.yml"
+    ```yaml hl_lines="6 9"
+    Resources:
+      HelloWorldFunction:
+        Type: AWS::Serverless::Function
+        Properties:
+          Runtime: nodejs14.x
+          Tracing: Active
+          Environment:
+            Variables:
+              POWERTOOLS_SERVICE_NAME: example
+    ```
+
+### Lambda handler
+
+You can quickly start by importing the `Tracer` class, initialize it outside the Lambda handler, and use `capture_lambda_handler` decorator.
+
+=== "app.py"
+	```typescript hl_lines="1 3 6"
+	import { Tracer } from '@aws-lambda-powertools/tracer';
+
+	const tracer = Tracer(); // Sets service via env var
+	// OR tracer = Tracer({ service: 'example' });
+
+	@tracer.capture_lambda_handler
+	const handler = (event, context) => {
+		const chargeId = event.chargeId;
+		const payment = collectPayment(chargeId);
+		...
+	}
+	```
+
+When using this `capture_lambda_handler` decorator, Tracer performs these additional tasks to ease operations:
+
+* Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead
+* Captures any response, or full exceptions generated by the handler, and include as tracing metadata
+
+### Annotations & Metadata
+
+**Annotations** are key-values associated with traces and indexed by AWS X-Ray. You can use them to filter traces and to create [Trace Groups](https://aws.amazon.com/about-aws/whats-new/2018/11/aws-xray-adds-the-ability-to-group-traces/) to slice and dice your transactions.
+
+**Metadata** are key-values also associated with traces but not indexed by AWS X-Ray. You can use them to add additional context for an operation using any native object.
+
+=== "Annotations"
+	You can add annotations using `put_annotation` method.
+
+    ```typescript hl_lines="7"
+		import { Tracer } from '@aws-lambda-powertools/tracer';
+
+    const tracer = Tracer()
+
+    @tracer.capture_lambda_handler
+    const handler = (event, context) => {
+			...
+			const res = some_logic();
+			tracer.putAnnotation(key='payment_response', value=res);
+		}
+    ```
+=== "Metadata"
+	You can add metadata using `put_metadata` method.
+
+    ```typescript hl_lines="9"
+    import { Tracer } from '@aws-lambda-powertools/tracer';
+
+    const tracer = Tracer()
+
+    @tracer.capture_lambda_handler
+    const handler = (event, context) => {
+			...
+			const res = some_logic();
+			tracer.putMetadata(key='payment_response', value=res);
+		}
+    ```
+
+:construction: WIP :construction:
+
+## Testing your code
+
+Powertools should be able to detect that it's not running inside a Lambda execution environment and disable tracing for you. If that doesn't work you can also disable it explicitly using `POWERTOOLS_TRACE_ENABLED` environment variable.
+
+```bash
+POWERTOOLS_TRACE_ENABLED=0 npm run test
+```
+
+## Tips
+
+* Use annotations on key operations to slice and dice traces, create unique views, and create metrics from it via Trace Groups
+* Use a namespace when adding metadata to group data more easily
+* Annotations and metadata are added to the current subsegment opened. If you want them in a specific subsegment, use a [context manager](https://github.com/aws/aws-xray-sdk-python/#start-a-custom-segmentsubsegment) via the escape hatch mechanism

docs/diagram_src/.gitignore

@@ -0,0 +1,49 @@
+---
+title: Homepage
+description: AWS Lambda Powertools Typescript
+---
+
+A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more.
+
+!!! tip "Looking for a quick read through how the core features are used?"
+  	Check out [this detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-lambda-powertools/) with a practical example.
+
+## Tenets
+
+This project separates core utilities that will be available in other runtimes vs general utilities that might not be available across all runtimes.
+
+* **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.
+
+## Install
+
+:construction:
+
+## Features
+
+| Utility | Description
+| ------------------------------------------------- | ---------------------------------------------------------------------------------
+[Tracing](./core/tracer.md) | Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
+[Logger](./core/logger.md) | Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
+[Metrics](./core/metrics.md) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
+
+## Environment variables
+
+!!! info
+    **Explicit parameters take precedence over environment variables.**
+
+| Environment variable | Description | Utility | Default |
+| ------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- |
+| **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `"service_undefined"` |
+| **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `None` |
+| **POWERTOOLS_TRACE_DISABLED** | Disables tracing | [Tracing](./core/tracer) | `false` |
+| **POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracing](./core/tracer) | `true` |
+| **POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracing](./core/tracer) | `true` |
+| **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logging](./core/logger) | `false` |
+| **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logging](./core/logger) | `0` |
+| **POWERTOOLS_LOG_DEDUPLICATION_DISABLED** | Disables log deduplication filter protection to use Pytest Live Log feature | [Logging](./core/logger) | `false` |
+| **LOG_LEVEL** | Sets logging level | [Logging](./core/logger) | `INFO` |