Merge pull request #365 from membraneframework/fine-grained-telemetry…

…-metrics

More fine-grained control over emitted metrics

CHANGELOG.md

@@ -1,5 +1,6 @@
  ## 0.9.0
  * Fixed PadAdded spec [#359](https://github.com/membraneframework/membrane_core/pull/359)
+ * More fine-grained control over emitted metrics [#365](https://github.com/membraneframework/membrane_core/pull/365)
  ### PRs not influencing public API:
  * Prevent internal testing notifications from reaching pipeline module [#350](https://github.com/membraneframework/membrane_core/pull/350)
  * Fix unknown node error on distribution changes [#352](https://github.com/membraneframework/membrane_core/pull/352)

lib/membrane/core/telemetry.ex

@@ -5,7 +5,7 @@ defmodule Membrane.Core.Telemetry do
 
   require Membrane.Pad
 
-  @enable_telemetry Application.compile_env(:membrane_core, :enable_telemetry, false)
+  @telemetry_flags Application.compile_env(:membrane_core, :telemetry_flags, [])
 
   @doc """
   Reports metrics such as input buffer's size inside functions, incoming events and received caps.
@@ -25,7 +25,11 @@ defmodule Membrane.Core.Telemetry do
         }
       end
 
-    report_event(event, value)
+    report_event(
+      event,
+      value,
+      Keyword.get(@telemetry_flags, :metrics, []) |> Enum.find(&(&1 == metric)) != nil
+    )
   end
 
   @doc """
@@ -53,7 +57,11 @@ defmodule Membrane.Core.Telemetry do
         }
       end
 
-    report_event(event, value)
+    report_event(
+      event,
+      value,
+      Keyword.get(@telemetry_flags, :metrics, []) |> Enum.find(&(&1 == :bitrate)) != nil
+    )
   end
 
   @doc false
@@ -88,7 +96,7 @@ defmodule Membrane.Core.Telemetry do
         }
       end
 
-    report_event(event, value)
+    report_event(event, value, Enum.find(@telemetry_flags, &(&1 == :links)) != nil)
   end
 
   @doc """
@@ -105,7 +113,7 @@ defmodule Membrane.Core.Telemetry do
         %{path: ComponentPath.get_formatted()}
       end
 
-    report_event(event, value)
+    report_event(event, value, Enum.find(@telemetry_flags, &(&1 == :inits_and_terminates)) != nil)
   end
 
   @doc """
@@ -122,12 +130,12 @@ defmodule Membrane.Core.Telemetry do
         %{path: ComponentPath.get_formatted()}
       end
 
-    report_event(event, value)
+    report_event(event, value, Enum.find(@telemetry_flags, &(&1 == :inits_and_terminates)) != nil)
   end
 
   # Conditional event reporting of telemetry events
-  defp report_event(event_name, measurement) do
-    if @enable_telemetry do
+  defp report_event(event_name, measurement, enable) do
+    if enable do
       quote do
         :telemetry.execute(
           unquote(event_name),

lib/membrane/telemetry.ex

@@ -1,14 +1,13 @@
 defmodule Membrane.Telemetry do
   @moduledoc """
   Defines basic telemetry event types used by Membrane's Core.
+
   Membrane uses [Telemetry Package](https://hex.pm/packages/telemetry) for instrumentation and does not store or save any measurements by itself.
 
   It is user's responsibility to use some sort of metrics reporter
   that will be attached to `:telemetry` package to consume and process generated measurements.
 
   ## Instrumentation
-  `Membrane.Telemetry` publishes functions that return described below event names.
-
   The following events are published by Membrane's Core with following measurement types and metadata:
 
     * `[:membrane, :metric, :value]` - used to report metrics, such as input buffer's size inside functions, incoming events and received caps.
@@ -27,11 +26,39 @@ defmodule Membrane.Telemetry do
         * Measurement: `t:init_or_terminate_event_value_t/0`
         * Metadata: `%{}`
 
-  The measurements are reported only when application using Membrane Core specifies following in compile-time config file:
+
+  ## Enabling certain metrics/events
+  A lot of events can happen literally hundreds times per second such as registering that a buffer has been sent/processed.
+
+  This behaviour can come with a great performance penalties but may be helpful for certain discoveries. To avoid any runtime overhead
+  when the reporting is not necessary all metrics/events are hidden behind a compile-time feature flags.
+  To enable a particular measurement one must recompile membrane core with the following snippet put inside
+  user's application `config.exs` file:
 
       config :membrane_core,
-        enable_telemetry: true
+        telemetry_flags: [
+          :flag_name,
+          ...,
+          {:metrics, [list of metrics]}
+          ...
+        ]
+
+  Available flags are (those are of a very low overhead):
+  * `:links` - enables new links notifications
+  * `:inits_and_terminates` - enables notifications of `init` and `terminate` events for elements/bins/pipelines
+
+
+  Additionally one can control which metric values should get measured by passing an option of format :
+  `{:metrics, [list of metrics]}`
 
+  Available metrics are:
+  * `:buffer` - number of buffers being sent from a particular element
+  * `:bitrate` - total number of bits carried by the buffers mentioned above
+  * `:queue_len` - number of messages in element's message queue during GenServer's `handle_info` invocation
+  * `:caps` - indicates that given element has received new caps, value always equals '1'
+  * `:event` - indicates that given element has received a new event, value always equals '1'
+  * `:store` - reports the current size of a input buffer when storing a new buffer
+  * `:take_and_demand` - reports the current size of a input buffer when taking buffers and making a new demand
   """
 
   @type event_name_t :: [atom(), ...]