Metrics synchronous instruments

api/metrics/+opentelemetry/+metrics/MeterProvider.m

@@ -4,7 +4,7 @@
 
     % Copyright 2023 The MathWorks, Inc.
 
-    properties (Access={?opentelemetry.sdk.metrics.MeterProvider})
+    properties (Access={?opentelemetry.sdk.metrics.MeterProvider, ?opentelemetry.sdk.metrics.Cleanup})
         Proxy   % Proxy object to interface C++ code
     end
 
@@ -59,4 +59,11 @@ function setMeterProvider(obj)
             obj.Proxy.setMeterProvider();
         end
     end
+
+    methods(Access=?opentelemetry.sdk.metrics.Cleanup)
+        function postShutdown(obj)
+            % POSTSHUTDOWN  Handle post-shutdown tasks
+            obj.Proxy.postShutdown();
+        end
+    end
 end

api/metrics/+opentelemetry/+metrics/getMeter.m

@@ -0,0 +1,17 @@
+function meter = getMeter(mname, varargin)
+% Create a meter from the global meter provider instance 
+%    M = OPENTELEMETRY.METRICS.GETMETER(NAME) returns a meter with the
+%    specified name created from the global meter provider instance.
+%
+%    M = OPENTELEMETRY.METRICS.GETMETER(NAME, VERSION, SCHEMA) also
+%    specifies the meter version and the URL that documents the schema
+%    of the generated metrics.
+%
+%    See also OPENTELEMETRY.SDK.METRICS.METERPROVIDER,
+%    OPENTELEMETRY.METRICS.METER,
+%    OPENTELEMETRY.METRICS.PROVIDER.SETMETERPROVIDER
+
+% Copyright 2023 The MathWorks, Inc.
+
+provider = opentelemetry.metrics.Provider.getMeterProvider();
+meter = getMeter(provider, mname, varargin{:});

api/metrics/include/opentelemetry-matlab/metrics/MeterProviderProxy.h

@@ -13,17 +13,15 @@
 #include "opentelemetry/metrics/noop.h"
 
 namespace metrics_api = opentelemetry::metrics;
-namespace metrics_sdk = opentelemetry::sdk::metrics;
-namespace metrics_exporter = opentelemetry::exporter::otlp;
 namespace nostd = opentelemetry::nostd;
