Emit MATLAB Build Telemetry Data with OpenTelemetry Integration

R2026b

Since R2026a

You can instrument your MATLAB^® builds with OpenTelemetry™ to emit detailed execution data, including build results, task spans, and other metrics. The build tool emits traces and metrics, which you can export to observability backends for monitoring and analysis, using the OpenTelemetry-MATLAB package. For more information on OpenTelemetry, see the OpenTelemetry documentation.

When you install the OpenTelemetry-MATLAB package, the build tool automatically instruments all builds. No changes to your build file are required.

Set Up OpenTelemetry Integration

To emit telemetry data from MATLAB builds, you need MATLAB R2026a or later and the OpenTelemetry-MATLAB package. For each MATLAB instance that participates in builds:

1. Install the gRPC variant of the OpenTelemetry-MATLAB package — Use the Add-On Explorer in MATLAB to search for and install OpenTelemetry-MATLAB. Alternatively, download the otel-matlab.mltbx file from GitHub Releases and then double-click the file or use mpminstall. For installation instructions and examples, see MATLAB Interface to OpenTelemetry on GitHub^®.

2. Configure how the integration exports data — On the system that runs the MATLAB build, set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to the address of your OpenTelemetry collector or backend. The build tool exports telemetry data using the OTLP gRPC protocol. If you do not set this variable, the default endpoint is localhost:4317.

After you install the OpenTelemetry-MATLAB package, the build tool automatically emits telemetry data on subsequent runs. The instrumentation emits:

• A trace with one parent span named "buildtool" that encompasses your entire build, with individual child spans for each task that executes

• Metrics that track quantitative build data, such as task successes, failures, and skips

You can view the resulting traces and metrics in your observability backend.

Note

Tasks that execute on parallel workers do not emit telemetry data. Only tasks that run on the MATLAB client emit spans and metrics.

Use Environment Variables for Context Propagation

The build tool integrates with other tools, such as continuous integration (CI) systems, by using environment variables to propagate context. For more information, see the OpenTelemetry Environment Variables as Context Propagation Carriers page.

To link build traces to a parent trace in your CI pipeline, set the following environment variables on the system that runs the MATLAB build.

Environment Variable	Description
TRACE_ID	Trace ID from the parent span
SPAN_ID	Span ID from the parent span
BAGGAGE	Comma-separated key-value pairs to attach as resource attributes (for example, cicd.pipeline.id=my_pipeline,cicd.pipeline.run_number=10)

For example, the OpenTelemetry plugin for Jenkins exposes these environment variables to downstream build steps automatically, enabling you to connect MATLAB build traces to the broader pipeline trace.

Use Existing OpenTelemetry Configuration

If you already configure OpenTelemetry in MATLAB elsewhere in your pipeline, you can prevent the build tool from overwriting your configuration. On the system that runs the MATLAB build, set the NO_MBT_OTEL_CONFIG environment variable to any value. For example:

setenv("NO_MBT_OTEL_CONFIG","1")

If you set this variable, the build tool still creates spans and records metrics using your existing configuration, but it does not set up or tear down the tracer provider, meter provider, logger provider, or exporters.

Telemetry Data Reference

The build tool emits telemetry data as traces and metrics. Each build produces a parent span with child spans for individual tasks, and counters that track task outcomes. The following subsections describe the attributes and metrics that the build tool produces.

Resource Attributes

All telemetry signals include the following resource attribute.

Attribute	Example Value	Description
service.name	buildtool	Name of the telemetry source

Span Attributes

The build span ("buildtool") includes these attributes.

Attribute	Example Value	Description
buildtool.tasks	3	Total number of tasks in the build
buildtool.tasks.successful	["check", "test"]	Names of successful tasks
buildtool.tasks.failed	[]	Names of failed tasks
buildtool.tasks.skipped	["archive"]	Names of skipped tasks
buildtool.build.successes	2	Number of successful tasks
buildtool.build.failures	0	Number of failed tasks
buildtool.build.skips	1	Number of skipped tasks

Each task span includes these attributes.

Attribute	Example Value	Description
buildtool.task.name	test	Name of the task
buildtool.task.description	Run tests	Description of the task
buildtool.task.successful	true	Whether the task was successful
buildtool.task.failed	false	Whether the task failed
buildtool.task.skipped	false	Whether the task was skipped

Span Status

The build tool sets the span status to indicate the outcome of the build or task.

Span	Condition	Status Code	Status Message
Build span	All tasks succeed	Ok	-
Build span	Any task fails	Error	Build completed, results not successful
Task span	Task succeeds	Ok	-
Task span	Task fails	Error	Task completed, results not successful

Metrics

The build tool records the following metrics.

Metric	Type	Description
buildtool.tasks.successful	Counter	Number of successful tasks
buildtool.tasks.failed	Counter	Number of failed tasks
buildtool.tasks.skipped	Counter	Number of skipped tasks
buildtool.build.successes	Counter	Number of successful builds
buildtool.build.failures	Counter	Number of failed builds