matlab-instrument-opentelemetry-tracing

name	matlab-instrument-opentelemetry-tracing
description	Add OpenTelemetry tracing to MATLAB code. Use when the user asks to "add tracing", "instrument with spans", "add OpenTelemetry", "trace my code", "add observability" (when about tracing), or mentions "spans", "distributed tracing", or "OTel tracing" in the context of MATLAB functions. Covers span creation, parent-child context propagation, error handling, attributes, events, and semantic conventions.
license	MathWorks BSD-3-Clause
metadata	{"author":"MathWorks","version":"1.0"}

Instrument MATLAB Code with OpenTelemetry Tracing

Add OpenTelemetry tracing spans to MATLAB functions with correct implicit context propagation, RAII lifecycle, and semantic conventions.

Prerequisites

The OpenTelemetry-MATLAB package (Version 1.11.0 or newer) must be installed. It provides the opentelemetry.trace.* namespace used throughout this skill. Requires MATLAB R2022b or newer.

Key Functions

Function	Purpose	Toolbox	Available From
opentelemetry.trace.getTracer	Obtain a tracer instance by name	OpenTelemetry-MATLAB	R2022b
startSpan	Create a new span from a tracer	OpenTelemetry-MATLAB	R2022b
makeCurrent	Set span as current context (enables implicit parent-child)	OpenTelemetry-MATLAB	R2022b
setAttributes	Attach key-value metadata to a span	OpenTelemetry-MATLAB	R2022b
setStatus	Mark span as "Ok" or "Error"	OpenTelemetry-MATLAB	R2022b
recordException	Record an MException on a span	OpenTelemetry-MATLAB	R2022b
addEvent	Record a timestamped event within a span	OpenTelemetry-MATLAB	R2022b
endSpan	End a span mid-function (loops only)	OpenTelemetry-MATLAB	R2022b

MATLAB API Differences

The MATLAB OpenTelemetry API differs slightly from C++, Java, and Python implementations. Do not rely on general OTel knowledge from other languages — when unsure about a function, use help opentelemetry.trace.Span or similar to check what exists. Common traps:

• setAttribute (singular) does not exist — use setAttributes (plural)
• opentelemetry.trace.StatusCode.Ok / StatusCode.Error enums do not exist — pass the strings "Ok" or "Error" directly to setStatus

When to Use

• User asks to add tracing or spans to MATLAB code
• User asks to instrument code with OpenTelemetry
• User asks to add observability and tracing is part of the request
• User wants parent-child span relationships across functions

When NOT to Use

• User wants metrics only (counters, histograms, gauges) — no tracing skill needed
• User wants logging only (structured log records) — no tracing skill needed
• User wants to configure the TracerProvider/SDK (exporters, samplers, resource) — that belongs in a separate setup script
• User wants to propagate context across network boundaries (inject/extract into HTTP headers)
• User wants to instrument inside parfor loops — OTel context is not thread-safe in MATLAB

Absolute Rules

These rules override all other considerations. Violating any of them produces incorrect instrumentation.

1. Never modify function signatures

Instrumentation must be invisible to callers. Never add parameters (tracer, context, span) to a function. Never change return values. Each function obtains its own tracer internally:

tr = opentelemetry.trace.getTracer("tracer_name");

This is a cheap lookup from the global provider, not a resource allocation.

2. Spans are RAII — never call endSpan at function exit

The MATLAB Span object holds a C++ shared pointer. When the span variable goes out of scope (function returns, error thrown), the C++ destructor automatically ends the span. Only call endSpan when you need to end a span mid-function before the variable naturally goes out of scope.

3. Scope is RAII — never call clear(scope) at function exit

The Scope object returned by makeCurrent restores the previous context when it goes out of scope. Assign it to a variable to control its lifetime. The %#ok<NASGU> pragma suppresses the "unused variable" warning because the variable's lifetime is its purpose, not its value. Exception: inside loops, clear is required to restore the parent context before the next iteration (see loop pattern).

4. Always call makeCurrent on every span

Every span must be made current so child spans created in called functions automatically become children. Without makeCurrent, child spans become orphaned root spans.

5. Never pass explicit "Context" to startSpan

When makeCurrent is used consistently, startSpan automatically picks up the current span as parent. Passing "Context" explicitly is redundant and error-prone. The only exception is when creating a span that must be a child of a different span than the current one (rare).

6. Always set span status

Every span must have its status set before it ends:

• setStatus(span, "Ok") on the success path
• setStatus(span, "Error", message) on the failure path

A span without explicit status is ambiguous in trace viewers.

7. Use getTracer directly

tr = opentelemetry.trace.getTracer("tracer_name");

