From 4de41c9c116d8e8eb658805d8857b4f46a4d82e3 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 3 Mar 2026 11:55:00 +0100 Subject: [PATCH 1/3] docs(develop-docs): Clarify push-based vs pull-based telemetry buffer approach Co-Authored-By: Claude --- .../backend-telemetry-processor.mdx | 2 +- .../processing/telemetry-processor/index.mdx | 16 +++++++++++----- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/backend-telemetry-processor.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/backend-telemetry-processor.mdx index 83e681b23a4a2..c333bd89349df 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/backend-telemetry-processor.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/backend-telemetry-processor.mdx @@ -28,7 +28,7 @@ Configurable via weights. #### TelemetryBuffer -The telemetry buffer on the backend must follow the common [telemetry buffer requirements](/sdk/foundations/processing/telemetry-processor/#telemetry-buffer). Here are the additional requirements for the backend-specific implementation: +Unlike the [push-based approach](/sdk/foundations/processing/telemetry-processor/#push-based-approach), the telemetry buffer does not push data to the telemetry scheduler. Instead, the [telemetry scheduler](#telemetryscheduler) iterates through all buffers using weighted round-robin and pulls data when it determines a buffer is ready to flush. Still, the telemetry buffer **MUST** follow the common [telemetry buffer requirements](/sdk/foundations/processing/telemetry-processor/#telemetry-buffer). Here are the additional backend-specific requirements: 1. The telemetry buffer **SHOULD** drop older items as the overflow policy. It **MAY** also drop newer items to preserve what's already buffered. diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 08f9051126788..20ae5e30efca2 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -98,11 +98,17 @@ The telemetry buffer batches high-volume telemetry items and forwards them to th 1. Before adding an item to a specific buffer, the telemetry buffer **SHOULD** drop rate-limited items to avoid overhead. If doing so, it **MUST** record client reports. 2. When the telemetry buffer overflows and it drops data, it **MUST** record client reports. -3. The telemetry buffer **MUST** forward low-volume data, such as normal events, session replays, or user feedback, directly to the telemetry scheduler. -4. The telemetry buffer **MUST** start a timeout of 5 seconds when the first item is added. When the timeout expires, the telemetry buffer **MUST** forward all items to the telemetry scheduler. -5. The telemetry buffer **MUST** define a size limit of `x` items. See [Size Limit Recommendations](#size-limit-recommendations) below for more details. -6. When the size limit is reached, the telemetry buffer **MUST** forward all items to the telemetry scheduler. The buffer **MAY** forward items in batches. -7. The telemetry buffer **SHOULD** use separate buffers per telemetry item type (e.g., one for spans, one for logs, one for metrics). +3. The telemetry buffer **SHOULD** use separate buffers per telemetry item type (e.g., one for spans, one for logs, one for metrics). + +## Push-Based Approach + +The push-based approach is the default for most SDKs. The telemetry buffers push data to the telemetry scheduler when full or on timeout. For a pull-based alternative, where the telemetry scheduler polls data from the buffers, see the [Backend Telemetry Processor](./backend-telemetry-processor/). + +1. The telemetry buffer **MUST** forward low-volume data, such as normal events, session replays, or user feedback, directly to the telemetry scheduler. +2. The telemetry buffer **MUST** start a timeout of 5 seconds when the first item is added. When the timeout expires, the telemetry buffer **MUST** forward all items to the telemetry scheduler. +3. The telemetry buffer **MUST** define a size limit of `x` items. See [Size Limit Recommendations](#size-limit-recommendations) below for more details. +4. When the size limit is reached, the telemetry buffer **MUST** forward all items to the telemetry scheduler. The buffer **MAY** forward items in batches. + ## Batch Size Limit From f956360d50173940fb7217453e2ac3212b55c731 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 3 Mar 2026 12:00:10 +0100 Subject: [PATCH 2/3] docs(develop-docs): Refine push vs pull-based approach wording Co-Authored-By: Claude --- .../sdk/foundations/processing/telemetry-processor/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 20ae5e30efca2..6882fa74d251f 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -102,7 +102,7 @@ The telemetry buffer batches high-volume telemetry items and forwards them to th ## Push-Based Approach -The push-based approach is the default for most SDKs. The telemetry buffers push data to the telemetry scheduler when full or on timeout. For a pull-based alternative, where the telemetry scheduler polls data from the buffers, see the [Backend Telemetry Processor](./backend-telemetry-processor/). +The push-based approach is the default for most SDKs. The telemetry buffers push data to the telemetry scheduler when full or on timeout. SDKs **MAY** use a [pull-based alternative](./backend-telemetry-processor/), where the telemetry scheduler pulls items from the buffers, which can improve prioritization and throughput control. 1. The telemetry buffer **MUST** forward low-volume data, such as normal events, session replays, or user feedback, directly to the telemetry scheduler. 2. The telemetry buffer **MUST** start a timeout of 5 seconds when the first item is added. When the timeout expires, the telemetry buffer **MUST** forward all items to the telemetry scheduler. From ec347b7923f0f234ebd1b6480e3f4aedf554e29a Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 3 Mar 2026 12:03:15 +0100 Subject: [PATCH 3/3] docs(develop-docs): Clarify push-based as default approach Co-Authored-By: Claude --- .../sdk/foundations/processing/telemetry-processor/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 6882fa74d251f..c413219715eea 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -102,7 +102,9 @@ The telemetry buffer batches high-volume telemetry items and forwards them to th ## Push-Based Approach -The push-based approach is the default for most SDKs. The telemetry buffers push data to the telemetry scheduler when full or on timeout. SDKs **MAY** use a [pull-based alternative](./backend-telemetry-processor/), where the telemetry scheduler pulls items from the buffers, which can improve prioritization and throughput control. +SDKs **SHOULD** use the push-based approach, where the telemetry buffers push data to the telemetry scheduler when full or on timeout. For high-throughput scenarios, SDKs **MAY** use a [pull-based alternative](./backend-telemetry-processor/) optimized for backends, where the scheduler pulls items from the buffers. + +SDKs using the push-based approach **MUST** follow these requirements: 1. The telemetry buffer **MUST** forward low-volume data, such as normal events, session replays, or user feedback, directly to the telemetry scheduler. 2. The telemetry buffer **MUST** start a timeout of 5 seconds when the first item is added. When the timeout expires, the telemetry buffer **MUST** forward all items to the telemetry scheduler.