diff options
Diffstat (limited to 'doc/source/tutorials/tracing.rst')
-rw-r--r-- | doc/source/tutorials/tracing.rst | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/doc/source/tutorials/tracing.rst b/doc/source/tutorials/tracing.rst new file mode 100644 index 000000000..bc0ca0ea6 --- /dev/null +++ b/doc/source/tutorials/tracing.rst @@ -0,0 +1,80 @@ +Jaeger Tracing Tutorial +======================= + +Zuul includes support for `distributed tracing`_ as described by the +OpenTelemetry project. This allows operators (and potentially users) +to visualize the progress of events and queue items through the +various Zuul components as an aid to debugging. + +Zuul supports the OpenTelemetry Protocol (OTLP) for exporting traces. +Many observability systems support receiving traces via OTLP. One of +these is Jaeger. Because it can be run as a standalone service with +local storage, this tutorial describes how to set up a Jaeger server +and configure Zuul to export data to it. + +For more information about tracing in Zuul, see :ref:`tracing`. + +To get started, first run the :ref:`quick-start` and then follow the +steps in this tutorial to add a Jaeger server. + +Restart Zuul Containers +----------------------- + +After completing the initial tutorial, stop the Zuul containers so +that we can update Zuul's configuration to enable tracing. + +.. code-block:: shell + + cd zuul/doc/source/examples + sudo -E docker-compose -p zuul-tutorial stop + +Restart the containers with a new Zuul configuration. + +.. code-block:: shell + + cd zuul/doc/source/examples + ZUUL_TUTORIAL_CONFIG="./tracing/etc_zuul/" sudo -E docker-compose -p zuul-tutorial up -d + +This tells docker-compose to use these Zuul `config files +<https://opendev.org/zuul/zuul/src/branch/master/doc/source/examples/tracing>`_. +The only change compared to the quick-start is to add a +:attr:`tracing` section to ``zuul.conf``: + +.. code-block:: ini + + [tracing] + enabled=true + endpoint=jaeger:4317 + insecure=true + +This instructs Zuul to send tracing information to the Jaeger server +we will start below. + +Start Jaeger +------------ + +A separate docker-compose file is provided to run Jaeger. Start it +with this command: + +.. code-block:: shell + + cd zuul/doc/source/examples/tracing + sudo -E docker-compose -p zuul-tutorial-tracing up -d + +You can visit http://localhost:16686/search to verify it is running. + +Recheck a change +---------------- + +Visit Gerrit at http://localhost:8080/dashboard/self and return to the +``test1`` change you uploaded earlier. Click `Reply` then type +`recheck` into the text field and click `Send`. This will tell Zuul +to run the test job once again. When the job is complete, you should +have a trace available in Jaeger. + +To see the trace, visit http://localhost:16686/search and select the +`zuul` service (reload the page if it doesn't show up at first). +Press `Find Traces` and you should see the trace for your build +appear. + +_`distributed tracing`: https://opentelemetry.io/docs/concepts/observability-primer/#distributed-traces |