Skip to content

style(docs): apply standardized formatting #1462

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 2 commits into from
May 12, 2023
Merged

style(docs): apply standardized formatting #1462

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f26b201
style(docs): apply standardized formatting
dreamorosi May 11, 2023
663a1ce
style(docs): apply standardized formatting
dreamorosi May 12, 2023
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
47 changes: 24 additions & 23 deletions docs/core/logger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,12 @@ The library requires two settings. You can set them as environment variables, or

These settings will be used across all logs emitted:

| Setting | Description | Environment variable | Default Value | Allowed Values | Example Value | Constructor parameter |
|-------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------|---------------------|-------------------------------------------|--------------------|-----------------------|
| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `service_undefined` | Any string | `serverlessAirline`| `serviceName` |
| **Logging level** | Sets how verbose Logger should be, from the most verbose to the least verbose (no logs) | `LOG_LEVEL` | `info` |`DEBUG`, `INFO`, `WARN`, `ERROR`, `SILENT` | `ERROR` | `logLevel` |
| **Log incoming event** | Whether to log or not the incoming event when using the decorator or middleware | `POWERTOOLS_LOGGER_LOG_EVENT` | `false` | `true`, `false` | `false` | `logEvent` |
| **Debug log sampling** | Probability that a Lambda invocation will print all the log items regardless of the log level setting | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` | `0.0` to `1` | `0.5` | `sampleRateValue` |
| Setting | Description | Environment variable | Default Value | Allowed Values | Example Value | Constructor parameter |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------- | ------------------------------------------ | ------------------- | --------------------- |
| **Service name** | Sets the name of service of which the Lambda function is part of, that will be present across all log statements | `POWERTOOLS_SERVICE_NAME` | `service_undefined` | Any string | `serverlessAirline` | `serviceName` |
| **Logging level** | Sets how verbose Logger should be, from the most verbose to the least verbose (no logs) | `LOG_LEVEL` | `info` | `DEBUG`, `INFO`, `WARN`, `ERROR`, `SILENT` | `ERROR` | `logLevel` |
| **Log incoming event** | Whether to log or not the incoming event when using the decorator or middleware | `POWERTOOLS_LOGGER_LOG_EVENT` | `false` | `true`, `false` | `false` | `logEvent` |
| **Debug log sampling** | Probability that a Lambda invocation will print all the log items regardless of the log level setting | `POWERTOOLS_LOGGER_SAMPLE_RATE` | `0` | `0.0` to `1` | `0.5` | `sampleRateValue` |

#### Example using AWS Serverless Application Model (SAM)

Expand Down Expand Up @@ -80,7 +80,7 @@ These settings will be used across all logs emitted:
Your Logger will include the following keys to your structured logging (default log formatter):

| Key | Example | Note |
|-----------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **level**: `string` | `INFO` | Logging level set for the Lambda function's invocation |
| **message**: `string` | `Query performed to DynamoDB` | A descriptive, human-readable representation of this log item |
| **sampling_rate**: `float` | `0.1` | When enabled, it prints all the logs of a percentage of invocations, e.g. 10% |
Expand All @@ -98,21 +98,21 @@ You can enrich your structured logs with key Lambda context information in multi

This functionality will include the following keys in your structured logs:

Key | Example
------------------------------------------------- | ---------------------------------------------------------------------------------
**cold_start**: `bool` | `false`
**function_name** `string` | `shopping-cart-api-lambda-prod-eu-west-1`
**function_memory_size**: `number` | `128`
**function_arn**: `string` | `arn:aws:lambda:eu-west-1:123456789012:function:shopping-cart-api-lambda-prod-eu-west-1`
**function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
| Key | Example |
| ---------------------------------- | ---------------------------------------------------------------------------------------- |
| **cold_start**: `bool` | `false` |
| **function_name** `string` | `shopping-cart-api-lambda-prod-eu-west-1` |
| **function_memory_size**: `number` | `128` |
| **function_arn**: `string` | `arn:aws:lambda:eu-west-1:123456789012:function:shopping-cart-api-lambda-prod-eu-west-1` |
| **function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678` |

=== "Middy Middleware"

!!! tip "Using Middy for the first time?"
You can install Middy by running `npm i @middy/core`.
Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.

