Merge pull request #727 from whatyouhide/al/resource-docs

Documentation for `otel_resource*` modules

Author: tsloughter

apps/opentelemetry/src/otel_resource.erl

@@ -14,11 +14,19 @@
 %%
 %% @doc A Resource is attributes representing the entity producing
 %% telemetry. For example, by default the language (Erlang), name of this
-%% library (opentelemetry) and version of this library are included in
+%% library (`opentelemetry'), and version of this library are included in
 %% the Resource.
 %%
 %% This module provides the functional interface for working with the
 %% resource record.
+%%
+%% The `opentelemetry' library supports <i>resource detectors</i> to
+%% detect attributes to include in the Resource. See {@link otel_resource_detector}
+%% for the behaviour to detect resources, and the {@link otel_resource_app_env}
+%% and {@link otel_resource_env_var} modules for built-in implementations.
+%%
+%% See the <a href="https://opentelemetry.io/docs/concepts/resources/">
+%% OpenTelemetry Resource documentation</a> for more information on Resources.
 %% @end
 %%%-----------------------------------------------------------------------
 -module(otel_resource).
@@ -32,22 +40,33 @@
 
 -type key() :: unicode:latin1_binary() | atom().
 %% values allowed in attributes of a resource are limited
+
 -type value() :: unicode:latin1_binary() | integer() | float() | boolean().
+%% A resource value.
+
 -type schema_url() :: uri_string:uri_string().
+%% A schema URL for the resource.
 
 -define(MAX_LENGTH, 255).
 
 -record(resource, {schema_url :: schema_url() | undefined,
                    attributes :: otel_attributes:t()}).
+
 -type t() :: #resource{} | undefined.
+%% The type that represents a resource.
 
 -export_type([t/0]).
 
+%% @equiv create(Attributes, undefined)
 -spec create(#{key() => value()} | [{key(), value()}]) -> t().
 create(Attributes) ->
     create(Attributes, undefined).
 
-%% verifies each key and value and drops any that don't pass verification
+%% @doc Creates a new resources from the given map or list of `Attributes' and
+%% with the given `SchemaUrl'.
+%%
+%%
+%% This function verifies each key and value, and drops any that don't pass verification.
 -spec create(#{key() => value()} | [{key(), value()}], schema_url() | undefined) -> t().
 create(Map, SchemaUrl) when is_map(Map) ->
     create(maps:to_list(Map), SchemaUrl);
@@ -69,18 +88,24 @@ create(List, SchemaUrl) when is_list(List) ->
     #resource{schema_url=SchemaUrl,
               attributes=otel_attributes:new(List1, 128, 255)}.
 
+%% @doc Returns the schema URL of the resource.
 -spec schema_url(t()) -> schema_url() | undefined.
 schema_url(#resource{schema_url=Schema}) ->
     Schema;
 schema_url(_) ->
     undefined.
 
+%% @doc Returns the attributes of the given `Resource'.
+%%
+%% This function returns `undefined' only in case `Resource' is an invalid argument
+%% (not a resource record).
 -spec attributes(t()) -> otel_attributes:t() | undefined.
 attributes(#resource{attributes=Attributes}) ->
     Attributes;
 attributes(_) ->
     undefined.
 
+%% @doc Returns `true' if `Key' is valid and part of the given resource.
 -spec is_key(key(), t()) -> boolean().
 is_key(K, #resource{attributes=Attributes}) ->
     case try_check_key(K, false) of
@@ -92,14 +117,16 @@ is_key(K, #resource{attributes=Attributes}) ->
 is_key(_, _) ->
     false.
 
-%% in case of collision the updating, first argument, resource takes precedence.
+%% @doc Merges the two given resources.
+%%
+%% In case of collision, the first argument (`Resource') takes precedence.
 -spec merge(t(), t()) -> t().
 merge(#resource{schema_url=NewSchemaUrl,
-                attributes=NewAttributes}, Current=#resource{schema_url=CurrentSchemaUrl,
+                attributes=NewAttributes}, CurrentResource=#resource{schema_url=CurrentSchemaUrl,
                                                              attributes=CurrentAttributes}) ->
     SchameUrl = merge_schema_url(NewSchemaUrl, CurrentSchemaUrl),
     NewMap = otel_attributes:map(NewAttributes),
-    Current#resource{schema_url=SchameUrl,
+    CurrentResource#resource{schema_url=SchameUrl,
                      attributes=otel_attributes:set(NewMap, CurrentAttributes)}.
 
 %%

apps/opentelemetry/src/otel_resource_app_env.erl

@@ -12,13 +12,23 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc Adds attributes to the `Resource' based on the value of `resource'
+%% @doc Resource detector ({@link otel_resource_detector}) which adds attributes
+%% to the `Resource' based on the value of `resource'
 %% in the `opentelemetry' application's environment.
 %%
-%%     [{service, #{name => "service-name",
-%%                  namespace => "service-namespace"}]
+%% For example, if the `opentelemetry' application environment has the following
+%% configuration under the `resource' key:
 %%
-%% Results in the `Resource' attributes `service.name' and `service.namespace'.
+%% ```
+%% [{service, #{name => "myservice",
+%%              namespace => "mynamespace"}}]
+%% '''
+%%
+%% then it results in the `Resource' attributes `service.name' and `service.namespace'
+%% set to `myservice' and `mynamespace"}}]' respectively.
+%%
+%% This detector is on by default (see the default configuration for `resource_detectors' in the
+%% `opentelemetry' application environment).
 %% @end
 %%%-----------------------------------------------------------------------
 -module(otel_resource_app_env).
@@ -28,12 +38,14 @@
 -export([get_resource/1,
          parse/1]).
 
+%% @private
 get_resource(_Config) ->
     Attributes = parse(application:get_env(opentelemetry, resource, #{})),
     otel_resource:create(Attributes).
 
 %%
 
+%% @private
 parse(Attributes) when is_map(Attributes) ->
     parse(maps:to_list(Attributes));
 parse(Attributes) when is_list(Attributes) ->

apps/opentelemetry/src/otel_resource_detector.erl

@@ -15,12 +15,16 @@
 %% @doc Resource detectors are responsible for reading in attributes about
 %% the runtime environment of a node (such as an environment variable or
 %% some metadata endpoint provided by a cloud host) and returning a
-%% `otel_resource:t()' made from those attributes.
+%% {@link otel_resource:t()} made from those attributes.
 %%
-%% The state machine will spawn a process for each detector and collect the
-%% results of running each and merge in the order they are defined. Once in
-%% the `ready' state it will reply to `get_resource' calls with the final
-%% `otel_resource:t()'.
+%% This module is meant for users who intend to write their own resource
+%% detectors.
+%%
+%% This behaviour is a state machine (started by the `opentelemetry' application)
+%%  which spawns a process for each detector, collects the
+%% results of running each, and merges them in the order they are defined. Once the
+%% state machine process is ready, it will reply to {@link get_resource/1}
+%% calls with the final {@link otel_resource:t()}.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_resource_detector).
@@ -36,6 +40,8 @@
          handle_event/4]).
 
 -callback get_resource(term()) -> otel_resource:t().
+%% Function that takes the configuration of a resource detector 
+%% and returns a resource.
 
 -type detector() :: module() | {module(), term()}.
 
@@ -46,15 +52,24 @@
                detectors        :: [detector()],
                detector_timeout :: integer()}).
 
+%% @private
 -spec start_link(Config) -> {ok, pid()} | ignore | {error, term()} when
               Config :: #{resource_detectors := [module()],
                           resource_detector_timeout := integer()}.
 start_link(Config) ->
     gen_statem:start_link({local, ?MODULE}, ?MODULE, [Config], []).
 
+%% @equiv get_resource(6000)
+-spec get_resource() -> otel_resource:t().
 get_resource() ->
     get_resource(6000).
 
+%% @doc Gets the resource formed by detecting attributes through resource
+%% detectors.
+%%
+%% If the call doesn't complete within the given `Timeout' then an empty
+%% resource is returned.
+-spec get_resource(timeout()) -> otel_resource:t().
 get_resource(Timeout) ->
     try gen_statem:call(?MODULE, get_resource, Timeout)
     catch
@@ -67,6 +82,7 @@ get_resource(Timeout) ->
             otel_resource:create([])
     end.
 
+%% @private
 init([#{resource_detectors := Detectors,
         resource_detector_timeout := DetectorTimeout}]) ->
     process_flag(trap_exit, true),
@@ -76,9 +92,11 @@ init([#{resource_detectors := Detectors,
                            detector_timeout=DetectorTimeout},
      [{next_event, internal, spawn_detectors}]}.
 
+%% @private
 callback_mode() ->
     [handle_event_function, state_enter].
 
+%% @private
 handle_event(enter, _, ready, Data=#data{resource=Resource}) ->
     NewResource = default_resource_attributes(Resource),
     {keep_state, Data#data{resource=NewResource}};

apps/opentelemetry/src/otel_resource_env_var.erl

@@ -12,8 +12,15 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc Resource detector ({@link otel_resource_detector}) which adds attributes
+%% to the `Resource' based on environment variables.
 %%
+%% This resource detector reads the `OTEL_RESOURCE_ATTRIBUTES' environment
+%% variable and parses it as a comma-separated list of key-value pairs. For
+% example, `key1=val1,key2=val2'.
+%%
+%% This detector is on by default (see the default configuration for `resource_detectors' in the
+%% `opentelemetry' application environment).
 %% @end
 %%%-----------------------------------------------------------------------
 -module(otel_resource_env_var).
@@ -27,11 +34,13 @@
 -define(LABEL_LIST_SPLITTER, ",").
 -define(LABEL_KEY_VALUE_SPLITTER, "=").
 
+%% @private
 get_resource(_Config) ->
     otel_resource:create(parse(os:getenv(?OS_ENV))).
 
 %%
 
+%% @private
 -spec parse(false | string()) -> list().
 parse(false) ->
     [];