TelemetryMetricsCloudwatch

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

Installation

To install telemetry_metrics_cloudwatch, just add an entry to your mix.exs:

def deps do
  [
    {:telemetry_metrics_cloudwatch, "~> 0.3"}
  ]
end

(Check Hex to make sure you're using an up-to-date version number.)

Usage

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 4 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.
• Sum: Sum metric keeps track of the sum of selected measurement's values carried by specific events. If you are using Summary for a metric already, then CloudWatch can calculate a Sum using that Summary metric. If you only need a Sum (and no other summary metrics) then use this Sum metric instead.

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

To write high-resolution metrics, supply the :storage_resolution option (which can be the default of :standard or :high):

counter(
  "http.request.count",
  reporter_options: [storage_resolution: :high]
)

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.

Event Sampling

You can optionally send only a portion of reported events to CloudWatch via the :sample_rate option. This parameter should contain a value between 0.0 and 1.0 (inclusive), and represents the proportion of events that will be reported. For instance, a sample rate value of 0.0 will ensure no events are sent, whereas a sample rate value of 1.0 will ensure all events are sent. A sample rate of 0.25 will result in roughly a quarter of all events being sent.

Note: Using a sampling rate of less than 1.0 will result in incorrect values for the "Sum" and "Counter" metric types (and some of the values like min/max for the "Summary" metric type) due to the under-reporting of events. You should only use a sampling rate of less than 1.0 if you have a guaranteed high rate of events and only care about summary statistics like averages and percentiles.

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.

ExAws Setup

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.

Running Tests

To run tests:

$ mix test

Reporting Issues

Please report all issues on github.