README.md

Membrane Telmetry Metrics

This repository contains a tool for generating metrics.

It is part of Membrane Multimedia Framework.

Installation

The package can be installed by adding membrane_telemetry_metrics to your list of dependencies in mix.exs:

def deps do
  [
    {:membrane_telemetry_metrics, "~> 0.1.0"}
  ]
end

Usage

The usage example below illustrates, how you can use this tool to aggregate metrics and generate reports containing their values. In this case, we have a scenario, where a couple of people are doing their shopping, and we want to have access to the reports with some metrics about them, without calling each of these people directly.

To benefit from of full functionality offered by this tool, you have to use both Membrane.TelemetryMetrics and Mebrane.TelemetryMetrics.Reporter.

First, put

config :membrane_telemetry_metrics, enabled: true

in your config.exs. You can also pass list of events, that will be enabled in :events option (in this case, it would be [[:shopping]]). If you don't specify that option, all events will be enabled.

Let's assume, that you want to track three metrics:

• cash_spent
• number_of_payments
• last_visited_shop So, the definition of our list of metrics will look like

metrics = 
  [
    Telemetry.Metrics.sum(
      "cash_spent",
      event_name: [:shopping],
      measurement: :payment
    ),
    Telemetry.Metrics.counter(
      "number_of_payments",
      event_name: [:shopping]
    ),
    Telemetry.Metrics.last_value(
      "last_visited_shop",
      event_name: [:shopping],
      measurement: :shop
    )
  ]

Then, you have to start Mebrane.TelemetryMetrics.Reporter. It can be made by calling

Membrane.TelemetryMetrics.Reporter.start_link(metrics, name: ShoppingReporter)

but the suggested way is to do it under Supervisor tree, in Application module.

Now, ShoppingReporter is ready to aggregate metrics from emitted events. But before that, we have to register our event in every process, that will emit it. Let's assume, that we want to aggregate data about three people: James Smith, Mary Smith and Patricia Johnson. Events with data about each of these people will be emitted in a different process.

In John Smith's process we will execute code

require Membrane.TelemetryMetrics

Membrane.TelemetryMetrics.register([:shopping], [name: "James", surname: "Smith"])

Membrane.TelemetryMetrics.execute(
  [:shopping],
  %{shop: "Grocery", payment: 10},
  %{},
  [name: "James", surname: "Smith"]
)

Membrane.TelemetryMetrics.execute(
  [:shopping],
  %{shop: "Bakery", payment: 5},
  %{},
  [name: "James", surname: "Smith"]
)

Membrane.TelemetryMetrics.execute(
  [:shopping],
  %{shop: "Jeweller", payment: 100},
  %{},
  [name: "James", surname: "Smith"]
)

In Mary Smith's process we will execute code

require Membrane.TelemetryMetrics

Membrane.TelemetryMetrics.register([:shopping], [name: "Mary", surname: "Smith"])

Membrane.TelemetryMetrics.execute(
  [:shopping],
  %{shop: "Bookshop", payment: 25},
  %{},
  [name: "Mary", surname: "Smith"]
)

Membrane.TelemetryMetrics.execute(
  [:shopping],
  %{shop: "Butcher", payment: 15},
  %{},
  [name: "Mary", surname: "Smith"]
)

In Patricia Johnson's process we will execute code

require Membrane.TelemetryMetrics

Membrane.TelemetryMetrics.register(
  [:shopping],
  [name: "Patricia", surname: "Johnson"]
)

Membrane.TelemetryMetrics.execute(
  [:shopping],
  %{shop: "Newsagent", payment: 5},
  %{},
  [name: "Patricia", surname: "Johnson"]
)

Then, calling

Membrane.TelemetryMetrics.Reporter.scrape(ShoppingReporter)

from anywhere on this same node, as noticed processes, will cause getting the following result:

%{
  {:surname, "Johnson"} => %{
    {:name, "Patricia"} => %{
      "cash_spent" => 5,
      "last_visited_shop" => "Newsagent",
      "number_of_payments" => 1
    }
  },
  {:surname, "Smith"} => %{
    {:name, "James"} => %{
      "cash_spent" => 115,
      "last_visited_shop" => "Jeweller",
      "number_of_payments" => 3
    },
    {:name, "Mary"} => %{
      "cash_spent" => 40,
      "last_visited_shop" => "Butcher",
      "number_of_payments" => 2
    }
  }
}

Then, for example, if Mary Smith's process exits, you will get a report like

%{
  {:surname, "Johnson"} => %{
    {:name, "Patricia"} => %{
      "cash_spent" => 5,
      "last_visited_shop" => "Newsagent",
      "number_of_payments" => 1
    }
  },
  {:surname, "Smith"} => %{
    {:name, "James"} => %{
      "cash_spent" => 115,
      "last_visited_shop" => "Jeweller",
      "number_of_payments" => 3
    }
  }
}

If a process registers an event by calling

Membrane.TelemetryMetrics.register(event_name, label)

and exits after it, every metric that aggregated measurements from an event with event_name will drop its values held for a specific value of label, as in the example above Mary Smith has disappeared from the report, after the end of her's process.

Copyright and License

Copyright 2022, Software Mansion

Licensed under the Apache License, Version 2.0