[FLINK-38353][docs] Update docs for children spans

Author: pnowojski

docs/content.zh/docs/ops/traces.md

@@ -33,26 +33,30 @@ Flink exposes a tracing system that allows gathering and exposing traces to exte
 ## Reporting traces
 
 You can access the tracing system from any user function that extends [RichFunction]({{< ref "docs/dev/datastream/user_defined_functions" >}}#rich-functions) by calling `getRuntimeContext().getMetricGroup()`.
-This method returns a `MetricGroup` object via which you can report a new single span trace.
+This method returns a `MetricGroup` object via which you can report a new single trace with tree of spans.
 
 ### Reporting single Span
 
 
 A `Span` represents some process that happened in Flink at certain point of time for a certain duration, that will be reported to a `TraceReporter`.
 To report a `Span` you can use the `MetricGroup#addSpan(SpanBuilder)` method.
 
-Currently, we don't support traces with multiple spans. Each `Span` is self-contained and represents things like a checkpoint or recovery.
+Currently, we support traces with a single tree of spans, but all the children spans have to be reported all at once in one `MetricGroup#addSpan` call.
+You can not report child or parent spans independently.
 {{< tabs "9612d275-bdda-4322-a01f-ae6da805e917" >}}
 {{< tab "Java" >}}
 ```java
 public class MyClass {
     void doSomething() {
         // (...)
         metricGroup.addSpan(
-                Span.builder(MyClass.class, "SomeAction")
-                        .setStartTsMillis(startTs) // Optional
-                        .setEndTsMillis(endTs) // Optional
-                        .setAttribute("foo", "bar");
+            Span.builder(MyClass.class, "SomeAction")
+                .setStartTsMillis(startTs) // Optional
+                .setEndTsMillis(endTs) // Optional
+                .setAttribute("foo", "bar") // Optional
+                .addChild(Span.builder(MyClass.class, "ChildAction") // Optional
+                    .addChildren(List.of(
+                        Span.builder(MyClass.class, "AnotherChildAction")); // Optional
     }
 }
 ```

docs/content/docs/ops/traces.md

@@ -33,26 +33,30 @@ Flink exposes a tracing system that allows gathering and exposing traces to exte
 ## Reporting traces
 
 You can access the tracing system from any user function that extends [RichFunction]({{< ref "docs/dev/datastream/user_defined_functions" >}}#rich-functions) by calling `getRuntimeContext().getMetricGroup()`.
-This method returns a `MetricGroup` object via which you can report a new single span trace.
+This method returns a `MetricGroup` object via which you can report a new single trace with tree of spans.
 
 ### Reporting single Span
 
 
 A `Span` represents some process that happened in Flink at certain point of time for a certain duration, that will be reported to a `TraceReporter`.
 To report a `Span` you can use the `MetricGroup#addSpan(SpanBuilder)` method.
 
-Currently, we don't support traces with multiple spans. Each `Span` is self-contained and represents things like a checkpoint or recovery.
+Currently, we support traces with a single tree of spans, but all the children spans have to be reported all at once in one `MetricGroup#addSpan` call.
+You can not report child or parent spans independently.
 {{< tabs "9612d275-bdda-4322-a01f-ae6da805e917" >}}
 {{< tab "Java" >}}
 ```java
 public class MyClass {
     void doSomething() {
         // (...)
         metricGroup.addSpan(
-                Span.builder(MyClass.class, "SomeAction")
-                        .setStartTsMillis(startTs) // Optional
-                        .setEndTsMillis(endTs) // Optional
-                        .setAttribute("foo", "bar");
+            Span.builder(MyClass.class, "SomeAction")
+                .setStartTsMillis(startTs) // Optional
+                .setEndTsMillis(endTs) // Optional
+                .setAttribute("foo", "bar") // Optional
+                .addChild(Span.builder(MyClass.class, "ChildAction") // Optional
+                .addChildren(List.of(
+                    Span.builder(MyClass.class, "AnotherChildAction")); // Optional
     }
 }
 ```

docs/layouts/shortcodes/generated/trace_configuration.html

@@ -8,6 +8,16 @@
         </tr>
     </thead>
     <tbody>
+        <tr>
+            <td><h5>traces.checkpoint.span-detail-level</h5></td>
+            <td style="word-wrap: break-word;">SPAN_PER_CHECKPOINT</td>
+            <td><p>Enum</p></td>
+            <td>Detail level for reporting checkpoint spans. Possible values:
+- SPAN_PER_CHECKPOINT (default): Single span per checkpoint. Aggregated sum/max for submetrics from all tasks and subtasks per checkpoint
+- SPAN_PER_CHECKPOINT_WITH_TASKS: Single span per checkpoint. Same as SPAN_PER_CHECKPOINT, plus arrays of aggregated values per task.
+- CHILDREN_SPANS_PER_TASK: Same as SPAN_PER_CHECKPOINT plus children spans per each task. Each task span with aggregated sum/max submetrics from subtasks.
+- CHILDREN_SPANS_PER_SUBTASK: Same as CHILDREN_SPANS_PER_TASK plus children spans per each subtask. Child spans for tasks and grand-child spans for subtasks.<br /><br />Possible values:<ul><li>"SPAN_PER_CHECKPOINT"</li><li>"SPAN_PER_CHECKPOINT_WITH_TASKS"</li><li>"CHILDREN_SPANS_PER_TASK"</li><li>"CHILDREN_SPANS_PER_SUBTASK"</li></ul></td>
+        </tr>
         <tr>
             <td><h5>traces.reporter.&lt;name&gt;.&lt;parameter&gt;</h5></td>
             <td style="word-wrap: break-word;">(none)</td>