Skip to content

docs(metrics): extract Metrics code snippets in separate files #1245

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
Jan 17, 2023
Merged

docs(metrics): extract Metrics code snippets in separate files #1245

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
4f7a969
docs(metrics): extract Metrics code snippets in separate files #1221
niko-achilles Jan 13, 2023
4b3b81d
fix(docs): hl_lines of multiValueMetrics code snippet
niko-achilles Jan 16, 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
232 changes: 19 additions & 213 deletions docs/core/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,7 @@ The `Metrics` utility must always be instantiated outside of the Lambda handler.
=== "handler.ts"

```typescript hl_lines="1 3"
import { Metrics } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event, _context): Promise<void> => {
// ...
};
--8<-- "docs/snippets/metrics/basicUsage.ts"
```

### Utility settings
Expand All @@ -81,16 +75,7 @@ The `Metrics` utility is instantiated outside of the Lambda handler. In doing th
=== "handler.ts"

```typescript hl_lines="1 4"
import { Metrics } from '@aws-lambda-powertools/metrics';

// Metrics parameters fetched from the environment variables (see template.yaml tab)
const metrics = new Metrics();

// You can also pass the parameters in the constructor
// const metrics = new Metrics({
// namespace: 'serverlessAirline',
// serviceName: 'orders'
// });
--8<-- "docs/snippets/metrics/sam.ts"
```

=== "template.yml"
Expand All @@ -116,28 +101,13 @@ You can create metrics using the `addMetric` method, and you can create dimensio
=== "Metrics"

```typescript hl_lines="6"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
metrics.publishStoredMetrics();
};
--8<-- "docs/snippets/metrics/createMetrics.ts"
```

=== "Metrics with custom dimensions"

```typescript hl_lines="6-7"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event: any, _context: any): Promise<void> => {
metrics.addDimension('environment', 'prod');
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
metrics.publishStoredMetrics();
};
--8<-- "docs/snippets/metrics/customDimensions.ts"
```

!!! tip "Autocomplete Metric Units"
Expand All @@ -155,17 +125,8 @@ You can call `addMetric()` with the same name multiple times. The values will be

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

```typescript hl_lines="8 10"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
Copy link
Contributor

@dreamorosi dreamorosi Jan 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please change the line above (L128) to:

    ```typescript hl_lines="7 9"

this is not an error you introduced but I just noticed that the highlighted lines are not correct, so let's fix it.

Copy link
Contributor Author

@niko-achilles niko-achilles Jan 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dreamorosi , sure, take a look .

import { Context } from 'aws-lambda';

const metrics = new Metrics({ namespace:'serverlessAirline', serviceName:'orders' });

export const handler = async (event: any, context: Context): Promise<void> => {
metrics.addMetric('performedActionA', MetricUnits.Count, 2);
// do something else...
metrics.addMetric('performedActionA', MetricUnits.Count, 1);
};
```typescript hl_lines="7 9"
--8<-- "docs/snippets/metrics/multiValueMetrics.ts"
```
=== "Example CloudWatch Logs excerpt"

Expand Down Expand Up @@ -210,17 +171,7 @@ You can add default dimensions to your metrics by passing them as parameters in
=== "constructor"

```typescript hl_lines="6"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({
namespace: 'serverlessAirline',
serviceName: 'orders',
defaultDimensions: { 'environment': 'prod', 'foo': 'bar' }
});

export const handler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};
--8<-- "docs/snippets/metrics/defaultDimensions.ts"
```

=== "Middy middleware"
Expand All @@ -230,53 +181,19 @@ You can add default dimensions to your metrics by passing them as parameters in
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"
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};

// Wrap the handler with middy
export const handler = middy(lambdaHandler)
// Use the middleware by passing the Metrics instance as a parameter
.use(logMetrics(metrics, { defaultDimensions:{ 'environment': 'prod', 'foo': 'bar' } }));
--8<-- "docs/snippets/metrics/defaultDimensionsMiddy.ts"
```

=== "setDefaultDimensions method"

```typescript hl_lines="4"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
metrics.setDefaultDimensions({ 'environment': 'prod', 'foo': 'bar' });

export const handler = async (event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};
--8<-- "docs/snippets/metrics/setDefaultDimensions.ts"
```

=== "with logMetrics decorator"

```typescript hl_lines="9"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });
const DEFAULT_DIMENSIONS = { 'environment': 'prod', 'foo': 'bar' };

export class Lambda implements LambdaInterface {
// Decorate your handler class method
@metrics.logMetrics({ defaultDimensions: DEFAULT_DIMENSIONS })
public async handler(_event: any, _context: any): Promise<void> {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
}
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass); // (1)
--8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts"
```

1. Binding your handler method allows your handler to access `this` within the class methods.
Expand Down Expand Up @@ -310,17 +227,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"
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics));
--8<-- "docs/snippets/metrics/middy.ts"
```

=== "Example CloudWatch Logs excerpt"
Expand Down Expand Up @@ -360,21 +267,7 @@ The `logMetrics` decorator of the metrics utility can be used when your Lambda h
=== "handler.ts"

