This is an automated email from the ASF dual-hosted git repository. pnowojski pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/flink.git
commit 61a8b11f2ef3ddecfbd4e0f86e98cfd52209f23d Author: Piotr Nowojski <[email protected]> AuthorDate: Wed Sep 17 14:59:28 2025 +0200 [FLINK-38353][docs] Update docs for children spans --- docs/content.zh/docs/ops/traces.md | 16 ++++++++++------ docs/content/docs/ops/traces.md | 16 ++++++++++------ .../shortcodes/generated/trace_configuration.html | 7 +++++++ 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/content.zh/docs/ops/traces.md b/docs/content.zh/docs/ops/traces.md index 1dfa6938687..99930650cbc 100644 --- a/docs/content.zh/docs/ops/traces.md +++ b/docs/content.zh/docs/ops/traces.md @@ -33,7 +33,7 @@ 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 @@ -41,7 +41,8 @@ This method returns a `MetricGroup` object via which you can report a new single 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 @@ -49,10 +50,13 @@ 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 } } ``` diff --git a/docs/content/docs/ops/traces.md b/docs/content/docs/ops/traces.md index 1dfa6938687..276c3c1488a 100644 --- a/docs/content/docs/ops/traces.md +++ b/docs/content/docs/ops/traces.md @@ -33,7 +33,7 @@ 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 @@ -41,7 +41,8 @@ This method returns a `MetricGroup` object via which you can report a new single 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 @@ -49,10 +50,13 @@ 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 } } ``` diff --git a/docs/layouts/shortcodes/generated/trace_configuration.html b/docs/layouts/shortcodes/generated/trace_configuration.html index 3e3f990caa5..5fd0c3f79ca 100644 --- a/docs/layouts/shortcodes/generated/trace_configuration.html +++ b/docs/layouts/shortcodes/generated/trace_configuration.html @@ -8,6 +8,13 @@ </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: +<ul><li>'<code class="highlighter-rouge">SPAN_PER_CHECKPOINT</code>' (default): Single span per checkpoint. Aggregated sum/max for sub-metrics from all tasks and subtasks per checkpoint.</li><li>'<code class="highlighter-rouge">SPAN_PER_CHECKPOINT_WITH_TASKS</code>': Single span per checkpoint. Same as '<code class="highlighter-rouge">SPAN_PER_CHECKPOINT</code>', plus arrays of aggregated values per task.</li><li>'<code class="highlighter-rouge">CHILDREN_SPANS_PER_TASK</code>': Same as ' [...] + </tr> <tr> <td><h5>traces.reporter.<name>.<parameter></h5></td> <td style="word-wrap: break-word;">(none)</td>
