Instruments v2.0.0 Instruments.Probe behaviour

A behavior for a Probe.

Modules that define probes are expected to implement all of the functions in this behaviour.

A probe is created via the call to Instruments.Probe.probe_init/3, and is then called every sample_interval milliseconds via the Instruments.Probe.probe_sample/1 function. The probe can then update its internal state and do any processing it requires.

Every report_interval milliseconds, the probe is expected to emit its metric value.

Link to this section Summary

Callbacks

Called at least every report_interval milliseconds. This call reads the value of the probe, which is reported to the underlying statistics system

Called when the probe's runner process receives an unknown message

Called when the probe is created. The callback is passed the name of the probe, what kind of metric it's producing and the options the probe was created with

Resets the probe's state

Called every sample_interval milliseconds. When called, the probe should perform its measurement and update its internal state

Link to this section Types

Link to this type

datapoint()
datapoint() :: String.t()

Link to this type

probe_options()
probe_options() :: [
  sample_rate: pos_integer(),
  tags: [String.t(), ...],
  report_interval: pos_integer(),
  sample_interval: pos_integer(),
  function: (() -> {:ok, state()}),
  mfa: mfa(),
  module: module(),
  keys: [atom()]
]

Link to this type

probe_type()
probe_type() :: :counter | :spiral | :gauge | :histogram | :timing | :set

Link to this type

probe_value()
probe_value() :: number() | keyword()

Link to this type

state()
state() :: any()

Link to this section Functions

Link to this function

define(name, type, options)

Link to this function

define!(name, type, options)

Link to this section Callbacks

Link to this callback

probe_get_value(state)
probe_get_value(state()) :: {:ok, probe_value()}

Called at least every report_interval milliseconds. This call reads the value of the probe, which is reported to the underlying statistics system.

Return values can either take the form of a single numeric value, or a keyword list keys -> numeric values. Nil values won't be reported to the statistics system.

Link to this callback

probe_handle_message(any, state)
probe_handle_message(any(), state()) :: {:ok, state()}

Called when the probe's runner process receives an unknown message.

You must return {:ok, state}. Any other return values will cancel further execution of the probe.

Link to this callback

probe_init(arg0, probe_type, probe_options)
probe_init(String.t(), probe_type(), probe_options()) :: {:ok, state()}

Called when the probe is created. The callback is passed the name of the probe, what kind of metric it's producing and the options the probe was created with.

You must return {:ok, state}. The state will be passed back to you on subsequent callbacks. Any other return values will cancel further execution of the probe.

Link to this callback

probe_reset(state)
probe_reset(state()) :: {:ok, state()}

Resets the probe's state.

You must return {:ok, state}. Any other return values will cancel further execution of the probe.

Link to this callback

probe_sample(state)
probe_sample(state()) :: {:ok, state()}

Called every sample_interval milliseconds. When called, the probe should perform its measurement and update its internal state.

You must return {:ok, state}. Any other return values will cancel further execution of the probe.