[doc] add documentation about tracing

doc/content/toolstack/features/Tracing/index.md

@@ -0,0 +1,87 @@
++++
+title = "Tracing"
++++
+
+Tracing is a powerful tool that enables the observation of system behavior across multiple components,
+making it particularly useful for debugging and performance analysis in complex environments. By
+integrating OpenTelemetry (a standard that unifies OpenTracing and OpenCensus) and the Zipkin v2 protocol,
+XAPI enables efficient tracking and visualization of operations across internal and external systems.
+This facilitates detailed analysis and improves collaboration between teams.
+
+Tracing is commonly used in high-level applications such as web services. Consequently, less popular or
+less web-oriented languages may lack dedicated libraries for distributed tracing. (An OCaml implementation
+has been developed specifically for XenAPI.)
+
+# How tracing works in XAPI
+
+## Spans and Trace Context
+
+- A *span* is the core unit of a trace, representing a single operation with a defined start and end time.
+  Spans can contain sub-spans, which represent child tasks. This helps identify bottlenecks or areas that
+  can be parallelized.
+  - A span can contain several contextual elements such as *tags* (key-value pairs),
+    *events* (time-based data), and *errors*.
+- The *TraceContext* HTTP standard defines how trace IDs and span contexts are propagated across systems,
+  enabling full traceability of operations.
+
+This data makes it possible to create relationships between tasks and generate visualizations such as
+architecture diagrams or execution flows. These help in identifying root causes of issues and bottlenecks,
+and also assist newcomers in onboarding to the project.
+
+## Configuration
+
+- To enable tracing you need to create an *Observer* object in XAPI. This can be done using the *xe* CLI:
+  ```sh
+  xe observer-create \
+    name-label=<name> \
+    enabled=true \
+    components=xapi,xenopsd \
+    endpoints=bugtool,http://<jaeger-ip>:9411/api/v2/spans
+  ```
+- **components**: Specify which internal components (e.g., *xapi*, *xenopsd*) should be traced.
+  More components are expected to be supported in future releases. An experimental *smapi* component
+  is also available and requires additional configuration (explained below).
+
+- **endpoints**: The observer can collect traces locally in */var/log/dt* or forward them to external
+  visualization tools such as [Jaeger](https://www.jaegertracing.io/). Currently, only HTTP/S endpoints
+  are supported, and they also require additional configuration steps (see next section).
+
+- To disable tracing you just need to set *enabled* to false:
+  ```sh
+  xe observer-param-set uuid=<OBSERVER_UUID> enabled=false
+  ```
+
+### Enabling smapi component
+
+- *smapi* component is currently considered experimental and is filtered by default. To enable it, you must
+  explicitly configure the following in **xapi.conf**:
+  ```ini
+  observer-experimental-components="" 
+  ```
+  This tells XAPI that no components are considered as experimental, thereby allowing *smapi* to be traced.
+  A modification to **xapi.conf** requires a restart of the XAPI toolstack.
+
+### Enabling HTTP/S endpoints
+
+- By default HTTP and HTTPS endpoints are disabled. To enable them, add the following lines to **xapi.conf**:
+  ```ini
+  observer-endpoint-http-enabled=true
+  observer-endpoint-https-enabled=true
+  ```
+  As with enabling *smapi* component, modifying **xapi.conf** requires a restart of the XAPI toolstack.
+
+### Tagging Trace Sessions for Easier Search
+
+To make trace logs easier to locate and analyze, it can be helpful to add custom attributes around the
+execution of specific commands. For example:
+
+```sh
+# xe observer-param-set uuid=<OBSERVER_UUID> attributes:custom.random=1234
+# xe vm-start ...
+# xe observer-param-clear uuid=<OBSERVER_UUID> param-name=attributes param-key=custom.random
+```
+
+This technique adds a temporary attribute *custom.random=1234* that will appear in the generated trace
+spans, making it easier to search for specific activity in trace visualisation tools. It may also be possible
+to achieve similar tagging using baggage parameters directly in individual *xe* commands, but this approach
+is currently undocumented.