This is an automated email from the ASF dual-hosted git repository.
jojochuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/master by this push:
new 732bacebe HDDS-15471. [Docs] Update Docs for Distributed Tracing.
(#458)
732bacebe is described below
commit 732bacebe743a053a07df1cde825fb6d0376b55c
Author: sravani <[email protected]>
AuthorDate: Wed Jun 10 05:06:40 2026 +0530
HDDS-15471. [Docs] Update Docs for Distributed Tracing. (#458)
---
.../09-observability/06-distributed-tracing.md | 87 ++++++++++++++++++++--
1 file changed, 81 insertions(+), 6 deletions(-)
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/06-distributed-tracing.md
b/docs/05-administrator-guide/03-operations/09-observability/06-distributed-tracing.md
index 6aff0ea70..3916a374e 100644
---
a/docs/05-administrator-guide/03-operations/09-observability/06-distributed-tracing.md
+++
b/docs/05-administrator-guide/03-operations/09-observability/06-distributed-tracing.md
@@ -8,20 +8,95 @@ Distributed tracing can help to understand performance
bottleneck with visualizi
Ozone makes use of [OpenTelemetry](https://opentelemetry.io/) API for tracing
and uses OTLP with gRPC format for sending traces.
[jaeger](https://jaegertracing.io) tracing library as collector can collect
traces from Ozone over default port 4317 (as default).
-Tracing is turned off by default, but can be turned on with
`hdds.tracing.enabled` from `ozone-site.xml`
+## Enabling Tracing
+
+Tracing is turned off by default. To enable it across Ozone services,
configure the following property in `ozone-site.xml`:
```xml
<property>
- <name>hdds.tracing.enabled</name>
+ <name>ozone.tracing.enabled</name>
<value>true</value>
</property>
```
-Below are the configuration steps for setting the collector endpoint and
sampling strategy. Set these environment variables to be set for each Ozone
component (OM, SCM, Datanode) and for the Ozone client to enable tracing.
+## Configuration Priorities
+
+When resolving configurations for endpoints and sampling strategies, Ozone
evaluates sources in the following order of priority:
+
+1. Explicit Configuration Keys (defined in `ozone-site.xml`)
+2. Environment Variables
+3. Default Internal Values
+
+## Collector Endpoint Configuration
+
+The endpoint specifies the destination where the Jaeger collector is listening.
+
+#### Via `ozone-site.xml`
+
+```xml
+<property>
+ <name>ozone.tracing.endpoint</name>
+ <value>http://localhost:4317</value>
+</property>
+```
+
+#### Via Environment Variable
+
+You can also set this environment variable for each Ozone component (OM, SCM,
DataNode) and the Ozone client:
```env
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-OTEL_TRACES_SAMPLER_ARG=0.01
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
```
-This configuration will record 1% of the requests to limit the performance
overhead.
+**Default Value:** `http://localhost:4317` (if neither the configuration key
nor the environment variable is provided).
+
+## Sampling Strategies
+
+To minimize performance overhead, Ozone supports sampling at both the trace
level and the span level.
+
+### 1. Trace-Level Sampling
+
+This controls the global percentage of end-to-end requests that will be
tracked, accepting a ratio from `0.0` (0%) to `1.0` (100%).
+
+#### Via `ozone-site.xml`
+
+```xml
+<property>
+ <name>ozone.tracing.sampler</name>
+ <value>0.01</value>
+</property>
+```
+
+#### Via Environment Variable
+
+```env
+export OTEL_TRACES_SAMPLER_ARG=0.01
+```
+
+> **Note:** This configuration records 1% of total requests. If an invalid or
negative value is provided, it defaults to `1.0` (100%).
+
+### 2. Span-Level Sampling
+
+This allows you to set sampling for specific, high-interest operations. It
accepts a comma-separated list of `spanName:rate` pairings.
+
+#### Via `ozone-site.xml`
+
+```xml
+<property>
+ <name>ozone.tracing.span.sampling</name>
+ <value>createVolume:1.0,getBucket:0.5</value>
+</property>
+```
+
+#### Via Environment Variable
+
+```env
+export OTEL_SPAN_SAMPLING_ARG="createVolume:1.0,getBucket:0.5"
+```
+
+> **Note:** In this example, 100% of `createVolume` spans and 50% of
`getBucket` spans will be collected.
+
+## References
+
+- Design doc: [HDDS-13679 Distributed tracing
improvement](https://github.com/apache/ozone/blob/master/hadoop-hdds/docs/content/design/distributed-tracing-OpenTelemetry.md)
+- Jira: [HDDS-13679](https://issues.apache.org/jira/browse/HDDS-13679)
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
