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 5511414aff HDDS-16048. [Docs] Improve Tracing Docs (#522)
5511414aff is described below
commit 5511414aff4c9ad973b40149228fe18b3ee5cd53
Author: sravani <[email protected]>
AuthorDate: Thu Aug 6 20:24:37 2026 +0530
HDDS-16048. [Docs] Improve Tracing Docs (#522)
---
.../09-observability/06-distributed-tracing.md | 71 +++++++++++++++++++++
.../09-observability/jaeger-trace.png | Bin 0 -> 399371 bytes
2 files changed, 71 insertions(+)
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 f88780ac0f..e57d49e196 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
@@ -19,6 +19,32 @@ Tracing is turned off by default. To enable it across Ozone
services, configure
</property>
```
+## Application-Aware Client Tracing
+
+Application-aware tracing lets Ozone participate in an existing application
trace without starting its own
+root traces when cluster-wide tracing is disabled. It applies only when
`ozone.tracing.enabled=false` and parent context is passed.
+
+This is controlled by:
+
+```xml
+<property>
+ <name>ozone.tracing.client.application-aware</name>
+ <value>true</value>
+</property>
+```
+
+**Default Value:** `true`
+
+**Behavior:**
+
+- When `true`, the Ozone client can create child spans if an application trace
is already active
+ (via the application's Global OpenTelemetry instance or a W3C-propagated
context).
+ Ozone will not start a new root trace on its own.
+- When `false` (with `ozone.tracing.enabled=false`), client tracing is fully
off.
+- When `ozone.tracing.enabled=true`, Ozone uses its own OpenTelemetry SDK and
exports
+ spans normally; application-aware mode does not change that behavior.
+- Set `ozone.tracing.endpoint` on the Ozone side to the same OTLP collector
endpoint used by your application.
+
## Configuration Priorities
When resolving configurations for endpoints and sampling strategies, Ozone
evaluates sources in the following order of priority:
@@ -96,6 +122,51 @@ 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.
+## Instrumented Components
+
+When tracing is enabled, specific services emit spans using the designated
identifiers below.
+Trace context is propagated across service boundaries via gRPC and W3C context
propagation.
+
+| Service / Component | Service Name |
+|---------------------------| ------------ |
+| Ozone Manager | `OzoneManager` |
+| Storage Container Manager | `StorageContainerManager` |
+| Datanode | `HddsDatanodeService.{datanodeId}` |
+| S3 Gateway | `S3gateway` |
+| Ozone Client | `client` (when Ozone initializes tracing in the
JVM) |
+| CLIs (Shell / FS / Freon) | `shell`, `FsShell`, `freon` |
+
+> **Note:** If an application registers OpenTelemetry first, client spans are
exported under that application's service name, not `client`.
+
+## Dynamic Reconfiguration
+
+You can update the following tracing properties at runtime on the OM, SCM, and
Datanodes
+without restarting the processes:
+
+- `ozone.tracing.enabled`
+- `ozone.tracing.endpoint`
+- `ozone.tracing.sampler`
+- `ozone.tracing.span.sampling`
+- `ozone.tracing.client.application-aware`
+
+> **Note:** S3 Gateway and the Ozone client do not support dynamic
reconfiguration.
+
+For more details on dynamic property reload, see [Dynamic Property
Reload](../dynamic-property-reload).
+
+## Quick Start
+
+1. Start your Ozone cluster and a Jaeger collector.
+2. Enable tracing and set the collector endpoint to your Jaeger OTLP receiver.
See [Enabling Tracing](#enabling-tracing) and [Collector Endpoint
Configuration](#collector-endpoint-configuration).
+3. Generate sample traces:
+
+ ```shell
+ ozone freon rk --numOfVolumes=1 --numOfBuckets=1 --numOfKeys=2
+ ```
+
+4. Open the Jaeger UI, select a service such as `OzoneManager` or `freon`, and
click **Find Traces**.
+
+
+
## References
- Design doc: [HDDS-13679 Distributed tracing
improvement](https://github.com/apache/ozone/blob/master/hadoop-hdds/docs/content/design/distributed-tracing-OpenTelemetry.md)
diff --git
a/docs/05-administrator-guide/03-operations/09-observability/jaeger-trace.png
b/docs/05-administrator-guide/03-operations/09-observability/jaeger-trace.png
new file mode 100644
index 0000000000..82d62bb389
Binary files /dev/null and
b/docs/05-administrator-guide/03-operations/09-observability/jaeger-trace.png
differ
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
