Skip to content

feat(attributes): Add CLS web vital source attribute #234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Lms24 merged 2 commits into from
Mar 10, 2026
Merged

feat(attributes): Add CLS web vital source attribute #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9beab17
feat(attributes): Add CLS web vital source attribute
Lms24 Mar 6, 2026
12a121b
rebase
Lms24 Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions javascript/sentry-conventions/src/attributes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -897,6 +897,30 @@ export const BROWSER_VERSION = 'browser.version';
*/
export type BROWSER_VERSION_TYPE = string;

// Path: model/attributes/browser/browser__web_vital__cls__source__[key].json

/**
* The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N `browser.web_vital.cls.source.<key>`
*
* Attribute Value Type: `string` {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY_TYPE}
*
* Contains PII: maybe
*
* Attribute defined in OTEL: No
*
* Has Dynamic Suffix: true
*
* Aliases: {@link CLS_SOURCE_KEY} `cls.source.<key>`
*
* @example "body > div#app"
*/
export const BROWSER_WEB_VITAL_CLS_SOURCE_KEY = 'browser.web_vital.cls.source.<key>';

/**
* Type for {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY} browser.web_vital.cls.source.<key>
*/
export type BROWSER_WEB_VITAL_CLS_SOURCE_KEY_TYPE = string;

// Path: model/attributes/browser/browser__web_vital__cls__value.json

/**
Expand Down Expand Up @@ -1208,6 +1232,31 @@ export const CLS = 'cls';
*/
export type CLS_TYPE = number;

// Path: model/attributes/cls/cls__source__[key].json

/**
* The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N `cls.source.<key>`
*
* Attribute Value Type: `string` {@link CLS_SOURCE_KEY_TYPE}
*
* Contains PII: maybe
*
* Attribute defined in OTEL: No
*
* Has Dynamic Suffix: true
*
* Aliases: {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY} `browser.web_vital.cls.source.<key>`
*
* @deprecated Use {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY} (browser.web_vital.cls.source.<key>) instead - The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.
* @example "body > div#app"
*/
export const CLS_SOURCE_KEY = 'cls.source.<key>';

/**
* Type for {@link CLS_SOURCE_KEY} cls.source.<key>
*/
export type CLS_SOURCE_KEY_TYPE = string;

// Path: model/attributes/code/code__filepath.json

