@grepr/cli 1.10.1-5f2d21d → 1.10.1-67e00bb

package/build/dist/docs-index/{ced679c3-7b6b-475f-a424-d3ff1e5ebd64.txt → 8eef2ea4-d4e6-422b-94ff-6fc89bf3455b.txt}

@@ -2,7 +2,7 @@ Create and manage trace reduction pipelines in Grepr to sample, transform, and r
 
 # Use a trace reduction pipeline for your APM data
 
-A *trace reduction pipeline* processes the Application Performance Monitoring (APM) data produced by your applications and agents, transforming and reshaping it before forwarding it to your observability platform. As traces flow through the pipeline, Grepr applies any configured transformations and then samples them to forward a representative subset rather than the full volume. By forwarding fewer traces, a trace pipeline reduces the volume and cost of data sent to your observability platform, while retaining the complete set of raw traces in a Grepr data lake, so you keep full access to your APM data when you need it. A trace pipeline can also derive metrics from your trace data and forward them to Datadog, so you can track trends across your traces without forwarding every trace.
+A *trace reduction pipeline* processes the Application Performance Monitoring (APM) data produced by your applications and agents, transforming and reshaping it before forwarding it to your observability platform. As traces flow through the pipeline, Grepr applies any configured transformations and then samples them to forward a representative subset rather than the full volume. By forwarding fewer traces, a trace pipeline reduces the volume and cost of data sent to your observability platform, while storing processed trace spans in a Grepr data lake so you can access them when needed. A trace pipeline can also derive metrics from your trace data and forward them to Datadog, so you can track trends across your traces without forwarding every trace.
 
 This page details how to create and manage trace pipelines in the Grepr UI, including the steps in a trace pipeline and the settings available for each step. This page also explains how to search the traces stored in your data lake with Trace Explorer.
 
@@ -68,9 +68,9 @@ To configure SQL transforms, on the **Configure SQL Transformation** form:
 * Optionally select **Reuse calculation** to materialize the results of query processing for reuse in subsequent views.
 * In the **Outputs** section, connect each view to a destination that receives the results of its SQL processing. The output type determines the valid destinations for a view: A view with the **Spans** output type sends its results downstream to the next step in the pipeline, and a view with the **Metrics** output type sends its results to a Datadog sink. Because it's the only sink type that can receive metrics, your pipeline must include a Datadog sink. Grepr forwards the metrics to every Datadog sink that you configure.
 
-## Store raw traces in the data lake \[#apm-data-lake]
+## Store traces in the data lake \[#apm-data-lake]
 
