# `Mobius.Exports`
[🔗](https://github.com/mobius-home/mobius/blob/v0.8.0/lib/mobius/exports.ex#L1)

Support retrieving historical data in different formats

Current formats:

* CSV
* Series
* Line plot
* Mobius Binary Format (MBF)

The Mobius Binary Format (MBF) is a format that contains the current state of
all metrics. This binary format is useful for transferring metric information in
a format that other services can parse and use. For more details see `mbf/1`.

# `csv_export_opt`

```elixir
@type csv_export_opt() ::
  export_opt() | {:headers, boolean()} | {:iodevice, IO.device()}
```

Options for exporting a CSV

# `export_metric_type`

```elixir
@type export_metric_type() :: Mobius.metric_type() | {:summary, atom()}
```

Metric types that can be exported

By default you can try to export any `Mobius.metric_type()`, but for the
summary metric type you can specify which summary type you want to export.

# `export_opt`

```elixir
@type export_opt() ::
  {:mobius_instance, Mobius.instance()}
  | {:from, integer()}
  | {:to, integer()}
  | {:last, integer() | {integer(), Mobius.time_unit()}}
```

Options to use when exporting time series metric data

* `:mobius_instance` - the name of the Mobius instance you are using. Unless
  you specified this in your configuration you should be safe to allow this
  option to default, which is `:mobius`.
* `:last` - display data point that have been captured over the last `x`
  amount of time. Where `x` is either an integer or a tuple of
  `{integer(), time_unit()}`. If you only pass an integer the time unit of
  `:seconds` is assumed. By default Mobius will plot the last 3 minutes of
  data.
* `:from` - the unix timestamp, in seconds, to start querying from
* `:to` - the unix timestamp, in seconds, to stop querying at

# `mbf_export_opt`

```elixir
@type mbf_export_opt() :: {:out_dir, Path.t()} | export_opt()
```

# `csv`

```elixir
@spec csv(binary(), export_metric_type(), map(), [csv_export_opt()]) ::
  :ok | {:ok, binary()} | {:error, Mobius.Exports.UnsupportedMetricError.t()}
```

Generate a CSV for the metric

Please see `Mobius.Exporters.CSV` for more information.

```elixir
# Return CSV as string
{:ok, csv_string} = Mobius.Exports.csv("vm.memory.total", :last_value, %{})

# Write to console
Mobius.Exports.csv("vm.memory.total", :last_value, %{}, iodevice: :stdio)

# Write to a file
{:ok, file} = File.open("mycsv.csv", [:write])
:ok = Mobius.Exports.csv("vm.memory.total", :last_value, %{}, iodevice: file)
```

# `mbf`

```elixir
@spec mbf([mbf_export_opt()]) ::
  binary() | {:ok, Path.t()} | {:error, Mobius.FileError.t()}
```

Export all metrics in the Mobius Binary Format (MBF)

This is mostly useful when you want to share metric data with different
networked services.

The binary format is `<<version, metric_data::binary>>`

The first byte is the version number of the following metric data. Currently,
the version number is `1`.

The metric data binary is the type of `[Mobius.metric()]` encoded in Binary
ERlang Term format (BERT) and compressed (using Zlib compression).

Optionally, `to_mbf/1` can write the binary to a file using the `:out_dir`
option.

```elixir
Mobius.Exports.to_mbf(out_dir: "/my/dir")
```

The generated file is returned as `{:ok, filename}`. The format of the
file name is `YYYYMMDDHHMMSS-metrics.mbf`.

See `Mobius.Exports.parse_mbf/1` to parse a binary in MBF.

# `metrics`

```elixir
@spec metrics(
  Mobius.metric_name(),
  Mobius.metric_type(),
  map(),
  [export_opt()] | keyword()
) :: [
  Mobius.metric()
]
```

Retrieve the raw metric data from the history store for a given metric.

Output will be a list of metric values, which will be in the format, eg:
  `%{type: :last_value, value: 12, tags: %{interface: "eth0"}, timestamp: 1645107424}`

  If there are tags for the metric you can pass those in the third argument:

```elixir
Mobius.Exports.metrics("vm.memory.total", :last_value, %{some: :tag})
```

By default the filter will display the last 3 minutes of metric history.

However, you can pass the `:from` and `:to` options to look at a specific
range of time.

```elixir
Mobius.Exports.metrics("vm.memory.total", :last_value, %{}, from: 1630619212, to: 1630619219)
```

You can also filter data over the last `x` amount of time. Where x is an
integer. When there is no `time_unit()` provided the unit is assumed to be
`:second`.

Retrieving data over the last 30 seconds:

```elixir
Mobius.Exports.metrics("vm.memory.total", :last_value, %{}, last: 30)
```

Retrieving data over the last 2 hours:

```elixir
Mobius.Exports.metrics("vm.memory.total", :last_value, %{}, last: {2, :hour})
```

Retrieving summary data can be performed by specifying the type: :summary - however, this returns
value data in the form of a map, which cannot be plotted or csv exported. To reduce the output to
a single metric value, use the form: {:summary, :summary_metric}

```elixir
Mobius.Exports.metrics("vm.memory.total", {:summary, :average}, %{}, last: {2, :hour})
```

# `parse_mbf`

```elixir
@spec parse_mbf(binary()) ::
  {:ok, [Mobius.metric()]} | {:error, Mobius.Exports.MBFParseError.t()}
```

Parse the mobius binary format into a list of metrics

# `plot`

```elixir
@spec plot(Mobius.metric_name(), export_metric_type(), map(), [export_opt()]) ::
  :ok | {:error, Mobius.Exports.UnsupportedMetricError.t()}
```

Plot the metric name to the screen

This takes the same arguments as for filter_metrics, eg:

If there are tags for the metric you can pass those in the second argument:

```elixir
Mobius.Exports.plot("vm.memory.total", :last_value, %{some: :tag})
```

By default the plot will display the last 3 minutes of metric history.

However, you can pass the `:from` and `:to` options to look at a specific
range of time.

```elixir
Mobius.Exports.plot("vm.memory.total", :last_value, %{}, from: 1630619212, to: 1630619219)
```

You can also plot data over the last `x` amount of time. Where x is an
integer. When there is no `time_unit()` provided the unit is assumed to be
`:second`.

Plotting data over the last 30 seconds:

```elixir
Mobius.Exports.plot("vm.memory.total", :last_value, %{}, last: 30)
```

Plotting data over the last 2 hours:

```elixir
Mobius.Exports.plot("vm.memory.total", :last_value, %{}, last: {2, :hour})
```

Retrieving summary data can be performed by specifying type of the form:
  `{:summary, :summary_metric}`

```elixir
Mobius.Exports.metrics("vm.memory.total", {:summary, :average}, %{}, last: {2, :hour})
```

# `series`

```elixir
@spec series(String.t(), export_metric_type(), map(), [export_opt()]) :: [term()]
```

Generates a series that contains the value of the metric

---

*Consult [api-reference.md](api-reference.md) for complete listing*
