diff options
author | Zuul <zuul@review.opendev.org> | 2022-09-27 20:34:51 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2022-09-27 20:34:51 +0000 |
commit | 9f459dd6f75f763d2c0c4c0e842478dbb233088c (patch) | |
tree | a9c18d9e17dbfc1c6727c74231ebd01d782fe0f8 /doc | |
parent | a30b6fc8aac8e8f8d8424b40443a98b046a84122 (diff) | |
parent | c1845b02a441b8533c3e9a2ebac070cdc073f1f9 (diff) | |
download | zuul-9f459dd6f75f763d2c0c4c0e842478dbb233088c.tar.gz |
Merge "Add tracing tutorial"
Diffstat (limited to 'doc')
-rw-r--r-- | doc/source/examples/tracing/docker-compose.yaml | 32 | ||||
-rw-r--r-- | doc/source/examples/tracing/etc_zuul/main.yaml | 14 | ||||
-rw-r--r-- | doc/source/examples/tracing/etc_zuul/zuul.conf | 59 | ||||
-rw-r--r-- | doc/source/tracing.rst | 15 | ||||
-rw-r--r-- | doc/source/tutorials/tracing.rst | 80 |
5 files changed, 199 insertions, 1 deletions
diff --git a/doc/source/examples/tracing/docker-compose.yaml b/doc/source/examples/tracing/docker-compose.yaml new file mode 100644 index 000000000..d732dff90 --- /dev/null +++ b/doc/source/examples/tracing/docker-compose.yaml @@ -0,0 +1,32 @@ +# Start the quickstart tutorial with `docker-compose -p zuul-tutorial +# up` (as directed in the instructions) in order for the network to +# have the expected name so that it can be shared with Jaeger. + +# Version 2.1 is required to specify the network name +version: '2.1' + +services: + jaeger: + image: docker.io/jaegertracing/all-in-one:latest + environment: + - COLLECTOR_OTLP_ENABLED=true + - SPAN_STORAGE_TYPE=badger + - BADGER_EPHEMERAL=false + - BADGER_DIRECTORY_VALUE=/badger/data + - BADGER_DIRECTORY_KEY=/badger/key + ports: + - "16686:16686" + - "4317:4317" + - "4318:4318" + volumes: + - "badger:/badger" + networks: + - zuul + +volumes: + badger: + +networks: + zuul: + external: true + name: zuul-tutorial_zuul diff --git a/doc/source/examples/tracing/etc_zuul/main.yaml b/doc/source/examples/tracing/etc_zuul/main.yaml new file mode 100644 index 000000000..b3674844e --- /dev/null +++ b/doc/source/examples/tracing/etc_zuul/main.yaml @@ -0,0 +1,14 @@ +- tenant: + name: example-tenant + source: + gerrit: + config-projects: + - zuul-config + untrusted-projects: + - test1 + - test2 + opendev.org: + untrusted-projects: + - zuul/zuul-jobs: + include: + - job diff --git a/doc/source/examples/tracing/etc_zuul/zuul.conf b/doc/source/examples/tracing/etc_zuul/zuul.conf new file mode 100644 index 000000000..76f4efe56 --- /dev/null +++ b/doc/source/examples/tracing/etc_zuul/zuul.conf @@ -0,0 +1,59 @@ +[zookeeper] +hosts=zk:2281 +tls_cert=/var/certs/certs/client.pem +tls_key=/var/certs/keys/clientkey.pem +tls_ca=/var/certs/certs/cacert.pem + +[keystore] +password=secret + +[scheduler] +tenant_config=/etc/zuul/main.yaml + +[connection "gerrit"] +name=gerrit +driver=gerrit +server=gerrit +sshkey=/var/ssh/zuul +user=zuul +password=secret +baseurl=http://gerrit:8080 +auth_type=basic + +[connection "opendev.org"] +name=opendev +driver=git +baseurl=https://opendev.org + +[database] +# Use variable interpolation to supply the password from the +# docker-compose file. +# https://zuul-ci.org/docs/zuul/latest/configuration.html +dburi=mysql+pymysql://zuul:%(ZUUL_MYSQL_PASSWORD)s@mysql/zuul + +[web] +listen_address=0.0.0.0 +port=9000 +root=http://localhost:9000 + +[executor] +private_key_file=/var/ssh/nodepool +default_username=root +trusted_rw_paths=/srv/static/logs + +[auth zuul_operator] +driver=HS256 +allow_authz_override=true +realm=zuul.example.com +client_id=zuul.example.com +issuer_id=zuul_operator +secret=exampleSecret + +[webclient] +url=http://localhost:9000 +verify_ssl=false + +[tracing] +enabled=true +endpoint=jaeger:4317 +insecure=true diff --git a/doc/source/tracing.rst b/doc/source/tracing.rst index e973a77dd..267ce4226 100644 --- a/doc/source/tracing.rst +++ b/doc/source/tracing.rst @@ -5,7 +5,7 @@ Tracing ======= -Zuul includes support for distributed `tracing`_ as described by the +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. @@ -18,6 +18,19 @@ Zuul supports the OpenTelemetry Protocol (OTLP) for exporting traces. Many observability systems support receiving traces via OTLP (including Jaeger tracing). +Configuration +------------- + Related configuration is in the :attr:`tracing` section of ``zuul.conf``. +Tutorial +-------- + +Here is a tutorial that shows how to enable tracing with Zuul and Jaeger. + +.. toctree:: + :maxdepth: 1 + + tutorials/tracing + _`distributed tracing`: https://opentelemetry.io/docs/concepts/observability-primer/#distributed-traces 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 |