-A trace pipeline persists the complete set of raw spans to a Grepr data lake, so that you retain full access to your input trace data even though the pipeline forwards only a sampled subset to your observability platform. You configure the data lake step by selecting the *dataset* that identifies where Grepr stores the raw spans. Storing raw traces in the data lake also makes them searchable in [Trace Explorer](#trace-explorer) and retrievable for tasks such as [backfilling](#trace-actions).
+A trace pipeline persists the processed spans that reach the data lake step, even though the pipeline forwards only a sampled subset to your observability platform. You configure the data lake step by selecting the *dataset* that identifies where Grepr stores the spans. Storing traces in the data lake also makes them searchable in [Trace Explorer](#trace-explorer) and retrievable for tasks such as [backfilling](#trace-actions). When you configure tail sampling, spans that require trace assembly reach this step after assembly; see the buffering note in [_](#tail-sampling).
 
 To learn more about how Grepr stores your raw telemetry data, see [_](/grepr-platform/data-lake).
 
@@ -98,6 +98,8 @@ If both trace head sampling and a span head sampling rule retain the same span,
 
 Tail sampling makes a sampling decision after Grepr assembles a complete trace within a time window, so it can base the decision on the characteristics of the whole trace. Tail sampling includes dedicated settings for traces likely to be valuable for troubleshooting, along with performance-based sampling tiers that sample traces based on their latency.
 
+> Trace assembly buffers tail-sampling candidates in task memory. Regular checkpoints do not include this buffer. If trace processing restarts after a failure or you cancel the pipeline, spans still in the buffer are lost and are not available in Trace Explorer. A planned stop with a savepoint drains the buffer before stopping. Spans retained by trace-level head sampling bypass trace assembly, and pipelines without tail sampling send retained spans directly to the data lake.
+
 Several tail sampling settings accept durations in ISO-8601 duration format. For example, `PT20S` represents 20 seconds and `PT1M` represents one minute.
 
 ### Sample error, incomplete, and long-running traces \[#error-traces]
@@ -175,7 +177,7 @@ The key difference is where the data originates. Grepr produces metrics from you
 
 ## Search traces with Trace Explorer \[#trace-explorer]
 
-Because a trace pipeline stores the complete set of raw spans in your data lake, you can search and inspect those spans even when the pipeline forwards only a sampled subset to your observability platform. Use Trace Explorer to search the spans stored in a dataset, group them to find patterns, and view the details of individual spans and traces. You can open Trace Explorer from the data lake step of a pipeline.
+You can use Trace Explorer to search and inspect the spans stored in your data lake even when the pipeline forwards only a sampled subset to your observability platform. Use Trace Explorer to search the spans stored in a dataset, group them to find patterns, and view the details of individual spans and traces. You can open Trace Explorer from the data lake step of a pipeline.
 
 Trace Explorer provides the following search controls:
 
@@ -209,7 +211,7 @@ When you select a span, Trace Explorer displays a details panel with the span's
 
 ### What is a trace reduction pipeline in Grepr?
 
-A trace reduction pipeline processes APM data from your applications and agents, transforming and sampling traces before forwarding a representative subset to your observability platform. It reduces the volume and cost of forwarded data while retaining the complete set of raw traces in a Grepr data lake.
+A trace reduction pipeline processes APM data from your applications and agents, transforming and sampling traces before forwarding a representative subset to your observability platform. It reduces the volume and cost of forwarded data while storing processed trace spans in a Grepr data lake.
 
 ### What are traces and spans in APM data?
 
@@ -249,7 +251,7 @@ Critical path analysis annotates each span in an assembled trace with its self-t
 
 ### Can I still access traces that the pipeline does not forward?
 
-Yes. A trace pipeline stores the complete set of raw spans in a Grepr data lake. You can search and inspect those spans in Trace Explorer, and you can use the logs backfill action to retrieve the full logs for a representative sample of traces.
+You can search and inspect spans that reach the Grepr data lake in Trace Explorer, and you can use the logs backfill action to retrieve the full logs for a representative sample of traces. Tail-sampling candidates still buffered when a task fails or a pipeline is canceled are lost because regular checkpoints do not include the in-memory trace assembly buffer.
 
 ### What is Trace Explorer?
 

package/build/dist/docs-index/{93e4eada-94b2-474d-abf0-1b9a501ffd70.txt → 98981e3b-e713-4d6b-b144-535a20052039.txt}

@@ -16,7 +16,7 @@ Optional configuration for histogram-based tail sampling. When provided, enables
 
 - name: incompleteSamplingRate (optional)
   type: number
-  description: Sampling rate for incomplete/partial traces. Partial traces occur when some spans are missing, which can indicate data loss or system issues. Applied before quantile-based sampling.
+  description: Sampling rate for incomplete/partial traces. Partial traces occur when some spans are missing or when an assembly span/byte bound forces a buffered segment to emit. Applied before quantile-based sampling.
 
 - name: keyAttributePaths (optional)
   type: array of array of string
@@ -28,11 +28,11 @@ Optional configuration for histogram-based tail sampling. When provided, enables
 
 - name: maxSessionLength (optional)
   type: string
-  description: Upper bound on how long a single trace assembly session may accumulate spans in state before being force-emitted. Protects against long-running traces that would otherwise hold spans in Flink keyed state indefinitely. When the cap is hit, the trace is emitted as partial and later spans form a new session. Must be strictly greater than maxTraceDelay.
+  description: Upper bound on how long a single trace assembly session may accumulate spans in memory before being force-emitted. Protects against long-running traces that would otherwise hold spans in the assembly buffer indefinitely. When the cap is hit, the trace is classified as long-running and later spans form a new session. Must be strictly greater than maxTraceDelay.
 
 - name: maxTraceDelay (optional)
   type: string
-  description: The maximum time to wait for all spans of a trace to arrive before assembling the trace. This determines the size of the tumbling window used for trace assembly. Traces that span longer than this duration may be assembled as partial traces. Should be set based on the expected maximum trace duration in your system. Large values may lead to memory issues if traces are too long and will delay sending traces to the sink by that amount. The pipeline may also fail if configured too high.
+  description: Idle gap after which an in-memory trace assembly session is considered complete. Each accepted span pushes the processing-time deadline forward by this duration. Larger values retain inactive sessions longer and delay emission, while the per-subtask byte bound still caps buffered span bytes.
 
 - name: quantileSamplingTiers (optional)
   type: array of `QuantileSamplingTier`