From 146dd009c3a0c60f9d8a3d68a295083e97ff438d Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 3 Mar 2026 11:15:53 +0100 Subject: [PATCH 1/3] docs(develop-docs): Clarify backend telemetry processor scope and limitations Co-Authored-By: Claude --- .../telemetry-processor/backend-telemetry-processor.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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 880a336a0f2e9..a17148f64adba 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 @@ -8,7 +8,9 @@ sidebar_order: 1 🚧 This document is work in progress. -For the common specification, refer to the [Telemetry Processor](/sdk/foundations/processing/telemetry-processor/) page. This page describes the backend-specific implementation. The key difference is that backend SDKs use **weighted round-robin scheduling** to ensure critical telemetry (like errors) gets priority over high-volume data (like logs) when the application is under heavy load. +For the common specification, refer to the [Telemetry Processor](/sdk/foundations/processing/telemetry-processor/) page. This page describes a backend-specific approach, which is optimized for high load. The key difference is that the telemetry scheduler pulls telemetry data from the telemetry buffers using **weighted round-robin scheduling**. + +It's worth noting that this approach may not be suitable for SDKs needing to support multiple platforms, such as Java, because this approach doesn't work well with offline caching. Offline caches also need a priority based sending strategy and a priority based overflow strategy to avoid dropping critical data over high volume data. If the telemetry scheduler pulls data from the telemetry buffer and it supports an offline cache, it needs to balance items in the offline cache with items from the telemetry buffer. Each SDK should evaluate its requirements and decide whether to adopt the backend-specific pull-based approach or continue using a push-based model as defined in the [Telemetry Processor](/sdk/foundations/processing/telemetry-processor/) page, depending on its platform constraints and architectural needs. ## Backend-Specific Design Decisions From 6ec62a1fe752483e4674e8d7730aefdd236aef02 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 3 Mar 2026 11:19:40 +0100 Subject: [PATCH 2/3] docs(develop-docs): Add minimal API with Close(timeout) to telemetry processor Addresses PR feedback from #16637 where Close(timeout) was missing from the minimal API definition. Co-Authored-By: Claude --- .../foundations/processing/telemetry-processor/index.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 875063216d3c9..4674e78452478 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -20,6 +20,14 @@ flowchart LR TelemetryProcessor -- sendEnvelope --> Transport ``` +The telemetry processor **SHOULD** expose the following minimal API: + +- `Add(item)` — Adds a telemetry item to the processor. +- `Flush(timeout)` — Flushes all buffered data to the transport within the given timeout. +- `Close(timeout)` — Flushes all buffered data and closes the processor within the given timeout. + +The telemetry processor **MUST** work with existing transport implementations. + SDKs **SHOULD** only add the telemetry processor for high-volume data (spans, logs, metrics). SDKs without these features **MAY** omit it. Once added, SDK clients **SHOULD** forward all data to the processor, not the transport. During migration, SDKs **MAY** temporarily send only some telemetry data through the processor. The telemetry processor consists of two major components: From d4ec4734654569cd9a1d6ab2d35a83a76082a8a4 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 3 Mar 2026 11:20:34 +0100 Subject: [PATCH 3/3] Revert "docs(develop-docs): Add minimal API with Close(timeout) to telemetry processor" This reverts commit 6ec62a1fe752483e4674e8d7730aefdd236aef02. --- .../foundations/processing/telemetry-processor/index.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 4674e78452478..875063216d3c9 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -20,14 +20,6 @@ flowchart LR TelemetryProcessor -- sendEnvelope --> Transport ``` -The telemetry processor **SHOULD** expose the following minimal API: - -- `Add(item)` — Adds a telemetry item to the processor. -- `Flush(timeout)` — Flushes all buffered data to the transport within the given timeout. -- `Close(timeout)` — Flushes all buffered data and closes the processor within the given timeout. - -The telemetry processor **MUST** work with existing transport implementations. - SDKs **SHOULD** only add the telemetry processor for high-volume data (spans, logs, metrics). SDKs without these features **MAY** omit it. Once added, SDK clients **SHOULD** forward all data to the processor, not the transport. During migration, SDKs **MAY** temporarily send only some telemetry data through the processor. The telemetry processor consists of two major components: