telemetry_metrics_cloudwatch v0.2.2 TelemetryMetricsCloudwatch View Source

This is a Amazon CloudWatch Reporter for Telemetry.Metrics definitions.

Provide a list of metric definitions to the init/2 function. It's recommended to run TelemetryMetricsCloudwatch under a supervision tree, usually under Application.

def start(_type, _args) do
  # List all child processes to be supervised
  children = [
    {TelemetryMetricsCloudwatch, [metrics: metrics()]}
  ...
  ]

  opts = [strategy: :one_for_one, name: ExampleApp.Supervisor]
  Supervisor.start_link(children, opts)
end

defp metrics do
  [
    counter("http.request.count"),
    last_value("vm.memory.total", unit: :byte),
    last_value("vm.total_run_queue_lengths.total")
  ]
end

You can also provide options for the namespace used in CloudWatch (by default, "Telemetry") and the minimum frequency (in milliseconds) with which data will be posted (see section below for posting rules). For instance:

...
children = [
   {TelemetryMetricsCloudwatch, metrics: metrics(), namespace: "Backend", push_interval: 30_000}
]
...

Telemetry.Metrics Types Supported

TelemetryMetricsCloudwatch supports 3 of the Metrics:

  • Counter: Counter metric keeps track of the total number of specific events emitted.
  • LastValue: Last value keeps track of the selected measurement found in the most recent event.
  • Summary: Summary aggregates measurement's values into statistics, e.g. minimum and maximum, mean, or percentiles. This sends every measurement to CloudWatch.

These metrics are sent to CloudWatch based on the rules described below.

When Data is Sent

Cloudwatch has certain constraints on the number of metrics that can be sent up at any given time. TelemetryMetricsCloudwatch will send accumulated metric data at least every minute (configurable by the :push_interval option) or when the data cache has reached the maximum size that CloudWatch will accept.

Units

In order to report metrics in the CloudWatch UI, they must be one of the following values:

  • Time units: :second, :microsecond, :millisecond
  • Byte sizes: :byte, :kilobyte, :megabyte, :gigabyte, :terabyte
  • Bit sizes: :bit, :kilobit, :megabit, :gigabit, :terabit

For Telementry.Metrics.Counters, the unit will always be :count. Otherwise, the unit will be treated as nil.

Notes on AWS

ExAws is the library used to send metrics to CloudWatch. Make sure your keys are configured and that they have the correct permissions of cloudwatch:PutMetricData.

Up to 10 tags are sent up to AWS as dimensions for a given metric. Every metric name will have a suffix added based on the metric type (CloudWatch doesn't allow different units / measurements with the same name). So, for instance, if your metrics are:

summary("my_app.repo.query.total_time", unit: {:nanosecond, :millisecond})
count("my_app.repo.query.total_time")

Then the metric names in CloudWatch will be:

  • my_app.repo.query.total_time.summary (with all data points recorded)
  • my_app.repo.query.total_time.count (with the number of queries recorded)

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Start the TelemetryMetricsCloudwatchGenServer.

Available options:

  • :name - name of the reporter instance.
  • :metrics - a list of Telemetry.Metrics to track.
  • :namespace - Namespace to use in CloudWatch
  • :push_interval - The minimum interval that metrics are guaranteed to be pushed to cloudwatch (in milliseconds)