From 9d1fb1bc39a55fd8bf906b553a5d0f1aeabc6812 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Thu, 2 Feb 2023 17:15:44 +1000 Subject: [PATCH] doc/jaegertracing: refine index.rst Make English in jaegertracing/index.rst more elegant. Signed-off-by: Zac Dover --- doc/jaegertracing/index.rst | 87 ++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 40 deletions(-) diff --git a/doc/jaegertracing/index.rst b/doc/jaegertracing/index.rst index 72622db122363..a3afd4787bfae 100644 --- a/doc/jaegertracing/index.rst +++ b/doc/jaegertracing/index.rst @@ -1,91 +1,98 @@ JAEGER- DISTRIBUTED TRACING =========================== -Jaeger provides ready to use tracing services for distributed -systems and is becoming the widely used standard because of their simplicity and -standardization. - +Jaeger provides ready-to-use tracing services for distributed systems. 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://:16686 - - -read more about jaeger tracing:. +* SPAN: A single unit of a trace. A data structure that stores information such + as the operation name, timestamps, and the ordering within 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. (The Jaeger agent acts like a sidecar listener.) +* JAEGER COLLECTOR: A daemon that receives spans sent by the Jaeger agent. The + Jaeger collector then stitches the spans together to form a trace. (A databse + can be enabled to persist a database for these traces). +* JAEGER QUERY AND CONSOLE FRONTEND: The UI-based frontend that presents + reports of the jaeger traces. Accessible at http://:16686. + +Read more about jaeger tracing:. https://www.jaegertracing.io/docs/ - JAEGER DEPLOYMENT ----------------- -there are couple of ways to deploy jaeger. -it can be done using cephadm, or manually. +Jaeger can be deployed using cephadm, and Jaeger can be deployed manually. -please refer to: +Refer to one of the following: -`Cephadm Jaeger services deployment <../cephadm/services/tracing/>`_ +`Cephadm Jaeger Services Deployment <../cephadm/services/tracing/>`_ -`jaeger deployment `_ +`Jaeger Deployment `_ -`jaeger performance tuning `_ +`Jaeger Performance Tuning `_ Important Notes: ^^^^^^^^^^^^^^^^ -- Spans are being sent to local jaeger agent, so the jaeger agent must be running on each host (not in all-in-one mode). otherwise, spans of hosts without active jaeger agent will be lost. +- The Jaeger agent must be running on each host (and not running in all-in-one + mode). This is because spans are sent to the local Jaeger agent. Spans of + hosts that do not have active Jaeger agents will be lost. -- Ceph tracers are configured to send tracers to agents that are listening to port 6799, so on manual jaeger deployment, option "--processor.jaeger-compact.server-host-port=6799" should be used. +- Ceph tracers are configured to send tracers to agents that listen to port + 6799. Use the option "--processor.jaeger-compact.server-host-port=6799" for + manual Jaeger deployments. HOW TO ENABLE TRACING IN CEPH ----------------------------- -tracing in Ceph is disabled by default. -it could be enabled globally, or for each entity separately (e.g. rgw). +Tracing in Ceph is disabled by default. + +Tracing can be enabled globally, and tracing can also be enabled separately for +each entity (for example, for rgw). + +Enable tracing globally: + +.. prompt:: bash $ - Enable tracing globally:: + ceph config set global jaeger_tracing_enable true - $ ceph config set global jaeger_tracing_enable true +Enable tracing for each entity: - Enable tracing for each entity:: +.. prompt:: bash $ - $ ceph config set jaeger_tracing_enable true + ceph config set jaeger_tracing_enable true TRACES IN RGW ------------- -traces of RGW can be found under Service `rgw` in Jaeger Frontend. +Traces run on RGW can be found under the Service `rgw` in the Jaeger Frontend. REQUESTS ^^^^^^^^ -every user request is being traced. each trace contains tags for -`Operation name`, `User id`, `Object name` and `Bucket name`. +Every user request is traced. Each trace contains tags for `Operation name`, +`User id`, `Object name` and `Bucket name`. -there is also `Upload id` tag for Multipart upload operations. +There is also an `Upload id` tag for Multipart upload operations. -request trace is named ` `. +The names of request traces have the following format: ` `. MULTIPART UPLOAD ^^^^^^^^^^^^^^^^ -there is a trace, that consists a span for each request that made by that multipart upload, including all `Put Object` requests. +There is a kind of trace that consists of a span for each request made by a +multipart upload, and it includes all `Put Object` requests. -multipart trace is named `multipart_upload `. +The names of multipart traces have the following format: `multipart_upload +`. rgw service in Jaeger Frontend: -- 2.47.3