From 0430930e39916891b403a6ba5b1dbe1564768229 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Feliks=20Pobiedzi=C5=84ski?=
 <38541925+FelonEkonom@users.noreply.github.com>
Date: Mon, 3 Mar 2025 16:31:33 +0100
Subject: [PATCH] Improve telemetry docs (and not only) (#949)

* Improve telemetry docs

* Add new modules to proper docs categories

* Add helper elements to docs categories

* Move filter aggregator to another doc category

* Change the order of categories
---
 lib/membrane/telemetry.ex | 26 +++++++++++++++-----------
 mix.exs                   | 11 +++++++++--
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/lib/membrane/telemetry.ex b/lib/membrane/telemetry.ex
index 493ad0f7e..086d2838b 100644
--- a/lib/membrane/telemetry.ex
+++ b/lib/membrane/telemetry.ex
@@ -11,13 +11,15 @@ defmodule Membrane.Telemetry do
   The following telemetric events are published by Membrane's Core components:
 
     * `[:membrane, :element | :bin | :pipeline, callback, :start | :stop | :exception]` -
-    where callback is any possible handle_* function defined for a component.
+    where `callback` is any possible `handle_*` function defined for a component. Metadata
+    passed to these events is `t:callback_span_metadata/0`.
       * `:start` - when the components begins callback's execution
       * `:stop` - when the components finishes callback's execution
       * `:exception` - when the component crashes during callback's execution
 
     * `[:membrane, :datapoint, datapoint_type]` -
-    where datapoint_type is any of the available datapoint types (see below)
+    where datapoint_type is any of the available datapoint types (see below).
+    Metadata passed to these events is `t:datapoint_metadata/0`.
 
   ## Enabling specific datapoints
   A lot of datapoints can happen hundreds times per second such as registering that a buffer has been sent/processed.
@@ -62,15 +64,17 @@ defmodule Membrane.Telemetry do
           Element.CallbackContext.t() | Bin.CallbackContext.t() | Pipeline.CallbackContext.t()
 
   @typedoc """
-  Metadata included with each telemetry component's handler profiled
-  * callback - name of the callback function
-  * callback_args - arguments passed to the callback
-  * callback_context - context of the callback consistent with Membrane.*.CallbackContext
-  * component_path - path of the component in the pipeline consistent with t:ComponentPath.path/0
-  * component_type - atom representation of the base component type
-  * monotonic_time - monotonic time when the callback was executed in native time unit
-  * state_before_callback - state of the component before the callback execution
-  * state_after_callback - state of the component after the callback execution, it's `nil` on :start and :exception events
+  Metadata passed to telemetry events emitted on component's callbacks.
+
+  Fields:
+  * `callback` - name of the callback function
+  * `callback_args` - arguments passed to the callback
+  * `callback_context` - context of the callback consistent with Membrane.*.CallbackContext
+  * `component_path` - path of the component in the pipeline consistent with t:ComponentPath.path/0
+  * `component_type` - atom representation of the base component type
+  * `monotonic_time` - monotonic time when the callback was executed in native time unit
+  * `state_before_callback` - state of the component before the callback execution
+  * `state_after_callback` - state of the component after the callback execution, it's `nil` on :start and :exception events
   """
   @type callback_span_metadata :: %{
           callback: atom(),
diff --git a/mix.exs b/mix.exs
index 398e44e8a..74585117a 100644
--- a/mix.exs
+++ b/mix.exs
@@ -98,25 +98,32 @@ defmodule Membrane.Mixfile do
         Bin: [~r/^Membrane\.Bin($|\.)/],
         Element: [
           ~r/^Membrane\.Filter($|\.)/,
-          ~r/^Membrane\.FilterAggregator($|\.)/,
           ~r/^Membrane\.Endpoint($|\.)/,
           ~r/^Membrane\.Sink($|\.)/,
           ~r/^Membrane\.Source($|\.)/,
           ~r/^Membrane\.Element($|\.)/
         ],
+        "Helper Elements": [
+          ~r/^Membrane\.Connector($|\.)/,
+          ~r/^Membrane\.Fake($|\.)/,
+          ~r/^Membrane\.Debug($|\.)/,
+          ~r/^Membrane\.Tee($|\.)/,
+          ~r/^Membrane\.Funnel($|\.)/,
+          ~r/^Membrane\.FilterAggregator($|\.)/
+        ],
         Parent: [~r/^Membrane\.(Parent|ChildrenSpec)($|\.)/],
         Child: [~r/^Membrane\.(Child|ChildEntry)($|\.)/],
         Communication: [
           ~r/^Membrane\.(Buffer|Payload|StreamFormat|Event|EventProtocol|ChildNotification|ParentNotification|Pad|KeyframeRequestEvent|RemoteStream)($|\.)/
         ],
         Logging: [~r/^Membrane\.Logger($|\.)/],
+        Telemetry: [~r/^Membrane\.Telemetry($|\.)/],
         Testing: [~r/^Membrane\.Testing($|\.)/],
         Utils: [
           ~r/^Membrane\.Clock($|\.)/,
           ~r/^Membrane\.Sync($|\.)/,
           ~r/^Membrane\.Time($|\.)/,
           ~r/^Membrane\.Playback($|\.)/,
-          ~r/^Membrane\.Telemetry($|\.)/,
           ~r/^Membrane\.ComponentPath($|\.)/,
           ~r/^Membrane\.ResourceGuard($|\.)/,
           ~r/^Membrane\.UtilitySupervisor($|\.)/