```typescript hl_lines="1-2 10-11"
```typescript hl_lines="1-2 13"
--8<-- "docs/snippets/logger/middy.ts"
```

Expand All @@ -126,7 +126,7 @@ Key | Example

=== "Manual"

```typescript hl_lines="7"
```typescript hl_lines="6"
--8<-- "docs/snippets/logger/manual.ts"
```

Expand Down Expand Up @@ -158,7 +158,7 @@ When debugging in non-production environments, you can instruct Logger to log th

=== "Middy Middleware"

```typescript hl_lines="11"
```typescript hl_lines="10"
--8<-- "docs/snippets/logger/eventMiddy.ts"
```

Expand All @@ -182,7 +182,7 @@ To remove the keys you added, you can use the `removeKeys` method.

=== "handler.ts"

```typescript hl_lines="5-13 17-25 30"
```typescript hl_lines="5-13 17-25 32"
--8<-- "docs/snippets/logger/appendKeys.ts"
```
=== "Example CloudWatch Logs excerpt"
Expand Down Expand Up @@ -229,7 +229,7 @@ If you want to make sure that persistent attributes added **inside the handler f

=== "Middy Middleware"

```typescript hl_lines="27"
```typescript hl_lines="30"
--8<-- "docs/snippets/logger/clearStateMiddy.ts"
```

Expand Down Expand Up @@ -294,7 +294,7 @@ You can append additional data to a single log item by passing objects as additi

=== "handler.ts"

```typescript hl_lines="14 18-20 24 32"
```typescript hl_lines="16-18 23-25 37"
--8<-- "docs/snippets/logger/extraData.ts"
```
=== "Example CloudWatch Logs excerpt"
Expand Down Expand Up @@ -347,7 +347,7 @@ The error will be logged with default key name `error`, but you can also pass yo

=== "handler.ts"

```typescript hl_lines="11 18"
```typescript hl_lines="13 20-22"
--8<-- "docs/snippets/logger/logError.ts"
```

Expand Down Expand Up @@ -396,7 +396,7 @@ The `createChild` method allows you to create a child instance of the Logger, wh

=== "handler.ts"

```typescript hl_lines="9-11 18-19"
```typescript hl_lines="16-18"
--8<-- "docs/snippets/logger/createChild.ts"
```

Expand Down Expand Up @@ -447,7 +447,8 @@ For example, by setting the "sample rate" to `0.5`, roughly 50% of your lambda i

However, it might still be useful to print all the logs (including debug ones) of a very small percentage of invocations to have a better understanding of the behaviour of your code in production even when there are no errors.

Sampling decision happens at the Logger initialization. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
**Sampling decision happens at the Logger initialization**. This means sampling may happen significantly more or less than depending on your traffic patterns, for example a steady low number of invocations and thus few cold starts.
If you want to reset the sampling decision and refresh it for each invocation, you can call the `logger.refreshSampleRateCalculation()` method at the beginning or end of your handler.

=== "handler.ts"

Expand Down
42 changes: 21 additions & 21 deletions docs/core/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ The `Metrics` utility must always be instantiated outside of the Lambda handler.

=== "handler.ts"

```typescript hl_lines="1 3"
```typescript hl_lines="1 3-6"
--8<-- "docs/snippets/metrics/basicUsage.ts"
```

Expand All @@ -63,10 +63,10 @@ The library requires two settings. You can set them as environment variables, or

These settings will be used across all metrics emitted:

| Setting | Description | Environment variable | Default | Allowed Values | Example | Constructor parameter |
|----------------------|-----------------------------------------------------------------|-------------------------------|--------------------|----------------|--------------------|-----------------------|
| **Service** | Optionally, sets **service** metric dimension across all metrics| `POWERTOOLS_SERVICE_NAME` | `service_undefined`| Any string | `serverlessAirline`| `serviceName` |
| **Metric namespace** | Logical container where all metrics will be placed | `POWERTOOLS_METRICS_NAMESPACE`| `default_namespace`| Any string | `serverlessAirline`| `default_namespace` |
| Setting | Description | Environment variable | Default | Allowed Values | Example | Constructor parameter |
| -------------------- | ---------------------------------------------------------------- | ------------------------------ | ------------------- | -------------- | ------------------- | --------------------- |
| **Service** | Optionally, sets **service** metric dimension across all metrics | `POWERTOOLS_SERVICE_NAME` | `service_undefined` | Any string | `serverlessAirline` | `serviceName` |
| **Metric namespace** | Logical container where all metrics will be placed | `POWERTOOLS_METRICS_NAMESPACE` | `default_namespace` | Any string | `serverlessAirline` | `default_namespace` |

!!! tip
Use your application name or main service as the metric namespace to easily group all metrics
Expand Down Expand Up @@ -103,13 +103,13 @@ You can create metrics using the `addMetric` method, and you can create dimensio

=== "Metrics"

```typescript hl_lines="6"
```typescript hl_lines="12"
--8<-- "docs/snippets/metrics/createMetrics.ts"
```

