View Source TelemetryEmitter.Emitter (TelemetryEmitter v0.1.1)

Emit metrics declared with Telemetry.Metrics.

Metric names are represented at strings separated by . or lists of atoms. Each name must have at least two segments, the last segment being the measurement.

All functions have the metric as the first argument. There is also an optional metadata argument that accepts a map of metric metadata, including tag values.

examples

Examples

Increment a counter:

Emitter.increment("request.count")

Or:

Emitter.increment([:request, :count])

Measure the time of a function call:

Emitter.measure("request.stop.duration", %{operation: "op1"}, fn ->
  {Service.operation(...), %{}}
end)

Link to this section Summary

Functions

Emit a metric with explicit measurements.

Emit the current value of the gauge as a number.

Increment the value of the counter metric. The last segment of the metric is the measurement.

Measure the duration of the given function.

Link to this section Functions

Link to this function

emit(metric, measurements, metadata \\ %{})

View Source
@spec emit(metric :: String.t() | [atom()], measurements :: map(), metadata :: map()) ::
  :ok

Emit a metric with explicit measurements.

This works with any of the declarations from Telemetry.Metrics. In this case, measurements are provided by the measurements argument and the entirety of metric is used as the name of the emitted Telemetry event.

This is largely an alias for :telemetry.execute/3.

examples

Examples

counter("service.request.count"),
summary("service.request.duration", unit: {:native, :millisecond}),
Emitter.emit("service.request", %{count: 1, duration: 5})

The metric service.request will be emitted with both the count and duration measurements.

Link to this function

gauge(metric, value, metadata \\ %{})

View Source
@spec gauge(
  metric :: String.t() | [atom()],
  value :: number(),
  metadata ::
    %{required(String.t()) => String.t()} | %{required(atom()) => String.t()}
) :: :ok

Emit the current value of the gauge as a number.

Define the metric using Telemetry.Metrics.last_value/2.

Telemetry.Metrics.last_value("memory_usage.ratio")

Then emit the metric using the same name:

Emitter.gauge("memory_usage.ratio", 0.88)

The metric will be emitted as memory_usage with the measurement, %{ratio: 0.88}.

Link to this function

increment(counter, count \\ 1, metadata \\ %{})

View Source
@spec increment(
  counter :: String.t() | [atom()],
  count :: integer(),
  metadata ::
    %{required(String.t()) => String.t()} | %{required(atom()) => String.t()}
) :: :ok

Increment the value of the counter metric. The last segment of the metric is the measurement.

Define the metric using Telemetry.Metrics.counter/2.

Telemetry.Metrics.counter("request.count")

Then emit the metric using the same name:

Emitter.increment("request.count")

The metric will be emitted as request with the measurement %{count: 1}.

Note

If the metric is delcared as a counter, the measurement value will always be 1.

Define the metric as a sum to increment the value by more than 1:

Telemetry.Metrics.sum("request.count")

Then emit the metric using the same name:

Emitter.increment("request.count", 99)

The metric will be emitted as request with the measurement %{count: 99}.

Link to this function

measure(metric, start_metadata \\ %{}, function)

View Source
@spec measure(
  metric :: String.t() | [atom()],
  start_metadata ::
    %{required(String.t()) => String.t()} | %{required(atom()) => String.t()},
  function :: function()
) :: :ok | any()

Measure the duration of the given function.

The metric name may be the same as the .stop metric: prefix.stop.duration where prefix is any aribitrary metric name and the suffix .stop.duration is required. The metric is reported as prefix.stop with a measurement of :duration.

Alternatively, the .stop.duration portion may be omitted for convenience. In this case the metric argument must match the prefix of the declared metric.

The given function must return a tuple, {return_value, stop_metadata}.

The start_metadata parameter is emitted for the .start event. The stop_metadata is emitted for the .stop event.

The return_value will be the value returned by this function.

Define the metric using Telemetry.Metrics.summary/2.

examples

Examples

Declaring the metric using Telemetry.Metrics.summary/2:

Telemetry.Metrics.summary("my.external.service.call.start.system_time", tags: [:operation], unit: {:native, :millisecond})
Telemetry.Metrics.summary("my.external.service.call.stop.duration", tags: [:operation], unit: {:native, :millisecond})
Telemetry.Metrics.summary("my.external.service.call.exception.duration", tags: [:operation], unit: {:native, :millisecond})

Emitting the metric using TelemetryEmitter.Emitter.measure/3:

Emitter.measure("my.external.service.call", %{operation: :record}, fn ->
  {MyExternalService.call(...), %{}}
end)

Note the use of the base metric name in the first argument to measure/3. You may also use the full .stop name, my.external.service.call.stop.duration. Do not use the metric .start.system_time suffix in the first argument.

If the metric with both the .start.system_time and .stop.duration suffixes are declared, both will be emitted:

  1. The my.external.service.call.start metric will be emitted with a system_time measurement of the start time of the call.
  2. The my.external.service.call.stop metric will be emitted with a duration measurement of the duration of calling the function parameter.
  3. The my.external.service.call.exception metric will be emitted if an exception is raised. It will have a duration measurement of the duration of calling the function parameter.

This function delegates to :telemetry.span/3, so see the documentation for that function for additional information.