Mobius (Mobius v0.8.0)

Copy Markdown View Source

Localized metrics reporter

Summary

Types

Arguments to Mobius

A function to process an event's measurements

Options you can pass an event

The name of the Mobius instance

A single metric data point

The name of the metric

Packed metric record used in the in-memory RRD

Functions

Returns a specification to start this module under a supervisor.

Print the current value of a metric.

Get the current metric information

Print the metrics available to chart for an instance.

Print a line plot of a metric over time.

Remove all data, returning Mobius to a clean state

Persist the metrics to disk

Start Mobius

Types

arg()

@type arg() ::
  {:mobius_instance, instance()}
  | {:metrics, [Telemetry.Metrics.t()]}
  | {:persistence_dir, binary()}
  | {:autosave_interval, non_neg_integer() | nil}
  | {:scrape_interval, pos_integer()}
  | {:compression_level, 0..9}
  | {:database, Mobius.RRD.t()}
  | {:events, [event_def()]}
  | {:event_log_size, integer()}
  | {:clock, module()}
  | {:session, session()}

Arguments to Mobius

  • :name - the name of the mobius instance (defaults to :mobius)
  • :metrics - list of telemetry metrics for Mobius to track
  • :persistence_dir - the top level directory where mobius will persist
  • :autosave_interval - time in seconds (a positive integer) between automatic writes of the persistence data (default disabled) metric information
  • :scrape_interval - time in milliseconds between scrapes of the tracked metrics into the history (defaults to 1_000). The history stores at most one snapshot per second, so values below 1_000 are clamped to 1_000 with a logged warning; other invalid values fall back to the default. The first scrape runs immediately at startup
  • :compression_level - the zlib level (0..9) used when compressing persisted metric history and event log data. Higher levels trade more CPU at save time for smaller files. Defaults to 9 (maximum compression). 0 disables compression.
  • :database - the Mobius.RRD.t() to use. This will default to the default values found in Mobius.RRD
  • :events - a list of events for mobius to store in the event log
  • :event_log_size - number of events to store (defaults to 500)
  • :clock - module that implements the Mobius.Clock behaviour
  • :session - a unique id to distinguish between different ties Mobius has ran

Mobius sessions allow you collect events to analyze across the different times mobius ran. A good example of this might be measuring how fast an interface makes its first connection. You can build averages over run times and measure connection performance. This will allow you to know on average how fast a device connects so you can check for increased or decreased performance between runs.

By default Mobius will generate an UUID for each run.

event_def()

@type event_def() :: binary() | {binary(), keyword()}

event_measurement_values()

@type event_measurement_values() :: ({atom(), term()} -> term())

A function to process an event's measurements

This will be called on each measurement and will receive a tuple where the first element is the name of the measurement and the second element is the value. This function can process the value and return a new one.

event_opt()

@type event_opt() ::
  {:measurement_values, event_measurement_values()}
  | {:tags, [atom()]}
  | {:group, atom()}

Options you can pass an event

These options only apply to the :event argument to Mobius. If you want to track metrics please see the :metrics argument to Mobius.

  • :tags - list of tag names to save with the event
  • :measurement_values - a function that will receive each measurement that allows for data processing before storing the event in the event log
  • :group - an atom that defines the event group, this will allow for filtering on particular types of events for example: :network. Default is :default

instance()

@type instance() :: atom()

The name of the Mobius instance

This is used to store data for a particular set of mobius metrics.

metric()

@type metric() :: %{
  type: metric_type(),
  value: term(),
  tags: map(),
  timestamp: integer(),
  name: binary()
}

A single metric data point

  • :type - the type of the metric
  • :value - the value of the measurement for the metric
  • :tags - a map of the tags for the metric
  • :timestamp - the naive time in seconds the metric was sampled
  • :name - the name of the metric

metric_name()

@type metric_name() :: binary()

The name of the metric

Example: "vm.memory.total"

metric_record()

@type metric_record() :: {metric_name(), metric_type(), term(), map()}

Packed metric record used in the in-memory RRD

This is the storage shape of a single metric inside a scrape snapshot. The timestamp lives one level up on the snapshot itself, so the inner tuple only carries identity (name, tags), type, and value.

metric_type()

@type metric_type() :: :counter | :last_value | :sum | :summary

session()

@type session() :: binary()

time_unit()

@type time_unit() :: :second | :minute | :hour | :day

timestamp()

@type timestamp() :: integer()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

current(metric_name, opts \\ [])

@spec current(metric_name(), keyword()) :: :ok

Print the current value of a metric.

If the metric is histogram-enabled, a small ASCII histogram of its buckets is printed too. For tagged metrics pass tags: with the exact tag map.

Options: :type, :tags, :mobius_instance, and the window options (:last/:from/:to) shared by Mobius.Charts. When :type is omitted it is inferred from the tracked metrics.

get_latest_events(instance \\ :mobius)

@spec get_latest_events(instance()) :: [Mobius.Event.t()]

Get the latest events

The latest events are the events recorded between the last query for the events and the query for the events that is being called.

get_latest_metrics(instance \\ :mobius)

@spec get_latest_metrics(instance()) :: [metric()]

Get the latest metrics

The latest metrics are the metrics recorded between the last query for the metrics and the query for the metrics that is being called.

info()

@spec info() :: :ok

Get the current metric information

If you configured Mobius to use a different name then you can pass in your custom name to ensure Mobius requests the metrics from the right place.

info(instance)

@spec info(instance()) :: :ok

metrics(instance \\ :mobius)

@spec metrics(instance()) :: :ok

Print the metrics available to chart for an instance.

Lists each metric's name, type, tags, and whether a histogram is available, so you know what to pass to current/2 and plot/2.

plot(metric_name, opts \\ [])

@spec plot(metric_name(), keyword()) :: :ok

Print a line plot of a metric over time.

The plot renders the series as a braille curve with a relative time x-axis.

Options: :type, :tags, :mobius_instance, the window options (:last/:from/:to), and :width/:height for the plot dimensions. When :type is omitted it is inferred from the tracked metrics; summary metrics are not plottable directly — pass a field (e.g. type: {:summary, :average}) or use current/2 for the histogram.

Mobius.plot("vm.memory.total", last: {5, :minute})

remove_all_data()

@spec remove_all_data() :: :ok

Remove all data, returning Mobius to a clean state

This clears everything out for the instance without requiring a restart:

  • the in-memory metrics table (current counters, sums, last values, and summary/histogram data)
  • the accumulated historical records (the in-memory RRD)
  • the in-memory event log
  • the persisted files on disk (history, metrics_table, and event_log)

This is useful when repurposing a device whose historical data is no longer meaningful, or while debugging and developing. The configured metrics and events keep being tracked — only the recorded data is discarded — so Mobius starts collecting fresh data immediately.

If you configured Mobius to use a different name then you can pass in your custom name to ensure the data is removed from the right instance.

remove_all_data(instance)

@spec remove_all_data(instance()) :: :ok

save()

@spec save() :: :ok | {:error, reason :: term()}

Persist the metrics to disk

save(instance)

@spec save(instance()) :: :ok | {:error, reason :: term()}

start_link(args)

@spec start_link([arg()]) :: Supervisor.on_start()

Start Mobius