Skip to content
This repository has been archived by the owner on Jul 17, 2024. It is now read-only.

Latest commit

 

History

History
269 lines (173 loc) · 9.57 KB

API.md

File metadata and controls

269 lines (173 loc) · 9.57 KB
Raw

AWS Serverless Prometheus Push Gateway

AWS Serverless Prometheus Push Gateway enables you to push metrics into Prometheus from any source without modifying your application or running an always-on service for Prometheus to scrape. This AWS CDK construct library deploys an AWS Lambda function using the Amazon Distribution for OpenTelemetry (ADOT) extension layer and connects it with an Amazon SQS queue and an Amazon Managed Service for Prometheus (AMP) workspace.

For example, you could create an AWS IoT Core rule to send telemetry data to AMP.

Lambda event payload

Example

{
  "dimensions": {
    "customerId": "customer1"
  },
  "timestamp": 1676398017000,
  "metrics": {
    "temperature": "14.3",
    "ph": "6.7"
  }
}

Properties

  • dimensions: Key/value pairs of dimension names and values.
  • metrics: Key/value pairs of metric names and values.
  • timestamp: Timestamp in milliseconds since epoch.

Metric type inference

Metric values can either be integers or floating point numbers. There is a risk that floating point metrics will be interpreted as integers by the JSON parser. To avoid this, we recommend sending metrics as strings to preserve the decimal point.

{
  "metric1": 12.0,
  "metric2": "12.0"
}

In this example, metric1 will get interpreted as the integer value 12, but metric2 will have the decimal preserved.

Caveats

Amazon Managed Prometheus requires metrics for a given combination of labels to arrive in strictly ascending order by timestamp. Anything that arrives late gets rejected and dropped. In practice, as long as events for a given combination are sent on an interval of at most every 10 seconds, out-of-order messages are unlikely.

API Reference

Constructs

PrometheusLambdaPushGateway

Create an AWS Lambda function that pushes metrics to Prometheus.

It can either be called directly or via Amazon SQS.

Initializers 

import { PrometheusLambdaPushGateway } from 'cdk-aws-serverless-prometheus-push-gateway'

new PrometheusLambdaPushGateway(scope: Construct, id: string, props: PrometheusLambdaPushGatewayProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props PrometheusLambdaPushGatewayProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { PrometheusLambdaPushGateway } from 'cdk-aws-serverless-prometheus-push-gateway'

PrometheusLambdaPushGateway.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
lambda aws-cdk-lib.aws_lambda.Function No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

lambdaRequired 
public readonly lambda: Function;
  • Type: aws-cdk-lib.aws_lambda.Function

Structs

PrometheusLambdaPushGatewayProps

The properties for PrometheusLambdaPushGateway.

Initializer 

import { PrometheusLambdaPushGatewayProps } from 'cdk-aws-serverless-prometheus-push-gateway'

const prometheusLambdaPushGatewayProps: PrometheusLambdaPushGatewayProps = { ... }

Properties

Name Type Description
prometheusArn string ARN for the Amazon Managed Prometheus workspace.
prometheusEndpoint string HTTP endpoint for Prometheus.
queue aws-cdk-lib.aws_sqs.IQueue Optional SQS queue for receiving metrics.
xray boolean Enable X-Ray tracing for Lambda functions.
prometheusArnRequired 
public readonly prometheusArn: string;
  • Type: string

ARN for the Amazon Managed Prometheus workspace.

prometheusEndpointRequired 
public readonly prometheusEndpoint: string;
  • Type: string

HTTP endpoint for Prometheus.

queueOptional 
public readonly queue: IQueue;
  • Type: aws-cdk-lib.aws_sqs.IQueue
  • Default: No queue. Invoke the Lambda with the metrics payload directly.

Optional SQS queue for receiving metrics.

xrayOptional 
public readonly xray: boolean;
  • Type: boolean
  • Default: false

Enable X-Ray tracing for Lambda functions.