From 74e0df80ec16019155c6ebbcaad2fe85942d1e22 Mon Sep 17 00:00:00 2001 From: "feliks.pobiedzinski@swmansion.com" Date: Mon, 3 Mar 2025 15:12:34 +0100 Subject: [PATCH 1/5] Improve telemetry docs --- lib/membrane/telemetry.ex | 26 +++++++++++++++----------- mix.exs | 2 +- 2 files changed, 16 insertions(+), 12 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..6ec207dcf 100644 --- a/mix.exs +++ b/mix.exs @@ -110,13 +110,13 @@ defmodule Membrane.Mixfile do ~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($|\.)/ From e98abe0e283806c09672f02bb78a90795eccaa4a Mon Sep 17 00:00:00 2001 From: "feliks.pobiedzinski@swmansion.com" Date: Mon, 3 Mar 2025 16:19:59 +0100 Subject: [PATCH 2/5] Add new modules to proper docs categories --- mix.exs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/mix.exs b/mix.exs index 6ec207dcf..6019ca267 100644 --- a/mix.exs +++ b/mix.exs @@ -102,7 +102,12 @@ defmodule Membrane.Mixfile do ~r/^Membrane\.Endpoint($|\.)/, ~r/^Membrane\.Sink($|\.)/, ~r/^Membrane\.Source($|\.)/, - ~r/^Membrane\.Element($|\.)/ + ~r/^Membrane\.Element($|\.)/, + ~r/^Membrane\.Connector($|\.)/, + ~r/^Membrane\.Fake($|\.)/, + ~r/^Membrane\.Debug($|\.)/, + ~r/^Membrane\.Tee($|\.)/, + ~r/^Membrane\.Funnel($|\.)/ ], Parent: [~r/^Membrane\.(Parent|ChildrenSpec)($|\.)/], Child: [~r/^Membrane\.(Child|ChildEntry)($|\.)/], From 615d753ea2d7f1cea29f8f94e6e6724a6d037050 Mon Sep 17 00:00:00 2001 From: "feliks.pobiedzinski@swmansion.com" Date: Mon, 3 Mar 2025 16:23:29 +0100 Subject: [PATCH 3/5] Add helper elements to docs categories --- mix.exs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/mix.exs b/mix.exs index 6019ca267..808474ef6 100644 --- a/mix.exs +++ b/mix.exs @@ -102,12 +102,7 @@ defmodule Membrane.Mixfile do ~r/^Membrane\.Endpoint($|\.)/, ~r/^Membrane\.Sink($|\.)/, ~r/^Membrane\.Source($|\.)/, - ~r/^Membrane\.Element($|\.)/, - ~r/^Membrane\.Connector($|\.)/, - ~r/^Membrane\.Fake($|\.)/, - ~r/^Membrane\.Debug($|\.)/, - ~r/^Membrane\.Tee($|\.)/, - ~r/^Membrane\.Funnel($|\.)/ + ~r/^Membrane\.Element($|\.)/ ], Parent: [~r/^Membrane\.(Parent|ChildrenSpec)($|\.)/], Child: [~r/^Membrane\.(Child|ChildEntry)($|\.)/], @@ -117,6 +112,13 @@ defmodule Membrane.Mixfile do Logging: [~r/^Membrane\.Logger($|\.)/], Telemetry: [~r/^Membrane\.Telemetry($|\.)/], Testing: [~r/^Membrane\.Testing($|\.)/], + "Helper Elements": [ + ~r/^Membrane\.Connector($|\.)/, + ~r/^Membrane\.Fake($|\.)/, + ~r/^Membrane\.Debug($|\.)/, + ~r/^Membrane\.Tee($|\.)/, + ~r/^Membrane\.Funnel($|\.)/ + ], Utils: [ ~r/^Membrane\.Clock($|\.)/, ~r/^Membrane\.Sync($|\.)/, From 5debc7d3f53354ad94b006b8aaa5a880e56c87b1 Mon Sep 17 00:00:00 2001 From: "feliks.pobiedzinski@swmansion.com" Date: Mon, 3 Mar 2025 16:25:09 +0100 Subject: [PATCH 4/5] Move filter aggregator to another doc category --- mix.exs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mix.exs b/mix.exs index 808474ef6..754ecef54 100644 --- a/mix.exs +++ b/mix.exs @@ -98,7 +98,6 @@ defmodule Membrane.Mixfile do Bin: [~r/^Membrane\.Bin($|\.)/], Element: [ ~r/^Membrane\.Filter($|\.)/, - ~r/^Membrane\.FilterAggregator($|\.)/, ~r/^Membrane\.Endpoint($|\.)/, ~r/^Membrane\.Sink($|\.)/, ~r/^Membrane\.Source($|\.)/, @@ -117,7 +116,8 @@ defmodule Membrane.Mixfile do ~r/^Membrane\.Fake($|\.)/, ~r/^Membrane\.Debug($|\.)/, ~r/^Membrane\.Tee($|\.)/, - ~r/^Membrane\.Funnel($|\.)/ + ~r/^Membrane\.Funnel($|\.)/, + ~r/^Membrane\.FilterAggregator($|\.)/ ], Utils: [ ~r/^Membrane\.Clock($|\.)/, From 29364e8474cf01b87a996f955d664823aaac54c8 Mon Sep 17 00:00:00 2001 From: "feliks.pobiedzinski@swmansion.com" Date: Mon, 3 Mar 2025 16:26:18 +0100 Subject: [PATCH 5/5] Change the order of categories --- mix.exs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/mix.exs b/mix.exs index 754ecef54..74585117a 100644 --- a/mix.exs +++ b/mix.exs @@ -103,14 +103,6 @@ defmodule Membrane.Mixfile do ~r/^Membrane\.Source($|\.)/, ~r/^Membrane\.Element($|\.)/ ], - 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($|\.)/], "Helper Elements": [ ~r/^Membrane\.Connector($|\.)/, ~r/^Membrane\.Fake($|\.)/, @@ -119,6 +111,14 @@ defmodule Membrane.Mixfile do ~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($|\.)/,