From 6fd01656104215ed18876eb5635ccbfc54d1de29 Mon Sep 17 00:00:00 2001 From: Deepika Upadhyay Date: Wed, 17 Mar 2021 21:35:50 +0530 Subject: [PATCH] doc/dev/developer_guide: add jaegertracing intial developer documentation Signed-off-by: Deepika Upadhyay --- doc/dev/developer_guide/index.rst | 3 +- doc/dev/developer_guide/jaegertracing.rst | 74 +++++++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 doc/dev/developer_guide/jaegertracing.rst diff --git a/doc/dev/developer_guide/index.rst b/doc/dev/developer_guide/index.rst index 970796bd3dc14..a924adf11349d 100644 --- a/doc/dev/developer_guide/index.rst +++ b/doc/dev/developer_guide/index.rst @@ -20,4 +20,5 @@ Contributing to Ceph: A Guide for Developers Tests: Integration Tests (Teuthology) Tests: Running Tests (Locally) Ceph Dashboard Developer Documentation (formerly HACKING.rst) - cephadm Developer Documentation <../cephadm/index> + Tracing Developer Documentation + Cephadm Developer Documentation <../cephadm/index> diff --git a/doc/dev/developer_guide/jaegertracing.rst b/doc/dev/developer_guide/jaegertracing.rst new file mode 100644 index 0000000000000..d70b72c385b80 --- /dev/null +++ b/doc/dev/developer_guide/jaegertracing.rst @@ -0,0 +1,74 @@ +JAEGER- DISTRIBUTED TRACING +=========================== + +Jaeger + Opentracing provides ready to use tracing services for distributed +systems and is becoming the widely used standard because of their simplicity and +standardization. + +We use a modified `jaeger-cpp-client +`_ the backend provided to the +Opentracing API, which is responsible for the collection of spans, these spans +are made with the use of smart pointers that carry the timestamp, TraceID and other +meta info like a specific tag/log associated with the span to uniquely identify +it across the distributed system. + + +BASIC ARCHITECTURE AND TERMINOLOGY +---------------------------------- + +* TRACE: A trace shows the data/execution path through a system. +* SPAN: A single unit of a trace, it is a data structure that stores + information like operation name, timestamps, ordering in a trace. +* JAEGER CLIENT: language-specific implementations of the OpenTracing API. +* JAEGER AGENT: a daemon that listens for spans sent over User Datagram Protocol. + The agent is meant to be placed on the same host as the instrumented + application. (acts like a sidecar listener) +* JAEGER COLLECTOR: Jaeger agent sends the spans to this daemon which then + stitches the spans together to form a trace(if enabled, also persists a database + for these traces) +* JAEGER QUERY AND CONSOLE FRONTEND: UI based frontend to checkout the jaeger + traces, navigate to http://localhost:16686 (if using default `all-in-one + docker `_ to access the Jaeger UI. + +HOW TO GET STARTED USING TRACING? +--------------------------------- + +Enabling jaegertracing with Ceph needs deployment Jaeger daemons + compiling +Ceph with Jaeger, orchestrated to be used in vstart cluster for developers, this +uses a jaeger `all-in-one docker +`_ which +isn't recommended for production, but for testing purposes. Let's look at all the +steps needed: + + 1. Update system with Jaeger dependencies, using install-deps:: + + $ WITH_JAEGER=true ./install-deps.sh + + 2. Compile Ceph with Jaeger enabled: + + - for precompiled build:: + + $ cd build + $ cmake -DWITH_JAEGER=ON .. + + - for fresh compilation using do_cmake.sh:: + + $ ./do_cmake.sh -DWITH_JAEGER=ON && ninja vstart + + 3. After successful compiling, start a vstart cluster with `--jaeger` which + will deploy `jaeger all-in-one `_ + using container deployment services(docker/podman):: + + $ MON=1 MGR=0 OSD=1 ../src/vstart.sh --with-jaeger + + if the deployment is unsuccessful, you can deploy `all-in-one + `_ + service manually and start vstart cluster without jaeger as well. + + + 4. Test the traces using rados-bench write:: + + $ bin/rados -p test bench 5 write --no-cleanup + +.. seealso:: + `using-jaeger-cpp-client-for-distributed-tracing-in-ceph `_ -- 2.39.5