Skip to content

Commit 5b3cff0

Browse files
duncanpoduncanpo
authored
Merge pull request #161 from mathworks/autotrace
Autotrace
2 parents e2ace2e + e81c793 commit 5b3cff0

File tree

10 files changed

+510
-0
lines changed

10 files changed

+510
-0
lines changed

‎CMakeLists.txt

+2
Original file line numberDiff line numberDiff line change
@@ -476,6 +476,7 @@ set(TRACE_SDK_MATLAB_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/sdk/trace/+opentelemetr
476476
set(METRICS_SDK_MATLAB_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/sdk/metrics/+opentelemetry)
477477
set(LOGS_SDK_MATLAB_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/sdk/logs/+opentelemetry)
478478
set(COMMON_SDK_MATLAB_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/sdk/common/+opentelemetry)
479+
set(AUTO_INSTRUMENTATION_MATLAB_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/auto-instrumentation/+opentelemetry)
479480
set(EXPORTER_MATLAB_SOURCES
480481
${CMAKE_CURRENT_SOURCE_DIR}/exporters/otlp/+opentelemetry/+exporters/+otlp/defaultSpanExporter.m
481482
${CMAKE_CURRENT_SOURCE_DIR}/exporters/otlp/+opentelemetry/+exporters/+otlp/defaultMetricExporter.m
@@ -510,6 +511,7 @@ install(DIRECTORY ${TRACE_SDK_MATLAB_SOURCES} DESTINATION .)
510511
install(DIRECTORY ${METRICS_SDK_MATLAB_SOURCES} DESTINATION .)
511512
install(DIRECTORY ${LOGS_SDK_MATLAB_SOURCES} DESTINATION .)
512513
install(DIRECTORY ${COMMON_SDK_MATLAB_SOURCES} DESTINATION .)
514+
install(DIRECTORY ${AUTO_INSTRUMENTATION_MATLAB_SOURCES} DESTINATION .)
513515
install(FILES ${EXPORTER_MATLAB_SOURCES} DESTINATION ${OTLP_EXPORTERS_DIR})
514516
if(WITH_OTLP_HTTP)
515517
install(FILES ${OTLP_HTTP_EXPORTER_MATLAB_SOURCES} DESTINATION ${OTLP_EXPORTERS_DIR})

‎README.md

+3
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,9 @@ otelcol --config <otelcol-config-yaml>
101101

102102
For more examples, see the "examples" folder.
103103

104+
## Automatic Instrumentation
105+
See example [here](auto-instrumentation/README.md).
106+
104107
## Help
105108
To view documentation of individual function, type "help \<function_name>\". For example,
106109
```

‎auto-instrumentation/+opentelemetry/+autoinstrument/AutoTrace.m

+175
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
classdef AutoTrace < handle
2+
% Automatic instrumentation with OpenTelemetry tracing.
3+
4+
% Copyright 2024 The MathWorks, Inc.
5+
6+
properties (SetAccess=private)
7+
StartFunction function_handle % entry function
8+
InstrumentedFiles string % list of M-files that are auto-instrumented
9+
end
10+
11+
properties (Access=private)
12+
Instrumentor (1,1) opentelemetry.autoinstrument.AutoTraceInstrumentor % helper object
13+
end
14+
15+
methods
16+
function obj = AutoTrace(startfun, options)
17+
% AutoTrace Automatic instrumentation with OpenTelemetry tracing
18+
% AT = OPENTELEMETRY.AUTOINSTRUMENT.AUTOTRACE(FUN) where FUN
19+
% is a function handle, automatically instruments the function
20+
% and all the functions in the same file, as well as their dependencies.
21+
% For each function, a span is automatically started and made
22+
% current at the beginning, and ended at the end. Returns an
23+
% object AT. When AT is cleared or goes out-of-scope, automatic
24+
% instrumentation will stop and the functions will no longer
25+
% be instrumented.
26+
%
27+
% If called in a deployable archive (CTF file), all M-files
28+
% included in the CTF will be instrumented.
29+
%
30+
% AT = OPENTELEMETRY.AUTOINSTRUMENT.AUTOTRACE(FUN, NAME1, VALUE1,
31+
% NAME2, VALUE2, ...) specifies optional name-value pairs.
32+
% Supported options are:
33+
% "AdditionalFiles" - List of additional file names to
34+
% include. Specifying additional files
35+
% are useful in cases when automatic
36+
% dependency detection failed to include them.
37+
% For example, MATLAB Toolbox functions
38+
% authored by MathWorks are excluded by default.
39+
% "ExcludeFiles" - List of file names to exclude
40+
% "AutoDetectFiles" - Whether to automatically include dependencies
41+
% of FUN, specified as a logical scalar.
42+
% Default value is true.
43+
% "TracerName" - Specifies the name of the tracer
44+
% the automatic spans are generated from
45+
% "TracerVersion" - The tracer version
46+
% "TracerSchema" - The tracer schema
47+
% "Attributes" - Add attributes to all the automatic spans.
48+
% Attributes must be specified as a dictionary.
49+
% "SpanKind" - Span kind of the automatic spans
50+
arguments
51+
startfun (1,1) function_handle
52+
options.TracerName {mustBeTextScalar} = "AutoTrace"
53+
options.TracerVersion {mustBeTextScalar} = ""
54+
options.TracerSchema {mustBeTextScalar} = ""
55+
options.SpanKind {mustBeTextScalar}
56+
options.Attributes {mustBeA(options.Attributes, "dictionary")}
57+
options.ExcludeFiles {mustBeText}
58+
options.AdditionalFiles {mustBeText}
59+
options.AutoDetectFiles (1,1) {mustBeNumericOrLogical} = true
60+
end
61+
obj.StartFunction = startfun;
62+
startfunname = func2str(startfun);
63+
processFileInput(startfunname); % validate startfun
64+
if options.AutoDetectFiles
65+
if isdeployed
66+
% matlab.codetools.requiredFilesAndProducts is not
67+
% deployable. Instead instrument all files under CTFROOT
68+
fileinfo = dir(fullfile(ctfroot, "**", "*.m"));
69+
files = fullfile(string({fileinfo.folder}), string({fileinfo.name}));
70+
71+
% filter out internal files in the toolbox directory
72+
files = files(~startsWith(files, fullfile(ctfroot, "toolbox")));
73+
else
74+
%#exclude matlab.codetools.requiredFilesAndProducts
75+
files = string(matlab.codetools.requiredFilesAndProducts(startfunname));
76+
end
77+
else
78+
% only include the input file, not its dependencies
79+
files = string(which(startfunname));
80+
end
81+
% add extra files, this is intended for files
82+
% matlab.codetools.requiredFilesAndProducts somehow missed
83+
if isfield(options, "AdditionalFiles")
84+
incfiles = string(options.AdditionalFiles);
85+
for i = 1:numel(incfiles)
86+
incfiles(i) = which(incfiles(i)); % get the full path
87+
processFileInput(incfiles(i)); % validate additional file
88+
end
89+
files = union(files, incfiles);
90+
end
91+
92+
% make sure files are unique
93+
files = unique(files);
94+
95+
% filter out excluded files
96+
if isfield(options, "ExcludeFiles")
97+
excfiles = string(options.ExcludeFiles);
98+
for i = 1:numel(excfiles)
99+
excfiles(i) = which(excfiles(i)); % get the full path
100+
end
101+
files = setdiff(files, excfiles);
102+
end
103+
% filter out OpenTelemetry files, in case manual
104+
% instrumentation is also used
105+
files = files(~contains(files, ["+opentelemetry" "+libmexclass"]));
106+
107+
for i = 1:length(files)
108+
currfile = files(i);
109+
if currfile =="" % ignore empties
110+
continue
111+
end
112+
obj.Instrumentor.instrument(currfile, options);
113+
obj.InstrumentedFiles(end+1,1) = currfile;
114+
end
115+
end
116+
117+
function delete(obj)
118+
obj.Instrumentor.cleanup(obj.InstrumentedFiles);
119+
end
120+
121+
function varargout = beginTrace(obj, varargin)
122+
% beginTrace Run the auto-instrumented function
123+
% [OUT1, OUT2, ...] = BEGINTRACE(AT, IN1, IN2, ...) calls the
124+
% instrumented function with error handling. In case of
125+
% error, all running spans will end and the last span will
126+
% set to an "Error" status. The instrumented function is
127+
% called with the synax [OUT1, OUT2, ...] = FUN(IN1, IN2, ...)
128+
%
129+
% See also OPENTELEMETRY.AUTOINSTRUMENT.AUTOTRACE/HANDLEERROR
130+
try
131+
varargout = cell(1,nargout);
132+
[varargout{:}] = feval(obj.StartFunction, varargin{:});
133+
catch ME
134+
handleError(obj, ME);
135+
end
136+
end
137+
138+
function handleError(obj, ME)
139+
% handleError Perform cleanup in case of an error
140+
% HANDLEERROR(AT, ME) performs cleanup by ending all running
141+
% spans and their corresponding scopes. Rethrow the
142+
% exception ME.
143+
if ~isempty(obj.Instrumentor.Spans)
144+
setStatus(obj.Instrumentor.Spans(end), "Error");
145+
for i = length(obj.Instrumentor.Spans):-1:1
146+
obj.Instrumentor.Spans(i) = [];
147+
obj.Instrumentor.Scopes(i) = [];
148+
end
149+
end
150+
rethrow(ME);
151+
end
152+
end
153+
154+
155+
end
156+
157+
% check input file is valid
158+
function processFileInput(f)
159+
f = string(f); % force into a string
160+
if startsWith(f, '@') % check for anonymous function
161+
error("opentelemetry:autoinstrument:AutoTrace:AnonymousFunction", ...
162+
replace(f, "\", "\\") + " is an anonymous function and is not supported.");
163+
end
164+
[~,~,fext] = fileparts(f); % check file extension
165+
filetype = exist(f, "file"); % check file type
166+
if ~(filetype == 2 && ismember(fext, ["" ".m" ".mlx"]))
167+
if exist(f, "builtin")
168+
error("opentelemetry:autoinstrument:AutoTrace:BuiltinFunction", ...
169+
replace(f, "\", "\\") + " is a builtin function and is not supported.");
170+
else
171+
error("opentelemetry:autoinstrument:AutoTrace:InvalidMFile", ...
172+
replace(f, "\", "\\") + " is not found or is not a valid MATLAB file with a .m or .mlx extension.");
173+
end
174+
end
175+
end

‎auto-instrumentation/+opentelemetry/+autoinstrument/AutoTraceInstrumentor.p

4.18 KB
Binary file not shown.

‎auto-instrumentation/README.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Automatic Instrumentation
2+
3+
Automatic instrumentation provides a way to instrument MATLAB code with OpenTelemetry data without requiring any code changes.
4+
5+
## AutoTrace
6+
With AutoTrace enabled, spans are automatically started at function beginnings and ended when functions end. By default, AutoTrace instruments the input function and all of its dependencies. An example workflow is as follows:
7+
```
8+
% The example functions should be on the path when calling AutoTrace
9+
addpath("myexample");
10+
11+
% Configure a tracer provider and set it as the global instance
12+
tp = opentelemetry.sdk.trace.TracerProvider; % use default settings
13+
setTracerProvider(tp);
14+
15+
% Instrument the code
16+
at = opentelemetry.autoinstrument.AutoTrace(@myexample, TracerName="AutoTraceExample");
17+
18+
% Start the example
19+
beginTrace(at);
20+
```
21+
Using the `beginTrace` method ensures proper error handling. In the case of an error, `beginTrace` will end all spans and set the "Error" status.
22+
23+
Alternatively, you can also get the same behavior by inserting a try-catch in the starting function.
24+
```
25+
function myexample(at)
26+
% wrap a try catch around the code
27+
try
28+
% example code goes here
29+
catch ME
30+
handleError(at);
31+
end
32+
```
33+
With the try-catch, `beginTrace` method is no longer necessary and you can simply call `myexample` directly and pass in the AutoTrace object.
34+
35+
To disable automatic tracing, delete the object returned by `AutoTrace`.

‎test/autotrace_examples/example1/best_fit_line.m

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
function yf = best_fit_line(x, y)
2+
% example code for testing auto instrumentation
3+
4+
% Copyright 2024 The MathWorks, Inc.
5+
6+
coefs = polyfit(x, y, 1);
7+
yf = polyval(coefs , x);

‎test/autotrace_examples/example1/example1.m

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
function yf = example1(n)
2+
% example code for testing auto instrumentation. Input n is the number of
3+
% data points.
4+
5+
% Copyright 2024 The MathWorks, Inc.
6+
7+
[x, y] = generate_data(n);
8+
yf = best_fit_line(x,y);

‎test/autotrace_examples/example1/example1_trycatch.m

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
function yf = example1_trycatch(at, n)
2+
% example code for testing auto instrumentation. This example should not
3+
% use beginTrace method and instead should be called directly.
4+
5+
% Copyright 2024 The MathWorks, Inc.
6+
7+
try
8+
[x, y] = generate_data(n);
9+
yf = best_fit_line(x,y);
10+
catch ME
11+
handleError(at, ME);
12+
end

‎test/autotrace_examples/example1/generate_data.m

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
function [x, y] = generate_data(n)
2+
% example code for testing auto instrumentation
3+
4+
% Copyright 2024 The MathWorks, Inc.
5+
6+
% check input is valid
7+
if ~(isnumeric(n) && isscalar(n))
8+
error("autotrace_examples:example1:generate_data:InvalidN", ...
9+
"Input must be a numeric scalar");
10+
end
11+
12+
% generate some random data
13+
a = 1.5;
14+
b = 0.8;
15+
sigma = 5;
16+
x = 1:n;
17+
y = a * x + b + sigma * randn(1, n);

0 commit comments

Comments
 (0)