[Lms24]

DESCRIBE YOUR PR

This PR proposes downgrading the emission of log and metric _byte client report outcomes from MUST to SHOULD. The primary reason for this are performance concerns for calculating or estimating the byte size of an item that is discarded. Specifically:

SDKs SHOULD record byte outcomes if the performance impact is only negligible, but MAY refrain from implementing them if there is a significant performance impact.

A previous benchmark (https://github.com/Lms24/sentry-span-size-benchmark) has shown that for JS and Python, there is a signficant performance cost to estimating sizes.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

• Urgent deadline (GA date, etc.): YYYY-MM-DD
• Other deadline: YYYY-MM-DD
• No deadline: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 21, 2026 9:01am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-docs	Ignored	Preview	Oct 21, 2026 9:01am UTC

[cursor]

The plan checks client errors, runtime missing-file warnings, 404s on the changed spec pages, and page-load volume on those pages. An issue escalates when client errors rise, missing-file warnings appear, or 404s rise while page loads fall.

Services: develop-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

The three spec pages now mark log and metric byte outcomes as optional. SDKs SHOULD record log_byte and trace_metric_byte entries. They MAY omit those entries when size calculation has a performance impact. develop-docs must deploy before this text is live.

Risk

A render failure in the spec changelog or MDX would 404 or crash those three pages. Readers would lose the spec text. The same page renderer serves sibling SDK telemetry pages. A frontmatter parse error could fail the production build for the whole site.

Intended effect

This change is documentation wording. Telemetry does not record the new SHOULD text. There is no queryable intended-effect signal. Absence cannot be told from a flat error rate.

Regression watch

These pages share one MDX renderer. A bad changelog or MDX compile can 404 the three pages or fail the site build. Most current errors are Algolia and an xS TypeError. Those titles may move without this change. Treat a new MDX or spec-render title as this change.

Signal	Baseline	Window	Source	Rule
Production error events	33 events last 24h, 35 events prior 24h. Hourly counts ranged from 0 to 7. Last 24h rate was 33 events per 1722 docs.page.load (1.9%). Top titles: TypeError: Cannot read properties of undefined (reading 'xS') 14, Algolia fetch fail 8, Algolia Insights 401 7	2026-10-19T09:00:00Z to 2026-10-21T09:00:00Z	Sentry org sentry project develop-docs. Query environment:production on error events, count(). Pair with sum of counter docs.page.load	Hourly count should stay in 0-7. A 24h total above 35 is a rise. Do not treat continued Algolia and xS titles at current counts as this change
MDX runtime missing-file warnings	0 logs	2026-10-20T09:00:00Z to 2026-10-21T09:00:00Z	Sentry logs, project develop-docs. Query message:"*MDX file not found at runtime*", count(message)	Hold at 0. This log is a fault. It fires when a bundled spec page is missing at runtime and the renderer returns 404
404s under sdk/telemetry	1 event last 24h, 4 events prior 24h	2026-10-19T09:00:00Z to 2026-10-21T09:00:00Z	Sentry metric docs.page.not_found grouped by requested_path. Row sdk/telemetry	Stay in 1-4 per 24h. A jump above 4 with falling page loads is a regression
Page loads of the changed spec pages	/sdk/telemetry/logs/: 11 last 24h, 8 prior 24h. /sdk/telemetry/client-reports/: 7 over 48h. Sibling /sdk/telemetry/: 24 last 24h, 19 prior 24h	2026-10-19T09:00:00Z to 2026-10-21T09:00:00Z	Sentry metric docs.page.load with page_type:sdk, grouped by path	Logs should stay in 8-11 per 24h. Sibling index should stay in 19-24 per 24h. Client-reports should stay near 7 per 48h. A drop to 0 with rising 404s is a regression. Volume is low and may vary by day

If error events rise, inspect logs for MDX missing-file warnings and new titles from spec changelog render.

Not observable

The published SHOULD wording is not in telemetry. Pageload and navigation spans for these URLs returned no rows, so page-scoped latency and page-scoped error events are not available. /sdk/telemetry/metrics/ page-load count was not in the top 50 page_type:sdk paths over 48h, so that page has no measured pre-ship rate. Prior-day total docs.page.load was not measured, so the 1.9% error rate has no second-window band.

Get Slack DMs about this change: cursor.com/automations/rollouts

[coolguyzone]

Looks good.

[szokeasaurusrex]

Some mostly small thoughts.

I would consider even downgrading further to "MAY," as the performance impact will likely be too high in many cases.

Also, we may want to point implementers to Relay's size calculation, as that is the authoritative calculation, and I believe it may in many cases be more efficient to implement that calculation than to estimate by serializing the log. Though that's just a guess, not supported by benchmarking

[szokeasaurusrex]

l: I would even consider downgrading this to "MAY" and clarifying that it should only be permitted when performance impact is acceptable

Suggested change

	- For logs and metrics, SDKs **SHOULD** also record the respective [`log_byte`](#log-byte-outcomes) and [`trace_metric_byte`](#metric-byte-outcomes) entries, unless they omit byte outcomes for performance reasons.
	- For logs and metrics, SDKs **MAY** also record the respective [`log_byte`](#log-byte-outcomes) and [`trace_metric_byte`](#metric-byte-outcomes) entries when the performance impact of doing so is acceptable.

[szokeasaurusrex]

m: I would remove the redundant sentence. Also, I am pretty sure the comma before the "if" should not be there in US English

l: Also, I would change "negligible" to "acceptable" as it will likely be hard to achieve negligible impact in most cases. If you apply my previous suggestion, the "SHOULD" also should become "MAY"

Suggested change

When a log is dropped, SDKs **SHOULD** record an additional `log_byte` category entry containing the byte size of the log, if calculating or estimating the log size has only a negligible performance impact. If calculating or estimating the log size has a performance impact, SDKs **MAY** omit `log_byte` entries. This provides visibility into the volume of log data being discarded, complementing the item count reported under the `log_item` category.

When a log is dropped, SDKs **SHOULD** record an additional `log_byte` category entry containing the byte size of the log if calculating or estimating the log size has acceptable performance impact. This provides visibility into the volume of log data being discarded, complementing the item count reported under the `log_item` category.

[szokeasaurusrex]

Same here

Suggested change

When a metric is dropped, SDKs **SHOULD** record an additional `trace_metric_byte` category entry containing the byte size of the metric, if calculating or estimating the metric size has only a negligible performance impact. If calculating or estimating the metric size has a performance impact, SDKs **MAY** omit `trace_metric_byte` entries. This provides visibility into the volume of metric data being discarded, complementing the item count reported under the `trace_metric` category.

When a metric is dropped, SDKs **SHOULD** record an additional `trace_metric_byte` category entry containing the byte size of the metric if calculating or estimating the metric size has acceptable performance impact. This provides visibility into the volume of metric data being discarded, complementing the item count reported under the `trace_metric` category.

[szokeasaurusrex]

Same here

Suggested change

	SDKs **SHOULD** also report the size in bytes (`log_byte`) of discarded log messages if calculating or estimating the log size has only a negligible performance impact. If calculating or estimating the log size has a significant performance impact, SDKs **MAY** omit `log_byte` outcomes. An approximation of log size is sufficient (e.g., by counting as if serialized).
	SDKs **SHOULD** also report the size in bytes (`log_byte`) of discarded log messages if calculating or estimating the log size has acceptable performance impact. An approximation of log size is sufficient (e.g., by counting as if serialized).

[szokeasaurusrex]

Same here

Suggested change

	SDKs **SHOULD** also report the size in bytes (`trace_metric_byte`) of discarded metrics if calculating or estimating the metric size has only a negligible performance impact. If calculating or estimating the metric size has a performance impact, SDKs **MAY** omit `trace_metric_byte` outcomes. An approximation of metric size is sufficient (e.g., by counting as if serialized).
	SDKs **SHOULD** also report the size in bytes (`trace_metric_byte`) of discarded metrics if calculating or estimating the metric size has acceptable performance impact. An approximation of metric size is sufficient (e.g., by counting as if serialized).