=== "Metrics with custom dimensions"

```typescript hl_lines="6-7"
```typescript hl_lines="12-13"
--8<-- "docs/snippets/metrics/customDimensions.ts"
```

Expand All @@ -131,7 +131,7 @@ You can create [high-resolution metrics](https://aws.amazon.com/about-aws/whats-

=== "Metrics with high resolution"

```typescript hl_lines="6"
```typescript hl_lines="4 20"
--8<-- "docs/snippets/metrics/addHighResolutionMetric.ts"
```

Expand All @@ -144,7 +144,7 @@ You can call `addMetric()` with the same name multiple times. The values will be

=== "addMetric() with the same name"

```typescript hl_lines="7 9"
```typescript hl_lines="12 14"
--8<-- "docs/snippets/metrics/multiValueMetrics.ts"
```
=== "Example CloudWatch Logs excerpt"
Expand Down Expand Up @@ -199,19 +199,19 @@ You can add default dimensions to your metrics by passing them as parameters in
You can install Middy by running `npm i @middy/core`.
Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.

```typescript hl_lines="1-2 11 13"
```typescript hl_lines="24-26"
--8<-- "docs/snippets/metrics/defaultDimensionsMiddy.ts"
```

=== "setDefaultDimensions method"

```typescript hl_lines="4"
```typescript hl_lines="7"
--8<-- "docs/snippets/metrics/setDefaultDimensions.ts"
```

=== "with logMetrics decorator"

```typescript hl_lines="9"
```typescript hl_lines="12"
--8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts"
```

Expand Down Expand Up @@ -245,7 +245,7 @@ See below an example of how to automatically flush metrics with the Middy-compat

=== "handler.ts"

```typescript hl_lines="1-2 7 10-11"
```typescript hl_lines="20"
--8<-- "docs/snippets/metrics/middy.ts"
```

Expand Down Expand Up @@ -285,7 +285,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h

=== "handler.ts"

```typescript hl_lines="8"
```typescript hl_lines="10"
--8<-- "docs/snippets/metrics/decorator.ts"
```

Expand Down Expand Up @@ -326,7 +326,7 @@ You can manually flush the metrics with `publishStoredMetrics` as follows:

=== "handler.ts"

```typescript hl_lines="7"
```typescript hl_lines="13"
--8<-- "docs/snippets/metrics/manual.ts"
```

Expand Down Expand Up @@ -364,7 +364,7 @@ If you want to ensure that at least one metric is emitted before you flush them,

=== "handler.ts"

```typescript hl_lines="11"
```typescript hl_lines="21"
--8<-- "docs/snippets/metrics/throwOnEmptyMetrics.ts"
```

Expand All @@ -374,13 +374,13 @@ You can optionally capture cold start metrics with the `logMetrics` middleware o

=== "Middy Middleware"

```typescript hl_lines="11"
```typescript hl_lines="21"
--8<-- "docs/snippets/metrics/captureColdStartMetricMiddy.ts"
```

=== "logMetrics decorator"

```typescript hl_lines="8"
```typescript hl_lines="10"
--8<-- "docs/snippets/metrics/captureColdStartMetricDecorator.ts"
```

Expand All @@ -404,7 +404,7 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad

=== "handler.ts"

```typescript hl_lines="8"
```typescript hl_lines="18"
--8<-- "docs/snippets/metrics/addMetadata.ts"
```

Expand Down Expand Up @@ -456,13 +456,13 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `singleMetr

=== "Middy Middleware"

```typescript hl_lines="11 13-14"
```typescript hl_lines="21 23-24"
--8<-- "docs/snippets/metrics/singleMetricDifferentDimsMiddy.ts"
```

=== "logMetrics decorator"

```typescript hl_lines="14 16-17"
```typescript hl_lines="16 18-19"
--8<-- "docs/snippets/metrics/singleMetricDifferentDimsDecorator.ts"
```

Expand Down
Loading