Add help texts for metrics

mathworks · Dec 12, 2023 · 97754c9 · 97754c9
1 parent 99f23be
commit 97754c9
Show file tree

Hide file tree

Showing 12 changed files with 263 additions and 86 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 MATLAB&reg; interface to [OpenTelemetry&trade;](https://opentelemetry.io/), based on the [OpenTelemetry Specification](https://opentelemetry.io/docs/reference/specification/). OpenTelemetry is an observability framework for creating and managing telemetry data, such as traces, metrics, and logs. This data can then be sent to an observability back-end for monitoring, alerts, and analysis. 
 
 ### Status
-- Currently only tracing is supported. Metrics and logs will be in the future.
+- Currently only tracing and metrics are supported. Logs will be in the future.
 - This package is supported and has been tested on Windows&reg;, Linux&reg;, and macOS.
 
 ### MathWorks Products (https://www.mathworks.com)
@@ -43,6 +43,7 @@ otelcol --config <otelcol-config-yaml>
 >> addpath <OpenTelemetry MATLAB installdir>
 ```
 ## Examples
+### Tracing
 1. Create a default tracer provider and save it.
 ```
 >> p = opentelemetry.sdk.trace.TracerProvider();
@@ -58,6 +59,22 @@ otelcol --config <otelcol-config-yaml>
 >> sp.endSpan();
 ```
 4. If your collector is configured to display the data, you should see your span displayed. 
+### Metrics
+1. Create a default meter provider and save it.
+```
+>> p = opentelemetry.sdk.metrics.MeterProvider();
+>> setMeterProvider(p);
+```
+2. Create a counter
+```
+>> m = opentelemetry.metrics.getMeter("First Meter");
+>> c = m.createCounter("FirstCounter");
+```
+3. Increment the counter
+```
+>> c.add(10);
+```
+4. If your collector is configured to display the data, you should see your counter displayed after 1 minute.
 
 For more examples, see the "examples" folder.
 

diff --git a/api/metrics/+opentelemetry/+metrics/Counter.m b/api/metrics/+opentelemetry/+metrics/Counter.m
@@ -14,6 +14,16 @@
 
     methods
         function add(obj, value, varargin)
+            % ADD Add to counter value
+            %    ADD(C, VALUE) adds a nonnegative scalar numeric value to
+            %    the counter.
+            %
+            %    ADD(C, VALUE, ATTRIBUTES) also specifies attributes as a
+            %    dictionary
+            %
+            %    ADD(C, VALUE, ATTRNAME1, ATTRVALUE1, ATTRNAME2,
+            %    ATTRVALUE2, ...) specifies attributes as trailing
+            %    name-value pairs.
             obj.processValue(value, varargin{:});
         end
     end

diff --git a/api/metrics/+opentelemetry/+metrics/Histogram.m b/api/metrics/+opentelemetry/+metrics/Histogram.m
@@ -13,6 +13,16 @@
 
     methods
         function record(obj, value, varargin)
+            % RECORD Aggregate a value into a histogram bin
+            %    RECORD(H, VALUE) determine which bin VALUE falls into and
+            %    increment that bin by 1.
+            %
+            %    RECORD(H, VALUE, ATTRIBUTES) also specifies attributes as a
+            %    dictionary
+            %
+            %    RECORD(H, VALUE, ATTRNAME1, ATTRVALUE1, ATTRNAME2,
+            %    ATTRVALUE2, ...) specifies attributes as trailing
+            %    name-value pairs.
             obj.processValue(value, varargin{:});
         end
     end

diff --git a/api/metrics/+opentelemetry/+metrics/Meter.m b/api/metrics/+opentelemetry/+metrics/Meter.m
@@ -30,6 +30,15 @@
     methods
 
         function counter = createCounter(obj, ctname, ctdescription, ctunit)
+            % CREATECOUNTER Create a counter
+            %    C = CREATECOUNTER(M, NAME) creates a counter with the specified
+            %    name. A counter's value can only increase but not
+            %    decrease.
+            %
+            %    C = CREATECOUNTER(M, NAME, DESCRIPTION, UNIT) also 
+            %    specifies a description and a unit.
+            %     
+            %    See also CREATEUPDOWNCOUNTER, CREATEHISTOGRAM
             arguments
                 obj
                 ctname
@@ -38,8 +47,6 @@
             end
             import opentelemetry.common.mustBeScalarString
             ctname = mustBeScalarString(ctname);
-            % cpp-opentelemetry end does not allow string input with spaces,
-            % replace any spaces with underscores as a temporary fix
             ctdescription = mustBeScalarString(ctdescription);
             ctunit = mustBeScalarString(ctunit);
             id = obj.Proxy.createCounter(ctname, ctdescription, ctunit);
@@ -50,6 +57,15 @@
 
 
         function updowncounter = createUpDownCounter(obj, ctname, ctdescription, ctunit)
+            % CREATEUPDOWNCOUNTER Create an UpDownCounter
+            %    C = CREATEUPDOWNCOUNTER(M, NAME) creates an UpDownCounter 
+            %    with the specified name. An UpDownCounter's value can
+            %    increase or decrease.
+            %
+            %    C = CREATEUPDOWNCOUNTER(M, NAME, DESCRIPTION, UNIT) also 
+            %    specifies a description and a unit.
+            %     
+            %    See also CREATECOUNTER, CREATEHISTOGRAM
             arguments
                 obj
                 ctname
@@ -59,8 +75,6 @@
 
             import opentelemetry.common.mustBeScalarString
             ctname = mustBeScalarString(ctname);
-            % cpp-opentelemetry end does not allow string input with spaces,
-            % replace any spaces with underscores as a temporary fix
             ctdescription = mustBeScalarString(ctdescription);
             ctunit = mustBeScalarString(ctunit);
             id = obj.Proxy.createUpDownCounter(ctname, ctdescription, ctunit);
@@ -71,6 +85,16 @@
 
 
         function histogram = createHistogram(obj, hiname, hidescription, hiunit)
+            % CREATEHISTOGRAM Create a histogram
+            %    H = CREATEHISTOGRAM(M, NAME) creates a histogram with the specified
+            %    name. A histogram aggregates values into bins. Bins can be
+            %    customized using a View object.
+            %
+            %    H = CREATEHISTOGRAM(M, NAME, DESCRIPTION, UNIT) also 
+            %    specifies a description and a unit.
+            %     
+            %    See also CREATECOUNTER, CREATEUPDOWNCOUNTER,
+            %    OPENTELEMETRY.SDK.METRICS.VIEW
             arguments
                 obj
                 hiname
@@ -80,8 +104,6 @@
 
             import opentelemetry.common.mustBeScalarString
             hiname = mustBeScalarString(hiname);
-            % cpp-opentelemetry end does not allow string input with spaces,
-            % replace any spaces with underscores as a temporary fix
             hidescription = mustBeScalarString(hidescription);
             hiunit = mustBeScalarString(hiunit);
             id = obj.Proxy.createHistogram(hiname, hidescription, hiunit);

diff --git a/api/metrics/+opentelemetry/+metrics/UpDownCounter.m b/api/metrics/+opentelemetry/+metrics/UpDownCounter.m
@@ -13,6 +13,16 @@
 
     methods
         function add(obj, value, varargin)
+            % ADD Add to UpDownCounter value
+            %    ADD(C, VALUE) adds scalar numeric value to the
+            %    UpDownCounter. VALUE can be positive or negative.
+            %
+            %    ADD(C, VALUE, ATTRIBUTES) also specifies attributes as a
+            %    dictionary
+            %
+            %    ADD(C, VALUE, ATTRNAME1, ATTRVALUE1, ATTRNAME2,
+            %    ATTRVALUE2, ...) specifies attributes as trailing
+            %    name-value pairs.
             obj.processValue(value, varargin{:});
         end
     end

diff --git a/sdk/metrics/+opentelemetry/+sdk/+metrics/MeterProvider.m b/sdk/metrics/+opentelemetry/+sdk/+metrics/MeterProvider.m
@@ -8,23 +8,23 @@
         isShutdown (1,1) logical = false
     end
 
-    properties (Access=public)
-        MetricReader
-        View
-        Resource
+    properties (SetAccess=private)
+        MetricReader  % Metric reader controls how often metrics are exported
+        View          % View object used to customize collected metrics
+        Resource      % Attributes attached to all metrics
     end
 
     methods
         function obj = MeterProvider(reader, optionnames, optionvalues)
             % SDK implementation of meter provider
-            %    MP = OPENTELEMETRY.SDK.METRICS.METERPROVIDER creates a meter 
+            %    MP = OPENTELEMETRY.SDK.METRICS.METERPROVIDER creates a meter
             %    provider that uses a periodic exporting metric reader and default configurations.
             %
             %    MP = OPENTELEMETRY.SDK.METRICS.METERPROVIDER(R) uses metric
-            %    reader R. Currently, the only supported metric reader is the periodic 
-	    %    exporting metric reader.
+            %    reader R. Currently, the only supported metric reader is the periodic
+    	    %    exporting metric reader.
             %
-            %    TP = OPENTELEMETRY.SDK.METRICS.METERPROVIDER(R, PARAM1, VALUE1, 
+            %    TP = OPENTELEMETRY.SDK.METRICS.METERPROVIDER(R, PARAM1, VALUE1,
             %    PARAM2, VALUE2, ...) specifies optional parameter name/value pairs.
             %    Parameters are:
             %       "View"        - View object used to customize collected metrics.
@@ -59,7 +59,7 @@
                     "ConstructorArguments", {mpproxy.ID});
                 % leave other properties unassigned, they won't be used
             else
-                validnames = ["Resource"];
+                validnames = "Resource";
                 resourcekeys = string.empty();
                 resourcevalues = {};
                 resource = dictionary(resourcekeys, resourcevalues);
@@ -89,21 +89,31 @@
                 obj.Resource = resource;
             end
         end
-        
+
         function addMetricReader(obj, reader)
-        arguments
-     	    obj
-            reader (1,1) {mustBeA(reader, "opentelemetry.sdk.metrics.PeriodicExportingMetricReader")}
-        end
+            % ADDMETRICREADER Add an additional metric reader
+            %    ADDMETRICREADER(MP, R) adds an additional metric reader
+            %    R to the list of metric readers used by meter provider
+            %    MP.
+            %
+            %    See also ADDVIEW, OPENTELEMETRY.SDK.METRICS.PERIODICEXPORTINGMETRICREADER
+            arguments
+         	    obj
+                reader (1,1) {mustBeA(reader, "opentelemetry.sdk.metrics.PeriodicExportingMetricReader")}
+            end
             obj.Proxy.addMetricReader(reader.Proxy.ID);
             obj.MetricReader = [obj.MetricReader, reader];
         end
 
         function addView(obj, view)
-        arguments
-     	    obj
-            view (1,1) {mustBeA(view, "opentelemetry.sdk.metrics.View")}
-        end
+            % ADDVIEW Add an additional view
+            %    ADDVIEW(MP, V) adds an additional view V. 
+            %
+            %    See also ADDMETRICREADER, OPENTELEMETRY.SDK.METRICS.VIEW
+            arguments
+         	    obj
+                view (1,1) {mustBeA(view, "opentelemetry.sdk.metrics.View")}
+            end
             obj.Proxy.addView(view.Proxy.ID);
             obj.View = [obj.View, view];
         end

diff --git a/sdk/metrics/+opentelemetry/+sdk/+metrics/MetricExporter.m b/sdk/metrics/+opentelemetry/+sdk/+metrics/MetricExporter.m
@@ -24,7 +24,7 @@
     methods
 	    function obj = set.PreferredAggregationTemporality(obj, temporality)
             temporality = validatestring(temporality, ["cumulative", "delta"]);
-            obj.Proxy.setTemporality(temporality);
+            obj.Proxy.setTemporality(temporality); %#ok<MCSUP>
             obj.PreferredAggregationTemporality = temporality;
         end
 

diff --git a/sdk/metrics/+opentelemetry/+sdk/+metrics/PeriodicExportingMetricReader.m b/sdk/metrics/+opentelemetry/+sdk/+metrics/PeriodicExportingMetricReader.m
@@ -1,5 +1,6 @@
 classdef PeriodicExportingMetricReader < matlab.mixin.Heterogeneous
-% Base class of metric reader
+% Periodic exporting metric reader passes collected metrics to an exporter
+% periodically at a fixed time interval.
 
 % Copyright 2023 The MathWorks, Inc.
 
@@ -12,13 +13,35 @@
     end
 
     properties
-        Interval (1,1) duration = minutes(1)  
-        Timeout (1,1) duration = seconds(30)
+        Interval (1,1) duration = minutes(1)  % Time interval between exports
+        Timeout (1,1) duration = seconds(30)  % Maximum time before export is timed out and gets aborted
     end
 
-    methods %(Access=?opentelemetry.sdk.metrics.MeterProvider)
+    methods
         function obj = PeriodicExportingMetricReader(metricexporter, optionnames, optionvalues)
-
+            % Periodic exporting metric reader passes collected metrics to
+            % an exporter periodically at a fixed time interval.
+            %    R = OPENTELEMETRY.SDK.METRICS.PERIODICEXPORTINGMETRICREADER
+            %    creates a periodic exporting metric reader that exports 
+            %    every minute using an OTLP HTTP exporter, which exports in 
+            %    OpenTelemetry Protocol (OTLP) format through HTTP.
+            %
+            %    R = OPENTELEMETRY.SDK.METRICS.PERIODICEXPORTINGMETRICREADER(EXP)
+            %    specifies the metric exporter. Supported metric exporters
+            %    are OTLP HTTP exporter and OTLP gRPC exporter.
+            %
+            %    R = OPENTELEMETRY.SDK.METRICS.PERIODICEXPORTINGMETRICREADER(
+            %    EXP, PARAM1, VALUE1, PARAM2, VALUE2, ...) specifies
+            %    optional parameter name/value pairs. Parameters are:
+            %       "Interval" - Time interval between exports specified as
+            %                    a duration. Default is 1 minute.
+            %       "Timeout"  - Maximum time before export is timed out
+            %                    and gets aborted, specified as a duration.  
+            %                    Default is 30 seconds.
+            %
+            %    See also OPENTELEMETRY.EXPORTERS.OTLP.OTLPHTTPMETRICEXPORTER,
+            %    OPENTELEMETRY.EXPORTERS.OTLP.OTLPGRPCMETRICEXPORTER, 
+            %    OPENTELEMETRY.SDK.METRICS.METERPROVIDER
             arguments
       	       metricexporter {mustBeA(metricexporter, "opentelemetry.sdk.metrics.MetricExporter")} = ...
                    opentelemetry.exporters.otlp.defaultMetricExporter()