Never use opentelemetry.sdk.trace.TracerProvider() or opentelemetry.trace.Provider.getTracerProvider() followed by getTracer. The one-liner above is the correct entry point.

8. Use snake_case attribute names with meaningful domain nouns

All attribute names must be lowercase, dot-separated, and use snake_case within each component. The namespace (left of the dot) must be a meaningful domain noun — not a generic word like "total", "numeric", or "count". See the Semantic Conventions section below for the full pattern and examples.

Workflow

Step 1: Analyze the code

Identify:

• Entry-point function (top-level function the user calls)
• Sub-functions and local functions that represent distinct units of work
• I/O operations (file read/write, network calls, database)
• Error-prone sections (file I/O, external systems, parsing)
• Computationally significant operations worth tracking

Step 2: Choose a tracer name

Derive from the file name or containing package:

• processSensorData.m → "processSensorData"
• +mypackage/analyze.m → "mypackage"

All functions in the same workflow should share the same tracer name.

Step 3: Instrument each function

Apply the core pattern to every function that represents a meaningful unit of work. Do not instrument trivial helpers (< 5 lines, no I/O) or functions called thousands of times in tight loops.

Step 4: Add error handling where needed

Add try-catch with recordException only for functions that perform I/O or call external systems. Do not add try-catch around pure computation.

Step 5: Add attributes and events

Add attributes that would help with debugging: input sizes, key parameters, output characteristics. Record events for significant milestones. Follow semantic conventions (see references/semantic-conventions.md).

Step 6: Verify

Run the instrumented code via mcp__matlab__evaluate_matlab_code or mcp__matlab__run_matlab_file to confirm it executes without error.

Core Pattern

This is the one correct pattern for every instrumented function:

function result = processData(inputData, method)
    tr = opentelemetry.trace.getTracer("myService");
    span = startSpan(tr, "processData");
    scope = makeCurrent(span); %#ok<NASGU>

    % --- original function body (unchanged) ---
    result = transform(inputData, method);

    setStatus(span, "Ok");
end

Key points:

• getTracer inside the function — never passed as argument
• startSpan with no "Context" — inherits from current context automatically
• scope = makeCurrent(span) — makes this span the parent for any child spans
• %#ok<NASGU> — suppresses false warning; scope lifetime is the point
• setStatus before the function returns
• No endSpan — span ends via RAII when function returns

Multi-function example

function results = runPipeline(inputFile)
    tr = opentelemetry.trace.getTracer("pipeline");
    span = startSpan(tr, "runPipeline");
    scope = makeCurrent(span); %#ok<NASGU>

    data = loadData(inputFile);
    cleaned = cleanData(data);
    results = analyze(cleaned);

    setStatus(span, "Ok");
end

function data = loadData(filepath)
    tr = opentelemetry.trace.getTracer("pipeline");
    span = startSpan(tr, "loadData");
    scope = makeCurrent(span); %#ok<NASGU>

    data = readtable(filepath);

    setStatus(span, "Ok");
end

function cleaned = cleanData(data)
    tr = opentelemetry.trace.getTracer("pipeline");
    span = startSpan(tr, "cleanData");
    scope = makeCurrent(span); %#ok<NASGU>

    cleaned = rmmissing(data);

    setStatus(span, "Ok");
end

function results = analyze(data)
    tr = opentelemetry.trace.getTracer("pipeline");
    span = startSpan(tr, "analyze");
    scope = makeCurrent(span); %#ok<NASGU>

    results = summary(data);

    setStatus(span, "Ok");
end

Each function independently obtains a tracer and creates its own span. Parent-child relationships are established automatically through makeCurrent.

Error Handling Pattern

Use for functions with I/O or external system calls:

function data = fetchData(url)
    tr = opentelemetry.trace.getTracer("myService");
    span = startSpan(tr, "fetchData", SpanKind="client");
    scope = makeCurrent(span); %#ok<NASGU>
    setAttributes(span, "url.full", url);

    try
        data = webread(url);
        setAttributes(span, "http.response.status_code", 200);
    catch ME
        recordException(span, ME);
        setStatus(span, "Error", ME.message);
        rethrow(ME);
    end

    setStatus(span, "Ok");
end

Key points:

• recordException captures the full MException (identifier, message, stack trace, cause)
• setStatus(span, "Error", ...) marks the span as errored in trace viewers
• rethrow(ME) preserves the original error — span still ends via RAII after rethrow
• Both recordException and setStatus are needed: one records detail, the other sets the visual indicator
• setStatus(span, "Ok") goes after the try-catch block, not inside try — rethrow exits the function so "Ok" is only reached on success

Attributes

Set attributes with setAttributes (plural, never singular setAttribute which does not exist):

