diff --git a/develop-docs/sdk/telemetry/telemetry-buffer/browser-telemetry-buffer.mdx b/develop-docs/sdk/telemetry/telemetry-buffer/browser-telemetry-buffer.mdx deleted file mode 100644 index 257f63d9b345b4..00000000000000 --- a/develop-docs/sdk/telemetry/telemetry-buffer/browser-telemetry-buffer.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Browser Telemetry Buffer -description: Detailed browser telemetry buffer design. -sidebar_order: 2 ---- - -To be defined β€” full spec lives here. diff --git a/develop-docs/sdk/telemetry/telemetry-buffer/gdx-telemetry-buffer.mdx b/develop-docs/sdk/telemetry/telemetry-buffer/gdx-telemetry-buffer.mdx deleted file mode 100644 index 4419559dbf726d..00000000000000 --- a/develop-docs/sdk/telemetry/telemetry-buffer/gdx-telemetry-buffer.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: GDX Telemetry Buffer -description: Detailed GDX telemetry buffer design. -sidebar_order: 3 ---- - -To be defined β€” full spec lives here. diff --git a/develop-docs/sdk/telemetry/telemetry-buffer/index.mdx b/develop-docs/sdk/telemetry/telemetry-buffer/index.mdx deleted file mode 100644 index e0ee2a3f750aff..00000000000000 --- a/develop-docs/sdk/telemetry/telemetry-buffer/index.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Telemetry Buffer -sidebar_order: 5 ---- - - - 🚧 This document is work in progress. - - - - This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. - - -The telemetry buffer sits between the client and the transport, temporarily buffering high-volume telemetry data such as spans and logs. The client **SHOULD** continue to pass low-volume telemetry data, such as events, directly to the transport. The telemetry buffer aims to efficiently batch data to reduce the number of outgoing HTTP requests and Sentry envelopes. Without buffering, each span or log would trigger its own request, quickly overwhelming our backends. - -```mermaid -flowchart LR - Client[Client] -->|high-volume telemetry data| Buffer[TelemetryBuffer] - Buffer -->|buffered telemetry data| Transport[Transport] - Client -->|low-volume telemetry data| Transport -``` - -Because telemetry workloads and platform constraints vary widely, buffer requirements differ across environments. For example, backend SDKs need high throughput and backpressure management to handle large data volumes. Mobile SDKs have lower throughput and don't need to worry much about backpressure, but they do need to minimize data loss in the event of abnormal process termination. Browser and GDX SDKs also have different requirements. - -Therefore, we recommend implementing different types of telemetry buffers tailored to the platform's needs. As of Nov 5th, 2025, this page is under development, and we're currently refining the requirements for different platforms: - -* [Backend Telemetry Buffer](./backend-telemetry-buffer/): Detailed backend design -* [Browser Telemetry Buffer](./browser-telemetry-buffer/): To be defined -* [GDX Telemetry Buffer](./gdx-telemetry-buffer/): To be defined -* [Mobile Telemetry Buffer](./mobile-telemetry-buffer/): Spec under validation. - -# Common Requirements - -This section covers the common requirements relevant for all platforms. - -## Data Forwarding Scenarios - -The TelemetryBuffer **MUST** forward all data in memory to the transport to avoid data loss in the following scenarios: - -1. When the user calls `SentrySDK.flush()`, the TelemetryBuffer **MUST** forward all data in memory to the transport, and only then **SHOULD** the transport flush the data. -2. When the user calls `SentrySDK.close()`, the TelemetryBuffer **MUST** forward all data in memory to the transport. SDKs **SHOULD** keep their existing closing behavior. -3. When the application shuts down gracefully, the TelemetryBuffer **SHOULD** forward all data in memory to the transport. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call transport `flush`. - - -## FAQ - -### Where is the Batch Processor? - -The batch processor is deprecated, so we moved it to the [batch-processor](/sdk/telemetry/telemetry-buffer/batch-processor/) page. The telemetry buffer will include parts of the batch processor functionality. diff --git a/develop-docs/sdk/telemetry/telemetry-buffer/backend-telemetry-buffer.mdx b/develop-docs/sdk/telemetry/telemetry-processor/backend-telemetry-processor.mdx similarity index 83% rename from develop-docs/sdk/telemetry/telemetry-buffer/backend-telemetry-buffer.mdx rename to develop-docs/sdk/telemetry/telemetry-processor/backend-telemetry-processor.mdx index bbcfe96595fddc..8faf7542bd87df 100644 --- a/develop-docs/sdk/telemetry/telemetry-buffer/backend-telemetry-buffer.mdx +++ b/develop-docs/sdk/telemetry/telemetry-processor/backend-telemetry-processor.mdx @@ -1,18 +1,22 @@ --- -title: Backend Telemetry Buffer -description: Detailed backend telemetry buffer design. +title: Backend Telemetry Processor +description: Detailed backend telemetry processor design. sidebar_order: 1 --- -## Telemetry Buffer Layer: Prioritized, Bounded, Rate-Aware Envelope Delivery + + 🚧 This document is work in progress. + + +## Telemetry Processor Layer: Prioritized, Bounded, Rate-Aware Envelope Delivery ### Overview -The buffer system sits between the SDK client and the HTTP transport layer, ensuring that critical telemetry like errors take priority over high-volume data like logs and traces. This prevents important events from getting lost when your application is under heavy load or sending large amounts of telemetry. +The TelemetryProcessor sits between the SDK client and the HTTP transport layer, ensuring that critical telemetry like errors take priority over high-volume data like logs and traces. This prevents important events from getting lost when your application is under heavy load or sending large amounts of telemetry. ### Motivation -- Aggregation lives in a unified buffer layer (this way we avoid creating multiple batch processors for different telemetry types). +- Aggregation lives in a unified layer (this way we avoid creating multiple batch processors for different telemetry types). - All telemetry types use capture APIs (CaptureX) routed through the Client. - Rate-limit awareness is built-in across categories. - Buffers support two modes: normal ring buffer and bucket-by-trace (for spans). @@ -20,7 +24,7 @@ The buffer system sits between the SDK client and the HTTP transport layer, ensu ### Architecture Overview -Introduce a `Buffer` layer between the `Client` and the `Transport`. This `Buffer` wraps prioritization and scheduling and exposes a minimal API to the SDK: +Introduce a `TelemetryProcessor` layer between the `Client` and the `Transport`. This `TelemetryProcessor` wraps prioritization and scheduling and exposes a minimal API to the SDK: - Add(item). - Flush(timeout). @@ -34,11 +38,11 @@ Introduce a `Buffer` layer between the `Client` and the `Transport`. This `Buffe β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Buffer β”‚ +β”‚ TelemetryProcessor β”‚ β”‚ Add(item) Β· Flush(timeout) Β· Close(timeout) β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Error Store β”‚ β”‚ Check-in Store β”‚ β”‚ Log Store β”‚ β”‚ +β”‚ β”‚ Error Buffer β”‚ β”‚ Check-in Buffer β”‚ β”‚ Log Buffer β”‚ β”‚ β”‚ β”‚ (CRITICAL) β”‚ β”‚ (HIGH) β”‚ β”‚ (LOW) β”‚ β”‚ β”‚ β”‚ Timeout: N/A β”‚ β”‚ Timeout: N/A β”‚ β”‚ Timeout: 5s β”‚ β”‚ β”‚ β”‚ BatchSize: 1 β”‚ β”‚ BatchSize: 1 β”‚ β”‚ BatchSize: 100 β”‚ β”‚ @@ -46,7 +50,7 @@ Introduce a `Buffer` layer between the `Client` and the `Transport`. This `Buffe β”‚ β”‚ β”‚ β”‚ β–Ό β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Scheduler (Weighted Round-Robin) β”‚ β”‚ +β”‚ β”‚ TelemetryScheduler (Weighted Round-Robin) β”‚ β”‚ β”‚ β”‚ - Priority weights: CRITICAL=5, HIGH=4, MEDIUM=3, LOW=2, LOWEST=1 β”‚ β”‚ β”‚ β”‚ - Processes a batch of items based on BatchSize and/or Timeout β”‚ β”‚ β”‚ β”‚ - Builds envelopes from batch β”‚ β”‚ @@ -61,10 +65,10 @@ Introduce a `Buffer` layer between the `Client` and the `Transport`. This `Buffe β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -#### How the Buffer works +#### How the Processor works - **Smart batching**: Logs are batched into single requests; errors, transactions, and monitors are sent immediately. -- **Pre-send rate limiting**: The scheduler checks rate limits before serialization to avoid unnecessary processing. When a telemetry is rate-limited the selected batch should +- **Pre-send rate limiting**: The TelemetryScheduler checks rate limits before serialization to avoid unnecessary processing. When a telemetry is rate-limited the selected batch should be dropped, to avoid filling up the buffers. - **Category isolation**: Separate ring buffers for each telemetry type prevent head-of-line blocking. - **Weighted scheduling**: High-priority telemetry gets sent more frequently via round-robin selection. @@ -81,9 +85,9 @@ Configurable via weights. ### Components -#### Storage +#### TelemetryBuffers -Each telemetry category maintains a store interface; a fixed-size circular array/ring buffer (not to be confused with the `Buffer` wrapper) that stores items before transmission: +Each telemetry category maintains a buffer interface; a fixed-size circular array/ring buffer that stores items before transmission: - **Bounded capacity**: Default to 100 items for errors, logs, and monitors; 1000 for transactions. This prevents unbounded memory growth regardless of telemetry volume and backpressure handling. - **Overflow policies** (optional): @@ -100,10 +104,10 @@ Each telemetry category maintains a store interface; a fixed-size circular array - Offer semantics: if not full, append; when full, apply `overflowPolicy`: - `drop_oldest`: evict the oldest item, insert the new one, and invoke the dropped callback with reason `buffer_full_drop_oldest`. - `drop_newest`: reject the new item and invoke the dropped callback with reason `buffer_full_drop_newest`. -- Readiness: a store is ready when `size >= batchSize` or when `timeout` has elapsed since `lastFlushTime` (and it is non-empty). -- Polling: `PollIfReady()` returns up to `batchSize` items and updates `lastFlushTime`; `Drain()` empties the store. +- Readiness: a buffer is ready when `size >= batchSize` or when `timeout` has elapsed since `lastFlushTime` (and it is non-empty). +- Polling: `PollIfReady()` returns up to `batchSize` items and updates `lastFlushTime`; `Drain()` empties the buffer. -##### Bucketed-by-trace storage (spans) +##### Bucketed-by-trace buffer (spans) - **Purpose**: keep spans from the same trace together and flush them as a unit to avoid partial-trace delivery under pressure. This addresses a gap in standard implementations where individual span drops can create incomplete traces. - **Grouping**: a new bucket is created per trace id; a map (`traceIndex`) provides O(1) lookup. @@ -119,11 +123,11 @@ Each telemetry category maintains a store interface; a fixed-size circular array There still remains a small subset of cases that might result in partial traces, where either an old trace bucket was dropped and a new span with the same trace arrived, or we dropped an incoming span of this trace. The preferred overflow behavior in most cases should be `drop_oldest` since it results in the fewest incomplete traces from the two scenarios. -Stores are mapped to [DataCategories](https://github.com/getsentry/relay/blob/master/relay-base-schema/src/data_category.rs), which determine their scheduling priority and rate limits. +Buffers are mapped to [DataCategories](https://github.com/getsentry/relay/blob/master/relay-base-schema/src/data_category.rs), which determine their scheduling priority and rate limits. -#### Scheduler +#### TelemetryScheduler -The scheduler runs as a background worker, coordinating the flow of telemetry from storage to the transport: +The TelemetryScheduler runs as a background worker, coordinating the flow of telemetry from buffers to the transport: - **Initialization**: Constructs a weighted priority cycle (e.g., `[CRITICALΓ—5, HIGHΓ—4, MEDIUMΓ—3, ...]`) based on configured weights. - **Event loop**: Wakes when explicitly signaled from the `captureX` methods on the client when new data is available (if the language does not support this, then a periodic ticker can be used). @@ -191,7 +195,7 @@ type Storage[T any] interface { } -// Single item store +// Single item buffer func (b *RingBuffer[T]) PollIfReady() []T { b.mu.Lock() defer b.mu.Unlock() @@ -226,7 +230,7 @@ func (b *RingBuffer[T]) PollIfReady() []T { return result } -// Bucketed store +// Bucketed buffer func (b *BucketedBuffer[T]) PollIfReady() []T { b.mu.Lock() defer b.mu.Unlock() @@ -257,10 +261,10 @@ func (b *BucketedBuffer[T]) PollIfReady() []T { ``` -#### Scheduler Processing +#### TelemetryScheduler Processing ```go -func (s *Scheduler) run() { +func (s *TelemetryScheduler) run() { for { s.mu.Lock() @@ -274,7 +278,7 @@ func (s *Scheduler) run() { } } -func (s *Scheduler) hasWork() bool { +func (s *TelemetryScheduler) hasWork() bool { for _, buffer := range s.buffers { if buffer.IsReadyToFlush() { return true @@ -283,7 +287,7 @@ func (s *Scheduler) hasWork() bool { return false } -func (s *Scheduler) processNextBatch() { +func (s *TelemetryScheduler) processNextBatch() { if len(s.currentCycle) == 0 { return } @@ -291,7 +295,7 @@ func (s *Scheduler) processNextBatch() { priority := s.currentCycle[s.cyclePos] s.cyclePos = (s.cyclePos + 1) % len(s.currentCycle) - var bufferToProcess Storage[protocol.EnvelopeItemConvertible] + var bufferToProcess TelemetryBuffer[protocol.EnvelopeItemConvertible] var categoryToProcess ratelimit.Category for category, buffer := range s.buffers { if buffer.Priority() == priority && buffer.IsReadyToFlush() { @@ -311,8 +315,8 @@ func (s *Scheduler) processNextBatch() { #### Flushing ```go -func (s *Scheduler) flush() { - // should process all store buffers and send to transport +func (s *TelemetryScheduler) flush() { + // should process all buffers and send to transport for category, buffer := range s.buffers { if !buffer.IsEmpty() { s.processItems(buffer, category, true) diff --git a/develop-docs/sdk/telemetry/telemetry-buffer/batch-processor.mdx b/develop-docs/sdk/telemetry/telemetry-processor/batch-processor.mdx similarity index 94% rename from develop-docs/sdk/telemetry/telemetry-buffer/batch-processor.mdx rename to develop-docs/sdk/telemetry/telemetry-processor/batch-processor.mdx index a104df2b1aec8c..83a2fdb2a808b7 100644 --- a/develop-docs/sdk/telemetry/telemetry-buffer/batch-processor.mdx +++ b/develop-docs/sdk/telemetry/telemetry-processor/batch-processor.mdx @@ -2,11 +2,12 @@ title: Batch Processor (deprecated) redirect_from: - /sdk/telemetry/spans/batch-processor/ + - /sdk/telemetry/telemetry-buffer/batch-processor/ sidebar_order: 10 --- - The BatchProcessor is deprecated. Please use the [Telemetry Buffer](/sdk/telemetry/telemetry-buffer/) instead. + The BatchProcessor is deprecated. Please use the [Telemetry Processor](/sdk/telemetry/telemetry-processor/) instead. @@ -15,7 +16,7 @@ sidebar_order: 10 # BatchProcessor (deprecated) -This section covers the initial specification of the BatchProcessor, which some SDKs use as a reference when implementing logs. This exists only as a reference until we fully spec out the [telemetry buffer](/sdk/telemetry/telemetry-buffer/) across all platforms. +This section covers the initial specification of the BatchProcessor, which some SDKs use as a reference when implementing logs. This exists only as a reference until we fully spec out the [telemetry processor](/sdk/telemetry/telemetry-processor/) across all platforms. ## Overview @@ -37,7 +38,7 @@ The BatchProcessor **MUST** forward all spans and logs in memory to the transpor 2. When the user calls `SentrySDK.close()`, the BatchProcessor **MUST** forward all data in memory to the transport. SDKs **SHOULD** keep their existing closing behavior. 3. When the application shuts down gracefully, the BatchProcessor **SHOULD** forward all data in memory to the transport. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call a transport `flush`. This is mostly relevant for mobile SDKs already subscribed to these hooks, such as [applicationWillTerminate](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/applicationwillterminate(_:)) on iOS. 4. When the application moves to the background, the BatchProcessor **SHOULD** forward all the data in memory to the transport and stop the timer. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call the transport `flush`. This is mostly relevant for mobile SDKs. -5. Mobile SDKs **MUST** minimize data loss when sudden process terminations occur. Refer to the [Mobile Telemetry Buffer](/sdk/telemetry/telemetry-buffer/mobile-telemetry-buffer) section for more details. +5. Mobile SDKs **MUST** minimize data loss when sudden process terminations occur. Refer to the [Mobile Telemetry Processor](/sdk/telemetry/telemetry-processor/mobile-telemetry-processor) section for more details. The detailed specification is written in the [Gherkin syntax](https://cucumber.io/docs/gherkin/reference/). The specification uses spans as an example, but the same applies to logs or any other future telemetry data. diff --git a/develop-docs/sdk/telemetry/telemetry-processor/browser-telemetry-processor.mdx b/develop-docs/sdk/telemetry/telemetry-processor/browser-telemetry-processor.mdx new file mode 100644 index 00000000000000..10ab01b73a4f05 --- /dev/null +++ b/develop-docs/sdk/telemetry/telemetry-processor/browser-telemetry-processor.mdx @@ -0,0 +1,7 @@ +--- +title: Browser Telemetry Processor +description: Detailed browser telemetry processor design. +sidebar_order: 2 +--- + +To be defined β€” full spec lives here. diff --git a/develop-docs/sdk/telemetry/telemetry-processor/gdx-telemetry-processor.mdx b/develop-docs/sdk/telemetry/telemetry-processor/gdx-telemetry-processor.mdx new file mode 100644 index 00000000000000..5a37b14996afc7 --- /dev/null +++ b/develop-docs/sdk/telemetry/telemetry-processor/gdx-telemetry-processor.mdx @@ -0,0 +1,7 @@ +--- +title: GDX Telemetry Processor +description: Detailed GDX telemetry processor design. +sidebar_order: 3 +--- + +To be defined β€” full spec lives here. diff --git a/develop-docs/sdk/telemetry/telemetry-processor/index.mdx b/develop-docs/sdk/telemetry/telemetry-processor/index.mdx new file mode 100644 index 00000000000000..554086f7a220b3 --- /dev/null +++ b/develop-docs/sdk/telemetry/telemetry-processor/index.mdx @@ -0,0 +1,55 @@ +--- +title: Telemetry Processor +sidebar_order: 5 +--- + + + 🚧 This document is work in progress. + + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +The telemetry processor ensures data is delivered efficiently to Sentry. It receives data from the client and forwards it to the transport. Its key responsibilities include buffering, rate limiting, client reporting, priority-based sending, and, on some platforms, offline caching. + + +```mermaid +flowchart LR + Client -- send Data --> TelemetryProcessor + TelemetryProcessor -- sendEnvelope --> Transport +``` + +Once an SDK adds the telemetry processor, its client **SHOULD** only forward data to the telemetry processor, and not directly to the transport. The TelemetryProcessor consists of two major components: + +- **TelemetryBuffer**: Focuses on buffering high-volume data, such as spans and logs, into batches to minimize HTTP requests. +- **TelemetryScheduler**: Takes buffered data from the TelemetryBuffer and manages prioritized sending, including potential offline caching and sending of client reports. + +Because telemetry workloads and platform constraints vary widely, the requirements differ across environments. For example, backend SDKs need high throughput and backpressure management to handle large data volumes. Mobile SDKs have lower throughput and don't need to worry much about backpressure, but they do need to minimize data loss in the event of abnormal process termination. Browser and GDX SDKs also have different requirements. + +Therefore, we recommend implementing different types of telemetry processors tailored to the platform's needs. As of Dec 18th, 2025, this page is under development, and we're currently refining the requirements for different platforms: + +* [Backend Telemetry Processor](./backend-telemetry-processor/): Detailed backend design +* [Browser Telemetry Processor](./browser-telemetry-processor/): To be defined +* [GDX Telemetry Processor](./gdx-telemetry-processor/): To be defined +* [Mobile Telemetry Processor](./mobile-telemetry-processor/): Spec under validation. + + +# Telemetry Buffer + +This section covers the common requirements relevant for all platforms for the TelemetryBuffer. + +## Data Forwarding Scenarios + +The TelemetryBuffer **MUST** forward all data in memory to the transport to avoid data loss in the following scenarios: + +1. When the user calls `SentrySDK.flush()`, the TelemetryBuffer **MUST** forward all data in memory to the transport, and only then **SHOULD** the transport flush the data. +2. When the user calls `SentrySDK.close()`, the TelemetryBuffer **MUST** forward all data in memory to the transport. SDKs **SHOULD** keep their existing closing behavior. +3. When the application shuts down gracefully, the TelemetryBuffer **SHOULD** forward all data in memory to the transport. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call transport `flush`. + + +## FAQ + +### Where is the Batch Processor? + +The batch processor is deprecated, so we moved it to the [batch-processor](/sdk/telemetry/telemetry-processor/batch-processor/) page. The telemetry buffer will include parts of the batch processor functionality. diff --git a/develop-docs/sdk/telemetry/telemetry-buffer/mobile-telemetry-buffer.mdx b/develop-docs/sdk/telemetry/telemetry-processor/mobile-telemetry-processor.mdx similarity index 89% rename from develop-docs/sdk/telemetry/telemetry-buffer/mobile-telemetry-buffer.mdx rename to develop-docs/sdk/telemetry/telemetry-processor/mobile-telemetry-processor.mdx index 0c8715510c6aaa..c8d59525b0b60c 100644 --- a/develop-docs/sdk/telemetry/telemetry-buffer/mobile-telemetry-buffer.mdx +++ b/develop-docs/sdk/telemetry/telemetry-processor/mobile-telemetry-processor.mdx @@ -1,15 +1,19 @@ --- -title: Mobile Telemetry Buffer +title: Mobile Telemetry Processor sidebar_order: 4 --- +We're still figuring out the spec for the mobile telemetry processor. The telemetry buffer is already an approved concept, but not the rest of the processor. + +## Telemetry Buffer + - 🚧 This concept is approved but not yet implemented in any SDKs, and it’s still being validated. If something feels unclear, too complex, or doesn’t work as expected, please open an issue or PR and tag @philipphofmann for review. Feedback and improvements are welcome while we confirm the approach makes sense. 🚧 + 🚧 This concept is approved but not yet implemented in any SDKs, and it's still being validated. If something feels unclear, too complex, or doesn't work as expected, please open an issue or PR and tag @philipphofmann for review. Feedback and improvements are welcome while we confirm the approach makes sense. 🚧 -For the common specification for the telemetry buffer, refer to the [Telemetry Buffer](/sdk/telemetry/telemetry-buffer/) page. This page describes the mobile-specific implementation of the telemetry buffer. The most important difference is that the mobile telemetry buffer is designed to minimize data loss when sudden process terminations occur, such as crashes or watchdog terminations. +For the common specification for the telemetry buffer, refer to the [Telemetry Processor](/sdk/telemetry/telemetry-processor/) page. This page describes the mobile-specific implementation of the telemetry buffer. The most important difference is that the mobile telemetry buffer is designed to minimize data loss when sudden process terminations occur, such as crashes or watchdog terminations. -The common requirements specify [data forwarding scenarios](/sdk/telemetry/telemetry-buffer/#data-forwarding-scenarios), which mobile SDKs MUST implement. Additionally, mobile SDKs **MUST** adhere to this extra data forwarding scenario: +The common requirements specify [data forwarding scenarios](/sdk/telemetry/telemetry-processor/#data-forwarding-scenarios), which mobile SDKs MUST implement. Additionally, mobile SDKs **MUST** adhere to this extra data forwarding scenario: * When the application moves to the background, the TelemetryBuffer **SHOULD** forward all data in memory to the transport and stop the timer. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call transport `flush`. @@ -17,7 +21,7 @@ Each SDK environment is unique. Therefore, SDKs have three options to choose fro ## 1. Flush All Data -When the SDK detects a sudden process termination, it **MUST** put all remaining items in the telemetry buffer into one envelope and flush it. If your SDK has an offline cache, it **MAY** flush the envelope to disk and skip sending it to Sentry, if it ensures to send the envelope the next time the SDK starts. The telemetry buffer **MUST** keep its existing logic described in the [Telemetry Buffer Specification](/sdk/telemetry/telemetry-buffer/#specification) page. +When the SDK detects a sudden process termination, it **MUST** put all remaining items in the telemetry buffer into one envelope and flush it. If your SDK has an offline cache, it **MAY** flush the envelope to disk and skip sending it to Sentry, if it ensures to send the envelope the next time the SDK starts. The telemetry buffer **MUST** keep its existing logic described in the [Telemetry Processor Specification](/sdk/telemetry/telemetry-processor/#specification) page. Suppose your SDK can't reliably detect sudden process terminations, or it can't reliably flush envelopes to Sentry or disk when a sudden process termination happens. In that case, it **SHOULD** implement the [FileStream Cache](#2-filestream-cache) or the [DoubleRotatingBuffer](#3-doublerotatingbuffer). It's acceptable to start with this option as a best effort interim solution before adding one of the more complex options. diff --git a/redirects.js b/redirects.js index 3e7467112c803b..09282d1da3576f 100644 --- a/redirects.js +++ b/redirects.js @@ -76,7 +76,31 @@ const developerDocsRedirects = [ }, { source: '/sdk/telemetry/spans/batch-processor/', - destination: '/sdk/telemetry/telemetry-buffer/batch-processor/', + destination: '/sdk/telemetry/telemetry-processor/batch-processor/', + }, + { + source: '/sdk/telemetry/telemetry-buffer/', + destination: '/sdk/telemetry/telemetry-processor/', + }, + { + source: '/sdk/telemetry/telemetry-buffer/backend-telemetry-buffer/', + destination: '/sdk/telemetry/telemetry-processor/backend-telemetry-processor/', + }, + { + source: '/sdk/telemetry/telemetry-buffer/browser-telemetry-buffer/', + destination: '/sdk/telemetry/telemetry-processor/browser-telemetry-processor/', + }, + { + source: '/sdk/telemetry/telemetry-buffer/gdx-telemetry-buffer/', + destination: '/sdk/telemetry/telemetry-processor/gdx-telemetry-processor/', + }, + { + source: '/sdk/telemetry/telemetry-buffer/mobile-telemetry-buffer/', + destination: '/sdk/telemetry/telemetry-processor/mobile-telemetry-processor/', + }, + { + source: '/sdk/telemetry/telemetry-buffer/batch-processor/', + destination: '/sdk/telemetry/telemetry-processor/batch-processor/', }, { source: '/sdk/setup-wizards/:path*',