```typescript hl_lines="8"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

class Lambda implements LambdaInterface {

@metrics.logMetrics()
public async handler(_event: any, _context: any): Promise<void> {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
}
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass); // (1)
--8<-- "docs/snippets/metrics/decorator.ts"
```

1. Binding your handler method allows your handler to access `this` within the class methods.
Expand Down Expand Up @@ -415,14 +308,7 @@ Metrics, dimensions and namespace validation still applies.
=== "handler.ts"

```typescript hl_lines="7"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 10);
metrics.publishStoredMetrics();
};
--8<-- "docs/snippets/metrics/manual.ts"
```

=== "Example CloudWatch Logs excerpt"
Expand Down Expand Up @@ -460,17 +346,7 @@ If you want to ensure that at least one metric is emitted before you flush them,
=== "handler.ts"

```typescript hl_lines="11"
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics, { throwOnEmptyMetrics: true }));
--8<-- "docs/snippets/metrics/throwOnEmptyMetrics.ts"
```

### Capturing a cold start invocation as metric
Expand All @@ -480,34 +356,13 @@ You can optionally capture cold start metrics with the `logMetrics` middleware o
=== "Middy Middleware"

```typescript hl_lines="11"
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics, { captureColdStartMetric: true }));
--8<-- "docs/snippets/metrics/captureColdStartMetricMiddy.ts"
```

=== "logMetrics decorator"

```typescript hl_lines="8"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export class MyFunction implements LambdaInterface {

@metrics.logMetrics({ captureColdStartMetric: true })
public async handler(_event: any, _context: any): Promise<void> {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
}
}
--8<-- "docs/snippets/metrics/captureColdStartMetricDecorator.ts"
```

If it's a cold start invocation, this feature will:
Expand All @@ -531,18 +386,7 @@ You can add high-cardinality data as part of your Metrics log with the `addMetad
=== "handler.ts"

```typescript hl_lines="8"
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
metrics.addMetadata('bookingId', '7051cd10-6283-11ec-90d6-0242ac120003');
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics));
--8<-- "docs/snippets/metrics/addMetadata.ts"
```

=== "Example CloudWatch Logs excerpt"
Expand Down Expand Up @@ -594,51 +438,13 @@ CloudWatch EMF uses the same dimensions across all your metrics. Use `singleMetr
=== "Middy Middleware"

```typescript hl_lines="11 13-14"
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addDimension('metricUnit', 'milliseconds');
// This metric will have the "metricUnit" dimension, and no "metricType" dimension:
metrics.addMetric('latency', MetricUnits.Milliseconds, 56);

const singleMetric = metrics.singleMetric();
// This metric will have the "metricType" dimension, and no "metricUnit" dimension:
singleMetric.addDimension('metricType', 'business');
singleMetric.addMetric('orderSubmitted', MetricUnits.Count, 1);
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics));
--8<-- "docs/snippets/metrics/singleMetricDifferentDimsMiddy.ts"
```

=== "logMetrics decorator"

```typescript hl_lines="14 16-17"
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

class Lambda implements LambdaInterface {

@metrics.logMetrics()
public async handler(_event: any, _context: any): Promise<void> {
metrics.addDimension('metricUnit', 'milliseconds');
// This metric will have the "metricUnit" dimension, and no "metricType" dimension:
metrics.addMetric('latency', MetricUnits.Milliseconds, 56);

const singleMetric = metrics.singleMetric();
// This metric will have the "metricType" dimension, and no "metricUnit" dimension:
singleMetric.addDimension('metricType', 'business');
singleMetric.addMetric('orderSubmitted', MetricUnits.Count, 1);
}
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass); // (1)
--8<-- "docs/snippets/metrics/singleMetricDifferentDimsDecorator.ts"
```

1. Binding your handler method allows your handler to access `this` within the class methods.
12 changes: 12 additions & 0 deletions docs/snippets/metrics/addMetadata.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
metrics.addMetadata('bookingId', '7051cd10-6283-11ec-90d6-0242ac120003');
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics));
7 changes: 7 additions & 0 deletions docs/snippets/metrics/basicUsage.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import { Metrics } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event, _context): Promise<void> => {
// ...
};
12 changes: 12 additions & 0 deletions docs/snippets/metrics/captureColdStartMetricDecorator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
import { Metrics, MetricUnits } from '@aws-lambda-powertools/metrics';
import { LambdaInterface } from '@aws-lambda-powertools/commons';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export class MyFunction implements LambdaInterface {

@metrics.logMetrics({ captureColdStartMetric: true })
public async handler(_event: any, _context: any): Promise<void> {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
}
}
11 changes: 11 additions & 0 deletions docs/snippets/metrics/captureColdStartMetricMiddy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
import middy from '@middy/core';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

const lambdaHandler = async (_event: any, _context: any): Promise<void> => {
metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
};

export const handler = middy(lambdaHandler)
.use(logMetrics(metrics, { captureColdStartMetric: true }));
Loading