setAttributes(span, "input.rows", height(data), "input.columns", width(data));

Or using a dictionary at span creation:

span = startSpan(tr, "processData", Attributes=dictionary( ...
    ["input.file", "input.format"], ...
    {filepath, "csv"}));

Numeric values do not need type casting — the API handles all MATLAB numeric types natively.

Events

Record events for significant milestones within a span:

addEvent(span, "validationComplete", "rows.valid", validCount, "rows.rejected", rejectCount);

SpanKind

Set SpanKind only when the operation involves remote communication. Do not set it for internal operations (the default is "internal").

SpanKind	When	MATLAB examples
"client"	Outgoing request awaiting response	webread, webwrite, ftp, database queries
"server"	Handling an incoming request	MATLAB Production Server handler
"producer"	Initiating work without waiting	Publishing to a queue, enqueuing a batch job
"consumer"	Processing work from a producer	Queue listener, batch worker

span = startSpan(tr, "fetchData", SpanKind="client");

When to Use endSpan

Only use endSpan when ending a span mid-function — before the variable would naturally go out of scope:

function results = batchProcess(items)
    tr = opentelemetry.trace.getTracer("myService");
    span = startSpan(tr, "batchProcess");
    scope = makeCurrent(span); %#ok<NASGU>

    results = cell(numel(items), 1);
    for i = 1:numel(items)
        itemSpan = startSpan(tr, "processItem");
        itemScope = makeCurrent(itemSpan); %#ok<NASGU>
        setAttributes(itemSpan, "item.index", i);
        results{i} = processOne(items{i});
        setStatus(itemSpan, "Ok");
        endSpan(itemSpan);  % Needed: itemSpan must end each iteration
        clear("itemScope");  % Needed: restore parent context before next iteration
    end

    setStatus(span, "Ok");
end

Both lines at the end of the loop body are mandatory:

• endSpan(itemSpan) — ends the span's timing. Without it, the span duration extends until the variable is overwritten on the next iteration (wrong timing).
• clear("itemScope") — restores the parent span as the current context. Without it, makeCurrent on the next iteration would make the new span a child of the previous iteration's span (nested chain) instead of a sibling under the parent (correct flat list).

Semantic Conventions

Attribute names must follow the {object}.{property} pattern:

• Lowercase and dot-separated — never camelCase
• snake_case within each component — total_paths not totalPaths
• Namespace is a meaningful domain noun — the word left of the dot must be a concrete object in the domain (e.g., batch, file, result, data), not a generic adjective or quantifier (total, numeric, count)

Wrong	Right	Why
batch.totalPaths	batch.total_paths	snake_case, not camelCase
option.S0	option.initial_price	descriptive, lowercase
numeric.columns	data.numeric_columns	"data" is meaningful domain noun; "numeric" is not
total.paths	result.total_paths	"total" is not a domain noun

See references/semantic-conventions.md for full guidance on code attributes, file I/O attributes, HTTP client attributes, and domain-specific patterns.

Common Mistakes

Mistake	Why it's wrong	Correct approach
Pass tracer as function argument	Modifies the function API; breaks existing callers	Call getTracer inside each function
Pass context as function argument	Modifies the function API; makes instrumentation visible	Use makeCurrent — child spans inherit automatically
Call endSpan at function exit	Redundant — span ends via RAII; adds noise	Remove it; only use endSpan mid-function
Call clear(scope) at function exit	Redundant — scope restores context via RAII when function returns	Remove it; let the variable go out of scope. Inside loops, clear IS required — see loop pattern above
Pass "Context" to startSpan	Redundant when makeCurrent is used; explicit coupling	Omit it; startSpan uses current context
Omit makeCurrent in child function	Grandchild spans won't inherit context; breaks deep traces	Always call makeCurrent on every span
Use setAttribute (singular)	Does not exist in MATLAB OTel API	Use setAttributes (plural)
Omit setStatus	Span status is ambiguous in trace viewer	Always set "Ok" or "Error"
Wrap OTel code in if isConfigured	Unnecessary — OTel methods are no-ops when not configured	Remove the guard; instrument unconditionally
Use TracerProvider() then getTracer	Indirect; extra line of code for no benefit	Use opentelemetry.trace.getTracer(name) directly
Cast attributes to int64	Unnecessary — API handles all MATLAB numeric types	Use native types as-is

What NOT to Instrument

• Trivial helper functions (< 5 lines, no I/O)
• Functions called thousands of times in tight loops (overhead)
• Anonymous functions or callbacks (unless significant work)
• Code inside parfor blocks (context is not thread-safe)

---

Copyright 2026 The MathWorks, Inc.

---