/**
Expand Down Expand Up @@ -9173,6 +9222,7 @@ export const ATTRIBUTE_TYPE: Record<string, AttributeType> = {
[BROWSER_SCRIPT_INVOKER_TYPE]: 'string',
[BROWSER_SCRIPT_SOURCE_CHAR_POSITION]: 'integer',
[BROWSER_VERSION]: 'string',
[BROWSER_WEB_VITAL_CLS_SOURCE_KEY]: 'string',
[BROWSER_WEB_VITAL_CLS_VALUE]: 'double',
[BROWSER_WEB_VITAL_INP_VALUE]: 'double',
[BROWSER_WEB_VITAL_LCP_VALUE]: 'double',
Expand All @@ -9188,6 +9238,7 @@ export const ATTRIBUTE_TYPE: Record<string, AttributeType> = {
[CLOUDFLARE_D1_ROWS_READ]: 'integer',
[CLOUDFLARE_D1_ROWS_WRITTEN]: 'integer',
[CLS]: 'double',
[CLS_SOURCE_KEY]: 'string',
[CODE_FILEPATH]: 'string',
[CODE_FILE_PATH]: 'string',
[CODE_FUNCTION]: 'string',
Expand Down Expand Up @@ -9611,6 +9662,7 @@ export type AttributeName =
| typeof BROWSER_SCRIPT_INVOKER_TYPE
| typeof BROWSER_SCRIPT_SOURCE_CHAR_POSITION
| typeof BROWSER_VERSION
| typeof BROWSER_WEB_VITAL_CLS_SOURCE_KEY
| typeof BROWSER_WEB_VITAL_CLS_VALUE
| typeof BROWSER_WEB_VITAL_INP_VALUE
| typeof BROWSER_WEB_VITAL_LCP_VALUE
Expand All @@ -9626,6 +9678,7 @@ export type AttributeName =
| typeof CLOUDFLARE_D1_ROWS_READ
| typeof CLOUDFLARE_D1_ROWS_WRITTEN
| typeof CLS
| typeof CLS_SOURCE_KEY
| typeof CODE_FILEPATH
| typeof CODE_FILE_PATH
| typeof CODE_FUNCTION
Expand Down Expand Up @@ -10593,6 +10646,19 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
aliases: [SENTRY_BROWSER_VERSION],
changelog: [{ version: '0.1.0', prs: [59, 127, 139] }],
},
[BROWSER_WEB_VITAL_CLS_SOURCE_KEY]: {
brief: 'The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N',
type: 'string',
pii: {
isPii: 'maybe',
},
isInOtel: false,
hasDynamicSuffix: true,
example: 'body > div#app',
aliases: [CLS_SOURCE_KEY],
sdks: ['javascript-browser'],
changelog: [{ version: 'next', prs: [234] }],
},
[BROWSER_WEB_VITAL_CLS_VALUE]: {
brief: 'The value of the recorded Cumulative Layout Shift (CLS) web vital',
type: 'double',
Expand Down Expand Up @@ -10771,6 +10837,23 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
},
],
},
[CLS_SOURCE_KEY]: {
brief: 'The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N',
type: 'string',
pii: {
isPii: 'maybe',
},
isInOtel: false,
hasDynamicSuffix: true,
example: 'body > div#app',
deprecation: {
replacement: 'browser.web_vital.cls.source.<key>',
reason: 'The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.',
},
aliases: [BROWSER_WEB_VITAL_CLS_SOURCE_KEY],
sdks: ['javascript-browser'],
changelog: [{ version: 'next', prs: [234] }],
},
[CODE_FILEPATH]: {
brief:
'The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path).',
Expand Down Expand Up @@ -15225,6 +15308,7 @@ export type Attributes = {
[BROWSER_SCRIPT_INVOKER_TYPE]?: BROWSER_SCRIPT_INVOKER_TYPE_TYPE;
[BROWSER_SCRIPT_SOURCE_CHAR_POSITION]?: BROWSER_SCRIPT_SOURCE_CHAR_POSITION_TYPE;
[BROWSER_VERSION]?: BROWSER_VERSION_TYPE;
[BROWSER_WEB_VITAL_CLS_SOURCE_KEY]?: BROWSER_WEB_VITAL_CLS_SOURCE_KEY_TYPE;
[BROWSER_WEB_VITAL_CLS_VALUE]?: BROWSER_WEB_VITAL_CLS_VALUE_TYPE;
[BROWSER_WEB_VITAL_INP_VALUE]?: BROWSER_WEB_VITAL_INP_VALUE_TYPE;
[BROWSER_WEB_VITAL_LCP_VALUE]?: BROWSER_WEB_VITAL_LCP_VALUE_TYPE;
Expand All @@ -15240,6 +15324,7 @@ export type Attributes = {
[CLOUDFLARE_D1_ROWS_READ]?: CLOUDFLARE_D1_ROWS_READ_TYPE;
[CLOUDFLARE_D1_ROWS_WRITTEN]?: CLOUDFLARE_D1_ROWS_WRITTEN_TYPE;
[CLS]?: CLS_TYPE;
[CLS_SOURCE_KEY]?: CLS_SOURCE_KEY_TYPE;
[CODE_FILEPATH]?: CODE_FILEPATH_TYPE;
[CODE_FILE_PATH]?: CODE_FILE_PATH_TYPE;
[CODE_FUNCTION]?: CODE_FUNCTION_TYPE;
Expand Down
19 changes: 19 additions & 0 deletions model/attributes/browser/browser__web_vital__cls__source__[key].json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"key": "browser.web_vital.cls.source.<key>",
"brief": "The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"example": "body > div#app",
"alias": ["cls.source.<key>"],
"sdks": ["javascript-browser"],
"has_dynamic_suffix": true,
"changelog": [
{
"version": "next",
"prs": [234]
}
]
}
24 changes: 24 additions & 0 deletions model/attributes/cls/cls__source__[key].json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"key": "cls.source.<key>",
"brief": "The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"example": "body > div#app",
"sdks": ["javascript-browser"],
"deprecation": {
"replacement": "browser.web_vital.cls.source.<key>",
"reason": "The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.",
"_status": "backfill"
},
"has_dynamic_suffix": true,
"alias": ["browser.web_vital.cls.source.<key>"],
"changelog": [
{
"version": "next",
"prs": [234]
}
]
}
61 changes: 61 additions & 0 deletions python/src/sentry_conventions/attributes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ class _AttributeNamesMeta(type):
"AI_TOTAL_COST",
"AI_TOTAL_TOKENS_USED",
"AI_WARNINGS",
"CLS_SOURCE_KEY",
"CLS",
"CODE_FILEPATH",
"CODE_FUNCTION",
Expand Down Expand Up @@ -689,6 +690,20 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
Example: "120.0.6099.130"
"""

# Path: model/attributes/browser/browser__web_vital__cls__source__[key].json
BROWSER_WEB_VITAL_CLS_SOURCE_KEY: Literal["browser.web_vital.cls.source.<key>"] = (
"browser.web_vital.cls.source.<key>"
)
"""The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N

Type: str
Contains PII: maybe
Defined in OTEL: No
Has Dynamic Suffix: true
Aliases: cls.source.<key>
Example: "body > div#app"
"""

# Path: model/attributes/browser/browser__web_vital__cls__value.json
BROWSER_WEB_VITAL_CLS_VALUE: Literal["browser.web_vital.cls.value"] = (
"browser.web_vital.cls.value"
Expand Down Expand Up @@ -843,6 +858,19 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
Example: 12
"""

# Path: model/attributes/cls/cls__source__[key].json
CLS_SOURCE_KEY: Literal["cls.source.<key>"] = "cls.source.<key>"
"""The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N

Type: str
Contains PII: maybe
Defined in OTEL: No
Has Dynamic Suffix: true
Aliases: browser.web_vital.cls.source.<key>
DEPRECATED: Use browser.web_vital.cls.source.<key> instead - The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.
Example: "body > div#app"
"""

# Path: model/attributes/cls.json
CLS: Literal["cls"] = "cls"
"""The value of the recorded Cumulative Layout Shift (CLS) web vital
Expand Down Expand Up @@ -5547,6 +5575,19 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
ChangelogEntry(version="0.1.0", prs=[59, 127, 139]),
],
),
"browser.web_vital.cls.source.<key>": AttributeMetadata(
brief="The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
type=AttributeType.STRING,
pii=PiiInfo(isPii=IsPii.MAYBE),
is_in_otel=False,
has_dynamic_suffix=True,
example="body > div#app",
aliases=["cls.source.<key>"],
sdks=["javascript-browser"],
changelog=[
ChangelogEntry(version="next", prs=[234]),
],
),
"browser.web_vital.cls.value": AttributeMetadata(
brief="The value of the recorded Cumulative Layout Shift (CLS) web vital",
type=AttributeType.DOUBLE,
Expand Down Expand Up @@ -5723,6 +5764,24 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
ChangelogEntry(version="0.0.0"),
],
),
"cls.source.<key>": AttributeMetadata(
brief="The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
type=AttributeType.STRING,
pii=PiiInfo(isPii=IsPii.MAYBE),
is_in_otel=False,
has_dynamic_suffix=True,
example="body > div#app",
deprecation=DeprecationInfo(
replacement="browser.web_vital.cls.source.<key>",
reason="The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.",
status=DeprecationStatus.BACKFILL,
),
aliases=["browser.web_vital.cls.source.<key>"],
sdks=["javascript-browser"],
changelog=[
ChangelogEntry(version="next", prs=[234]),
],
),
"cls": AttributeMetadata(
brief="The value of the recorded Cumulative Layout Shift (CLS) web vital",
type=AttributeType.DOUBLE,
Expand Down Expand Up @@ -10124,6 +10183,7 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
"browser.script.invoker_type": str,
"browser.script.source_char_position": int,
"browser.version": str,
"browser.web_vital.cls.source.<key>": str,
"browser.web_vital.cls.value": float,
"browser.web_vital.inp.value": float,
"browser.web_vital.lcp.value": float,
Expand All @@ -10138,6 +10198,7 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
"cloudflare.d1.duration": int,
"cloudflare.d1.rows_read": int,
"cloudflare.d1.rows_written": int,
"cls.source.<key>": str,
"cls": float,
"code.file.path": str,
"code.filepath": str,
Expand Down
24 changes: 24 additions & 0 deletions shared/deprecated_attributes.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1059,6 +1059,30 @@
}
]
},
{
"key": "cls.source.<key>",
"brief": "The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"example": "body > div#app",
"sdks": ["javascript-browser"],
"deprecation": {
"replacement": "browser.web_vital.cls.source.<key>",
"reason": "The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.",
"_status": "backfill"
},
"has_dynamic_suffix": true,
"alias": ["browser.web_vital.cls.source.<key>"],
"changelog": [
{
"version": "next",
"prs": [234]
}
]
},
{
"key": "code.filepath",
"brief": "The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path).",
Expand Down
Loading