-namespace resource = opentelemetry::sdk::resource;
 
 namespace libmexclass::opentelemetry {
 class MeterProviderProxy : public libmexclass::proxy::Proxy {
   public:
     MeterProviderProxy(nostd::shared_ptr<metrics_api::MeterProvider> mp) : CppMeterProvider(mp) {
         REGISTER_METHOD(MeterProviderProxy, getMeter);
         REGISTER_METHOD(MeterProviderProxy, setMeterProvider);
+        REGISTER_METHOD(MeterProviderProxy, postShutdown);
     }
 
     // Static make method should only be used by getMeterProvider. It gets the global instance 
@@ -39,6 +37,12 @@ class MeterProviderProxy : public libmexclass::proxy::Proxy {
     nostd::shared_ptr<metrics_api::MeterProvider> getInstance() {
         return CppMeterProvider;
     }
+
+    void postShutdown(libmexclass::proxy::method::Context& context) {
+	    // Replace meter provider with a no-op instance. Subsequent metrics won't be recorded
+	    nostd::shared_ptr<metrics_api::MeterProvider> noop(new metrics_api::NoopMeterProvider);
+        CppMeterProvider.swap(noop);
+    }
 
   protected:
     nostd::shared_ptr<metrics_api::MeterProvider> CppMeterProvider;

sdk/metrics/+opentelemetry/+sdk/+metrics/Cleanup.m

@@ -0,0 +1,63 @@
+classdef Cleanup
+% Clean up methods for MeterProvider in the API
+
+% Copyright 2023 The MathWorks, Inc.
+
+    methods (Static)
+        function success = shutdown(mp)
+            % SHUTDOWN  Shutdown 
+            %    SUCCESS = SHUTDOWN(MP) shuts down all metric readers associated with 
+            %    API meter provider MP and return a logical that indicates 
+            %    whether shutdown was successful.
+            %
+            %    See also FORCEFLUSH
+
+            % return false if input is not the right type
+            if isa(mp, "opentelemetry.metrics.MeterProvider")
+                % convert to MeterProvider class in sdk
+                try
+                    mpsdk = opentelemetry.sdk.metrics.MeterProvider(mp.Proxy);
+                catch 
+                    success = false;
+                    return
+                end
+                success = mpsdk.shutdown;
+                postShutdown(mp);
+            else
+                success = false;
+            end
+        end
+
+        function success = forceFlush(mp, timeout)
+            % FORCEFLUSH Force flush
+            %    SUCCESS = FORCEFLUSH(MP) immediately exports all metrics
+            %    that have not yet been exported. Returns a logical that
+            %    indicates whether force flush was successful.
+            %
+            %    SUCCESS = FORCEFLUSH(MP, TIMEOUT) specifies a TIMEOUT
+            %    duration. Force flush must be completed within this time,
+            %    or else it will fail.
+            %
+            %    See also SHUTDOWN
+
+            % return false if input is not the right type
+            if isa(mp, "opentelemetry.metrics.MeterProvider")
+                % convert to MeterProvider class in sdk
+                try
+                    mpsdk = opentelemetry.sdk.metrics.MeterProvider(mp.Proxy);
+                catch
+                    success = false;
+                    return
+                end
+                if nargin < 2 || ~isa(timeout, "duration")
+                    success = mpsdk.forceFlush;
+                else
+                    success = mpsdk.forceFlush(timeout);
+                end
+            else
+                success =  false;
+            end
+        end
+    end
+
+end

sdk/metrics/+opentelemetry/+sdk/+metrics/MeterProvider.m

@@ -4,11 +4,10 @@
 
     % Copyright 2023 The MathWorks, Inc.
 
-    properties (Access=private)
+    properties(Access=private)
         isShutdown (1,1) logical = false
     end
 
-
     properties (Access=public)
         MetricReader
     end
@@ -48,34 +47,49 @@
                 optionvalues
             end
 
-            validnames = ["Resource"];
-            resourcekeys = string.empty();
-            resourcevalues = {};
-            resource = dictionary(resourcekeys, resourcevalues);
-            for i = 1:length(optionnames)
-                namei = validatestring(optionnames{i}, validnames);
-                valuei = optionvalues{i};
-                if strcmp(namei, "Resource")
-                    if ~isa(valuei, "dictionary")
-                        error("opentelemetry:sdk:metrics:MeterProvider:InvalidResourceType", ...
-                            "Attibutes input must be a dictionary.");
-                    end
-                    resource = valuei;
-                    resourcekeys = keys(valuei);
-                    resourcevalues = values(valuei,"cell");
-                    % collapse one level of cells, as this may be due to
-                    % a behavior of dictionary.values
-                    if all(cellfun(@iscell, resourcevalues))
-                        resourcevalues = [resourcevalues{:}];
+            % explicit call to superclass constructor to make it a no-op
+            [email protected]("skip");
+
+            if isa(reader, "libmexclass.proxy.Proxy")
+                % This code branch is used to support conversion from API
+                % MeterProvider to SDK equivalent, needed internally by
+                % opentelemetry.sdk.metrics.Cleanup
+                mpproxy = reader;  % rename the variable
+                assert(mpproxy.Name == "libmexclass.opentelemetry.MeterProviderProxy");
+                obj.Proxy = libmexclass.proxy.Proxy("Name", ...
+                    "libmexclass.opentelemetry.sdk.MeterProviderProxy", ...
+                    "ConstructorArguments", {mpproxy.ID});
+                % leave other properties unassigned, they won't be used
+            else
+                validnames = ["Resource"];
+                resourcekeys = string.empty();
+                resourcevalues = {};
+                resource = dictionary(resourcekeys, resourcevalues);
+                for i = 1:length(optionnames)
+                    namei = validatestring(optionnames{i}, validnames);
+                    valuei = optionvalues{i};
+                    if strcmp(namei, "Resource")
+                        if ~isa(valuei, "dictionary")
+                            error("opentelemetry:sdk:metrics:MeterProvider:InvalidResourceType", ...
+                                "Attibutes input must be a dictionary.");
+                        end
+                        resource = valuei;
+                        resourcekeys = keys(valuei);
+                        resourcevalues = values(valuei,"cell");
+                        % collapse one level of cells, as this may be due to
+                        % a behavior of dictionary.values
+                        if all(cellfun(@iscell, resourcevalues))
+                            resourcevalues = [resourcevalues{:}];
+                        end
                     end
                 end
+
+                obj.Proxy = libmexclass.proxy.Proxy("Name", ...
+                    "libmexclass.opentelemetry.sdk.MeterProviderProxy", ...
+                    "ConstructorArguments", {reader.Proxy.ID, resourcekeys, resourcevalues});
+                obj.MetricReader = reader;
+                obj.Resource = resource;
             end
-
-            obj.Proxy = libmexclass.proxy.Proxy("Name", ...
-                "libmexclass.opentelemetry.sdk.MeterProviderProxy", ...
-                "ConstructorArguments", {reader.Proxy.ID, resourcekeys, resourcevalues});
-            obj.MetricReader = reader;
-            obj.Resource = resource;
         end
 
         function addMetricReader(obj, reader)
@@ -86,8 +100,13 @@ function addMetricReader(obj, reader)
             obj.Proxy.addMetricReader(reader.Proxy.ID);
             obj.MetricReader = [obj.MetricReader, reader];
         end
-        
+
         function success = shutdown(obj)
+            % SHUTDOWN  Shutdown 
+            %    SUCCESS = SHUTDOWN(MP) shuts down all metric readers associated with meter provider MP
+    	    %    and return a logical that indicates whether shutdown was successful.
+            %
+            %    See also FORCEFLUSH
             if ~obj.isShutdown
                 success = obj.Proxy.shutdown();
                 obj.isShutdown = success;
@@ -96,5 +115,25 @@ function addMetricReader(obj, reader)
             end
         end
 
+        function success = forceFlush(obj, timeout)
+            % FORCEFLUSH Force flush
+            %    SUCCESS = FORCEFLUSH(MP) immediately exports all metrics
+            %    that have not yet been exported. Returns a logical that
+            %    indicates whether force flush was successful.
+            %
+            %    SUCCESS = FORCEFLUSH(MP, TIMEOUT) specifies a TIMEOUT
+            %    duration. Force flush must be completed within this time,
+            %    or else it will fail.
+            %
+            %    See also SHUTDOWN
+            if obj.isShutdown
+                success = false;
+            elseif nargin < 2 || ~isa(timeout, "duration")  % ignore timeout if not a duration
+                success = obj.Proxy.forceFlush();
+            else
+                success = obj.Proxy.forceFlush(milliseconds(timeout)*1000); % convert to microseconds
+            end
+        end
+
     end
 end

sdk/metrics/include/opentelemetry-matlab/sdk/metrics/MeterProviderProxy.h

@@ -39,15 +39,18 @@ namespace resource = opentelemetry::sdk::resource;
 namespace libmexclass::opentelemetry::sdk {
 class MeterProviderProxy : public libmexclass::opentelemetry::MeterProviderProxy {
   public:
-    MeterProviderProxy(nostd::shared_ptr<metrics_api::MeterProvider> mp) : libmexclass::opentelemetry::MeterProviderProxy(mp), CppMeterProvider(mp) {
+    MeterProviderProxy(nostd::shared_ptr<metrics_api::MeterProvider> mp) : libmexclass::opentelemetry::MeterProviderProxy(mp) {
         REGISTER_METHOD(MeterProviderProxy, addMetricReader);
+        REGISTER_METHOD(MeterProviderProxy, shutdown);
+        REGISTER_METHOD(MeterProviderProxy, forceFlush);
     }
 
     static libmexclass::proxy::MakeResult make(const libmexclass::proxy::FunctionArguments& constructor_arguments);
 
     void addMetricReader(libmexclass::proxy::method::Context& context);
 
-  protected:
-    nostd::shared_ptr<metrics_api::MeterProvider> CppMeterProvider;
+    void shutdown(libmexclass::proxy::method::Context& context);
+
+    void forceFlush(libmexclass::proxy::method::Context& context);
 };
 } // namespace libmexclass::opentelemetry

sdk/metrics/src/MeterProviderProxy.cpp

@@ -11,26 +11,38 @@ namespace libmexclass::opentelemetry::sdk {
 libmexclass::proxy::MakeResult MeterProviderProxy::make(const libmexclass::proxy::FunctionArguments& constructor_arguments) {
 
     libmexclass::proxy::MakeResult out;
-
-    matlab::data::TypedArray<uint64_t> readerid_mda = constructor_arguments[0];
-    libmexclass::proxy::ID readerid = readerid_mda[0];
-
-    matlab::data::StringArray resourcenames_mda = constructor_arguments[1];
-    size_t nresourceattrs = resourcenames_mda.getNumberOfElements();
-    matlab::data::CellArray resourcevalues_mda = constructor_arguments[2];
-
-    auto resource_custom = createResource(resourcenames_mda, resourcevalues_mda);
-
-    auto reader = std::static_pointer_cast<PeriodicExportingMetricReaderProxy>(
-	        libmexclass::proxy::ProxyManager::getProxy(readerid))->getInstance();
-    auto p = metrics_sdk::MeterProviderFactory::Create(NULL, std::move(resource_custom));
-    auto *p_sdk = static_cast<metrics_sdk::MeterProvider *>(p.get());
-    p_sdk->AddMetricReader(std::move(reader));
+    if (constructor_arguments.getNumberOfElements() == 1)  {
+        // if only one input, assume it is an API Tracer Provider to support type conversion
+        matlab::data::TypedArray<uint64_t> mpid_mda = constructor_arguments[0];
+        libmexclass::proxy::ID mpid = mpid_mda[0];
+        auto mp = std::static_pointer_cast<libmexclass::opentelemetry::MeterProviderProxy>(
+            libmexclass::proxy::ProxyManager::getProxy(mpid))->getInstance();
+        // check if input can be cast to an SDK Meter Provider 
+        auto mpsdk = dynamic_cast<metrics_sdk::MeterProvider*>(mp.get());
+        if (mpsdk == nullptr) {
+          return libmexclass::error::Error{"opentelemetry:sdk:metrics:Cleanup:UnsetGlobalInstance", 
+          "Clean up operations are not supported if global MeterProvider instance is not set."};
+        }
+        out = std::make_shared<MeterProviderProxy>(nostd::shared_ptr<metrics_api::MeterProvider>(mp));
+    } else {
+        matlab::data::TypedArray<uint64_t> readerid_mda = constructor_arguments[0];
+        libmexclass::proxy::ID readerid = readerid_mda[0];
+
+        matlab::data::StringArray resourcenames_mda = constructor_arguments[1];
+        size_t nresourceattrs = resourcenames_mda.getNumberOfElements();
+        matlab::data::CellArray resourcevalues_mda = constructor_arguments[2];
 
-    auto p_out = nostd::shared_ptr<metrics_api::MeterProvider>(std::move(p));
-
-    out = std::make_shared<MeterProviderProxy>(p_out);
+        auto resource_custom = createResource(resourcenames_mda, resourcevalues_mda);
 
+        auto reader = std::static_pointer_cast<PeriodicExportingMetricReaderProxy>(
+	            libmexclass::proxy::ProxyManager::getProxy(readerid))->getInstance();
+        auto p = metrics_sdk::MeterProviderFactory::Create();
+        auto *p_sdk = static_cast<metrics_sdk::MeterProvider *>(p.get());
+        p_sdk->AddMetricReader(std::move(reader));
+
+        auto p_out = nostd::shared_ptr<metrics_api::MeterProvider>(std::move(p));
+        out = std::make_shared<MeterProviderProxy>(p_out);
+    }
     return out;
 }
 
@@ -44,5 +56,25 @@ void MeterProviderProxy::addMetricReader(libmexclass::proxy::method::Context& co
    return;
 }
 
+void MeterProviderProxy::shutdown(libmexclass::proxy::method::Context& context) {
+    matlab::data::ArrayFactory factory;
+    auto result_mda = factory.createScalar(static_cast<metrics_sdk::MeterProvider&>(*CppMeterProvider).Shutdown());
+    context.outputs[0] = result_mda;
+    nostd::shared_ptr<metrics_api::MeterProvider> noop(new metrics_api::NoopMeterProvider);
+    CppMeterProvider.swap(noop);
+}
+
+void MeterProviderProxy::forceFlush(libmexclass::proxy::method::Context& context) {
+    matlab::data::ArrayFactory factory;
+
+    if (context.inputs.getNumberOfElements() == 0) {
+        context.outputs[0] = factory.createScalar(static_cast<metrics_sdk::MeterProvider&>(*CppMeterProvider).ForceFlush());
+    } else {  // number of inputs > 0
+        matlab::data::TypedArray<double> timeout_mda = context.inputs[0];
+        auto timeout = std::chrono::microseconds(timeout_mda[0]);
+        context.outputs[0] = factory.createScalar(static_cast<metrics_sdk::MeterProvider&>(*CppMeterProvider).ForceFlush(timeout));
+    }
+}
+
 
 } // namespace libmexclass::opentelemetry