Skip to content

Commit 430d485

Browse files
authored
style(docs): apply standardized formatting (#1462)
1 parent 455261a commit 430d485

File tree

93 files changed

+662
-401
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

93 files changed

+662
-401
lines changed

docs/core/logger.md

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,12 @@ The library requires two settings. You can set them as environment variables, or
4646

4747
These settings will be used across all logs emitted:
4848

49-
| Setting | Description | Environment variable | Default Value | Allowed Values | Example Value | Constructor parameter |
50-
|-------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------|---------------------|-------------------------------------------|--------------------|-----------------------|
51-
| **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` |
52-
| **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` |
53-
| **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` |
54-
| **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` |
49+
| Setting | Description | Environment variable | Default Value | Allowed Values | Example Value | Constructor parameter |
50+
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------- | ------------------------------------------ | ------------------- | --------------------- |
51+
| **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` |
52+
| **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` |
53+
| **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` |
54+
| **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` |
5555

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

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

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

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

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

109109
=== "Middy Middleware"
110110

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

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

@@ -126,7 +126,7 @@ Key | Example
126126

127127
=== "Manual"
128128

129-
```typescript hl_lines="7"
129+
```typescript hl_lines="6"
130130
--8<-- "docs/snippets/logger/manual.ts"
131131
```
132132

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

159159
=== "Middy Middleware"
160160

161-
```typescript hl_lines="11"
161+
```typescript hl_lines="10"
162162
--8<-- "docs/snippets/logger/eventMiddy.ts"
163163
```
164164

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

183183
=== "handler.ts"
184184

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

230230
=== "Middy Middleware"
231231

232-
```typescript hl_lines="27"
232+
```typescript hl_lines="30"
233233
--8<-- "docs/snippets/logger/clearStateMiddy.ts"
234234
```
235235

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

295295
=== "handler.ts"
296296

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

348348
=== "handler.ts"
349349

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

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

397397
=== "handler.ts"
398398

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

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

448448
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.
449449

450-
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.
450+
**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.
451+
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.
451452

452453
=== "handler.ts"
453454

docs/core/metrics.md

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ The `Metrics` utility must always be instantiated outside of the Lambda handler.
5353

5454
=== "handler.ts"
5555

56-
```typescript hl_lines="1 3"
56+
```typescript hl_lines="1 3-6"
5757
--8<-- "docs/snippets/metrics/basicUsage.ts"
5858
```
5959

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

6464
These settings will be used across all metrics emitted:
6565

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

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

104104
=== "Metrics"
105105

106-
```typescript hl_lines="6"
106+
```typescript hl_lines="12"
107107
--8<-- "docs/snippets/metrics/createMetrics.ts"
108108
```
109109

110110
=== "Metrics with custom dimensions"
111111

112-
```typescript hl_lines="6-7"
112+
```typescript hl_lines="12-13"
113113
--8<-- "docs/snippets/metrics/customDimensions.ts"
114114
```
115115

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

132132
=== "Metrics with high resolution"
133133

134-
```typescript hl_lines="6"
134+
```typescript hl_lines="4 20"
135135
--8<-- "docs/snippets/metrics/addHighResolutionMetric.ts"
136136
```
137137

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

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

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

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

206206
=== "setDefaultDimensions method"
207207

208-
```typescript hl_lines="4"
208+
```typescript hl_lines="7"
209209
--8<-- "docs/snippets/metrics/setDefaultDimensions.ts"
210210
```
211211

212212
=== "with logMetrics decorator"
213213

214-
```typescript hl_lines="9"
214+
```typescript hl_lines="12"
215215
--8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts"
216216
```
217217

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

246246
=== "handler.ts"
247247

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

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

286286
=== "handler.ts"
287287

288-
```typescript hl_lines="8"
288+
```typescript hl_lines="10"
289289
--8<-- "docs/snippets/metrics/decorator.ts"
290290
```
291291

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

327327
=== "handler.ts"
328328

329-
```typescript hl_lines="7"
329+
```typescript hl_lines="13"
330330
--8<-- "docs/snippets/metrics/manual.ts"
331331
```
332332

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

365365
=== "handler.ts"
366366

367-
```typescript hl_lines="11"
367+
```typescript hl_lines="21"
368368
--8<-- "docs/snippets/metrics/throwOnEmptyMetrics.ts"
369369
```
370370

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

375375
=== "Middy Middleware"
376376

377-
```typescript hl_lines="11"
377+
```typescript hl_lines="21"
378378
--8<-- "docs/snippets/metrics/captureColdStartMetricMiddy.ts"
379379
```
380380

381381
=== "logMetrics decorator"
382382

383-
```typescript hl_lines="8"
383+
```typescript hl_lines="10"
384384
--8<-- "docs/snippets/metrics/captureColdStartMetricDecorator.ts"
385385
```
386386

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

405405
=== "handler.ts"
406406

407-
```typescript hl_lines="8"
407+
```typescript hl_lines="18"
408408
--8<-- "docs/snippets/metrics/addMetadata.ts"
409409
```
410410

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

457457
=== "Middy Middleware"
458458

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

463463
=== "logMetrics decorator"
464464

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

0 commit comments

Comments
 (0)