OpenTelemetry#

Portions of Arrow C++ are instrumented with the OpenTelemetry C++ SDK which makes it possible to generate detailed tracing information which can be analyzed in other tools.

Creating a Build with OpenTelemetry Tracing Enabled#

OpenTelemetry tracing is not turned on by default so you must first create a custom build of Arrow C++ with tracing turned on. See Building Arrow C++ for general instructions on creating a custom build.

To enable tracing, specify ARROW_WITH_OPENTELEMETRY=ON when generating your build. You may also want to specify CMAKE_BUILD_TYPE=RelWithDebInfo in order to get representative timings while retaining debug information.

Exporting Tracing Information#

By default, no tracing information is exported until a tracing backend has been specified. This is typically done by the executable using Arrow by installing a TracerProvider through the OpenTelemetry SDK API. Please refer to the OpenTelemetry SDK API C++ documentation.

In the rare cases you want Arrow to control the global resources of the OpenTelemetry SDK, a tracing backend can be specified through the ARROW_TRACING_BACKEND environment variable. This overrides any TracerProvider previously set.

Possible values for ARROW_TRACING_BACKEND are:

• ostream: emit textual log messages to stdout

• otlp_http: emit OTLP JSON encoded traces to a HTTP server (by default, the endpoint URL is http://localhost:4318/v1/traces)

• arrow_otlp_stdout: emit JSON traces to stdout

• arrow_otlp_stderr: emit JSON traces to stderr

For example, to enable exporting JSON traces to stdout, set:

export ARROW_TRACING_BACKEND=arrow_otlp_stdout

At this point, running the program youve linked to your custom build of Arrow C++ should produce JSON traces on stdout.

Visualizing Traces with Jaeger UI#

Analyzing trace information exported to stdout/stderr may involve writing custom processing scripts. As an alternative or even a complement to this process, the all-in-one Jaeger Docker image is a relatively straightforward way of visualizing trace data and is suitable for local development and testing.

Note: This assumes you have Docker installed.

First, change your tracing backend to otlp_http:

export ARROW_TRACING_BACKEND=otlp_http

Then start the Jaeger all-in-one container:

docker run \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:1.35

Now you should be able to run your program and view any traces in a web browser at http://localhost:16686. Note that unlike with other methods of exporting traces, no output will be made to stdout/stderr. However, if you tail your Docker container logs, you should see output when traces are received by the all-in-one container.