Collect Detailed Execution Data with OpenTelemetry Integration

To gather detailed timing and execution data when you run your process, you can set up and enable OpenTelemetry integration. OpenTelemetry is an observability framework for creating and managing telemetry data, such as traces, metrics, and logs. The integration produces traces by using the OpenTelemetry-MATLAB package.

Before you enable the OpenTelemetry integration, you must install the OpenTelemetry-MATLAB^® package and configure OpenTelemetry by performing the required setup. For more information on OpenTelemetry, see the OpenTelemetry documentation.

Required Setup

For each MATLAB instance that you use:

1. Install the OpenTelemetry-MATLAB package by using one of these approaches:

   • Search for and install the OpenTelemetry-MATLAB package by using the Add-On Explorer in MATLAB.

   • Download the toolbox file (.mltbx) from File Exchange or GitHub and then install the package by either double-clicking the toolbox file or using matlab.addons.install.

   Make sure to review the Status section of the README file of the package in File Exchange or GitHub^®, and follow any special instructions for your platform and MATLAB version.

2. Configure how the integration exports data.

   By default, the integration exports data to https://localhost:4317 by using the OTLP protocol. You can either:

   • Use a telemetry backend that supports OTLP at https://localhost:4317.

   • Start an OpenTelemetry Collector on each machine and configure the collector to export data to your receivers.

   For information on how to configure your Collectors, see the OpenTelemetry documentation for Configuration.

For example, the following OpenTelemetry Collector configuration forwards traces to Jaeger and metrics to Prometheus:

receivers:
  otlp:
    protocols:
      grpc:
      http:
processors:
  batch:
exporters:
  debug:
    verbosity: detailed
  prometheus:
    endpoint: "localhost:8889"
    namespace: "matlab"
  otlp/jaeger:
    endpoint: "localhost:14317"
    tls:
      cert_file: cert.pem
      key_file: cert-key.pem
service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]    
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, otlp/jaeger]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, prometheus]

Note that you can change the configuration through environment variables. For example, to send the data to a different endpoint, you can set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable. For more information, see the OpenTelemetry documentation for Environment Variable Specification.

Enable OpenTelemetry

After you perform the required setup, you can enable OpenTelemetry integration by using one of these approaches:

• In the runprocess function, set EnableOpenTelemetry to true to trace the tasks in your process, locally or in CI.

  runprocess(EnableOpenTelemetry=true)

  Optionally, to start a span during report generation, you can set the EnableOpenTelemetry argument in the report settings object.

  rpt = padv.ProcessAdvisorReportGenerator(EnableOpenTelemetry=true);
  generateReport(rpt)

• If you are using the pipeline generator, specify the EnableOpenTelemetry property in your Pipeline Generator Options Object. For example, for Jenkins^® pipeline generation:

  padv.pipeline.JenkinsOptions(EnableOpenTelemetry=true)

By default, custom tasks automatically generate one span which covers the entire duration of the task. If you want additional information or attributes, you can instrument your custom tasks as shown in Optional Customizations for OpenTelemetry Integration.