Skip to content

Commit f09166c

Browse files
Lms24claude
Lms24
and
claude
authored
feat(attributes): Add CLS web vital source attribute (#234)
* feat(attributes): Add CLS web vital source attribute Add browser.web_vital.cls.source.<key> as the canonical attribute for CLS layout shift sources, with a dynamic numeric suffix. Deprecate the legacy cls.source.<key> attribute in favour of the new name with backfill status. Co-Authored-By: Claude <noreply@anthropic.com> Made-with: Cursor * rebase --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent fe22d96 commit f09166c

5 files changed

Lines changed: 213 additions & 0 deletions

File tree

‎javascript/sentry-conventions/src/attributes.ts‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -897,6 +897,30 @@ export const BROWSER_VERSION = 'browser.version';
897897
*/
898898
export type BROWSER_VERSION_TYPE = string;
899899

900+
// Path: model/attributes/browser/browser__web_vital__cls__source__[key].json
901+
902+
/**
903+
* 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>`
904+
*
905+
* Attribute Value Type: `string` {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY_TYPE}
906+
*
907+
* Contains PII: maybe
908+
*
909+
* Attribute defined in OTEL: No
910+
*
911+
* Has Dynamic Suffix: true
912+
*
913+
* Aliases: {@link CLS_SOURCE_KEY} `cls.source.<key>`
914+
*
915+
* @example "body > div#app"
916+
*/
917+
export const BROWSER_WEB_VITAL_CLS_SOURCE_KEY = 'browser.web_vital.cls.source.<key>';
918+
919+
/**
920+
* Type for {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY} browser.web_vital.cls.source.<key>
921+
*/
922+
export type BROWSER_WEB_VITAL_CLS_SOURCE_KEY_TYPE = string;
923+
900924
// Path: model/attributes/browser/browser__web_vital__cls__value.json
901925

902926
/**
@@ -1208,6 +1232,31 @@ export const CLS = 'cls';
12081232
*/
12091233
export type CLS_TYPE = number;
12101234

1235+
// Path: model/attributes/cls/cls__source__[key].json
1236+
1237+
/**
1238+
* The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N `cls.source.<key>`
1239+
*
1240+
* Attribute Value Type: `string` {@link CLS_SOURCE_KEY_TYPE}
1241+
*
1242+
* Contains PII: maybe
1243+
*
1244+
* Attribute defined in OTEL: No
1245+
*
1246+
* Has Dynamic Suffix: true
1247+
*
1248+
* Aliases: {@link BROWSER_WEB_VITAL_CLS_SOURCE_KEY} `browser.web_vital.cls.source.<key>`
1249+
*
1250+
* @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.
1251+
* @example "body > div#app"
1252+
*/
1253+
export const CLS_SOURCE_KEY = 'cls.source.<key>';
1254+
1255+
/**
1256+
* Type for {@link CLS_SOURCE_KEY} cls.source.<key>
1257+
*/
1258+
export type CLS_SOURCE_KEY_TYPE = string;
1259+
12111260
// Path: model/attributes/code/code__filepath.json
12121261

12131262
/**
@@ -9173,6 +9222,7 @@ export const ATTRIBUTE_TYPE: Record<string, AttributeType> = {
91739222
[BROWSER_SCRIPT_INVOKER_TYPE]: 'string',
91749223
[BROWSER_SCRIPT_SOURCE_CHAR_POSITION]: 'integer',
91759224
[BROWSER_VERSION]: 'string',
9225+
[BROWSER_WEB_VITAL_CLS_SOURCE_KEY]: 'string',
91769226
[BROWSER_WEB_VITAL_CLS_VALUE]: 'double',
91779227
[BROWSER_WEB_VITAL_INP_VALUE]: 'double',
91789228
[BROWSER_WEB_VITAL_LCP_VALUE]: 'double',
@@ -9188,6 +9238,7 @@ export const ATTRIBUTE_TYPE: Record<string, AttributeType> = {
91889238
[CLOUDFLARE_D1_ROWS_READ]: 'integer',
91899239
[CLOUDFLARE_D1_ROWS_WRITTEN]: 'integer',
91909240
[CLS]: 'double',
9241+
[CLS_SOURCE_KEY]: 'string',
91919242
[CODE_FILEPATH]: 'string',
91929243
[CODE_FILE_PATH]: 'string',
91939244
[CODE_FUNCTION]: 'string',
@@ -9611,6 +9662,7 @@ export type AttributeName =
96119662
| typeof BROWSER_SCRIPT_INVOKER_TYPE
96129663
| typeof BROWSER_SCRIPT_SOURCE_CHAR_POSITION
96139664
| typeof BROWSER_VERSION
9665+
| typeof BROWSER_WEB_VITAL_CLS_SOURCE_KEY
96149666
| typeof BROWSER_WEB_VITAL_CLS_VALUE
96159667
| typeof BROWSER_WEB_VITAL_INP_VALUE
96169668
| typeof BROWSER_WEB_VITAL_LCP_VALUE
@@ -9626,6 +9678,7 @@ export type AttributeName =
96269678
| typeof CLOUDFLARE_D1_ROWS_READ
96279679
| typeof CLOUDFLARE_D1_ROWS_WRITTEN
96289680
| typeof CLS
9681+
| typeof CLS_SOURCE_KEY
96299682
| typeof CODE_FILEPATH
96309683
| typeof CODE_FILE_PATH
96319684
| typeof CODE_FUNCTION
@@ -10593,6 +10646,19 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
1059310646
aliases: [SENTRY_BROWSER_VERSION],
1059410647
changelog: [{ version: '0.1.0', prs: [59, 127, 139] }],
1059510648
},
10649+
[BROWSER_WEB_VITAL_CLS_SOURCE_KEY]: {
10650+
brief: 'The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N',
10651+
type: 'string',
10652+
pii: {
10653+
isPii: 'maybe',
10654+
},
10655+
isInOtel: false,
10656+
hasDynamicSuffix: true,
10657+
example: 'body > div#app',
10658+
aliases: [CLS_SOURCE_KEY],
10659+
sdks: ['javascript-browser'],
10660+
changelog: [{ version: 'next', prs: [234] }],
10661+
},
1059610662
[BROWSER_WEB_VITAL_CLS_VALUE]: {
1059710663
brief: 'The value of the recorded Cumulative Layout Shift (CLS) web vital',
1059810664
type: 'double',
@@ -10771,6 +10837,23 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
1077110837
},
1077210838
],
1077310839
},
10840+
[CLS_SOURCE_KEY]: {
10841+
brief: 'The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N',
10842+
type: 'string',
10843+
pii: {
10844+
isPii: 'maybe',
10845+
},
10846+
isInOtel: false,
10847+
hasDynamicSuffix: true,
10848+
example: 'body > div#app',
10849+
deprecation: {
10850+
replacement: 'browser.web_vital.cls.source.<key>',
10851+
reason: 'The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.',
10852+
},
10853+
aliases: [BROWSER_WEB_VITAL_CLS_SOURCE_KEY],
10854+
sdks: ['javascript-browser'],
10855+
changelog: [{ version: 'next', prs: [234] }],
10856+
},
1077410857
[CODE_FILEPATH]: {
1077510858
brief:
1077610859
'The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path).',
@@ -15225,6 +15308,7 @@ export type Attributes = {
1522515308
[BROWSER_SCRIPT_INVOKER_TYPE]?: BROWSER_SCRIPT_INVOKER_TYPE_TYPE;
1522615309
[BROWSER_SCRIPT_SOURCE_CHAR_POSITION]?: BROWSER_SCRIPT_SOURCE_CHAR_POSITION_TYPE;
1522715310
[BROWSER_VERSION]?: BROWSER_VERSION_TYPE;
15311+
[BROWSER_WEB_VITAL_CLS_SOURCE_KEY]?: BROWSER_WEB_VITAL_CLS_SOURCE_KEY_TYPE;
1522815312
[BROWSER_WEB_VITAL_CLS_VALUE]?: BROWSER_WEB_VITAL_CLS_VALUE_TYPE;
1522915313
[BROWSER_WEB_VITAL_INP_VALUE]?: BROWSER_WEB_VITAL_INP_VALUE_TYPE;
1523015314
[BROWSER_WEB_VITAL_LCP_VALUE]?: BROWSER_WEB_VITAL_LCP_VALUE_TYPE;
@@ -15240,6 +15324,7 @@ export type Attributes = {
1524015324
[CLOUDFLARE_D1_ROWS_READ]?: CLOUDFLARE_D1_ROWS_READ_TYPE;
1524115325
[CLOUDFLARE_D1_ROWS_WRITTEN]?: CLOUDFLARE_D1_ROWS_WRITTEN_TYPE;
1524215326
[CLS]?: CLS_TYPE;
15327+
[CLS_SOURCE_KEY]?: CLS_SOURCE_KEY_TYPE;
1524315328
[CODE_FILEPATH]?: CODE_FILEPATH_TYPE;
1524415329
[CODE_FILE_PATH]?: CODE_FILE_PATH_TYPE;
1524515330
[CODE_FUNCTION]?: CODE_FUNCTION_TYPE;

‎model/attributes/browser/browser__web_vital__cls__source__[key].json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"key": "browser.web_vital.cls.source.<key>",
3+
"brief": "The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
4+
"type": "string",
5+
"pii": {
6+
"key": "maybe"
7+
},
8+
"is_in_otel": false,
9+
"example": "body > div#app",
10+
"alias": ["cls.source.<key>"],
11+
"sdks": ["javascript-browser"],
12+
"has_dynamic_suffix": true,
13+
"changelog": [
14+
{
15+
"version": "next",
16+
"prs": [234]
17+
}
18+
]
19+
}

‎model/attributes/cls/cls__source__[key].json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"key": "cls.source.<key>",
3+
"brief": "The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
4+
"type": "string",
5+
"pii": {
6+
"key": "maybe"
7+
},
8+
"is_in_otel": false,
9+
"example": "body > div#app",
10+
"sdks": ["javascript-browser"],
11+
"deprecation": {
12+
"replacement": "browser.web_vital.cls.source.<key>",
13+
"reason": "The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.",
14+
"_status": "backfill"
15+
},
16+
"has_dynamic_suffix": true,
17+
"alias": ["browser.web_vital.cls.source.<key>"],
18+
"changelog": [
19+
{
20+
"version": "next",
21+
"prs": [234]
22+
}
23+
]
24+
}

‎python/src/sentry_conventions/attributes.py‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ class _AttributeNamesMeta(type):
136136
"AI_TOTAL_COST",
137137
"AI_TOTAL_TOKENS_USED",
138138
"AI_WARNINGS",
139+
"CLS_SOURCE_KEY",
139140
"CLS",
140141
"CODE_FILEPATH",
141142
"CODE_FUNCTION",
@@ -689,6 +690,20 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
689690
Example: "120.0.6099.130"
690691
"""
691692

693+
# Path: model/attributes/browser/browser__web_vital__cls__source__[key].json
694+
BROWSER_WEB_VITAL_CLS_SOURCE_KEY: Literal["browser.web_vital.cls.source.<key>"] = (
695+
"browser.web_vital.cls.source.<key>"
696+
)
697+
"""The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N
698+
699+
Type: str
700+
Contains PII: maybe
701+
Defined in OTEL: No
702+
Has Dynamic Suffix: true
703+
Aliases: cls.source.<key>
704+
Example: "body > div#app"
705+
"""
706+
692707
# Path: model/attributes/browser/browser__web_vital__cls__value.json
693708
BROWSER_WEB_VITAL_CLS_VALUE: Literal["browser.web_vital.cls.value"] = (
694709
"browser.web_vital.cls.value"
@@ -843,6 +858,19 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
843858
Example: 12
844859
"""
845860

861+
# Path: model/attributes/cls/cls__source__[key].json
862+
CLS_SOURCE_KEY: Literal["cls.source.<key>"] = "cls.source.<key>"
863+
"""The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N
864+
865+
Type: str
866+
Contains PII: maybe
867+
Defined in OTEL: No
868+
Has Dynamic Suffix: true
869+
Aliases: browser.web_vital.cls.source.<key>
870+
DEPRECATED: Use browser.web_vital.cls.source.<key> instead - The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.
871+
Example: "body > div#app"
872+
"""
873+
846874
# Path: model/attributes/cls.json
847875
CLS: Literal["cls"] = "cls"
848876
"""The value of the recorded Cumulative Layout Shift (CLS) web vital
@@ -5547,6 +5575,19 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
55475575
ChangelogEntry(version="0.1.0", prs=[59, 127, 139]),
55485576
],
55495577
),
5578+
"browser.web_vital.cls.source.<key>": AttributeMetadata(
5579+
brief="The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
5580+
type=AttributeType.STRING,
5581+
pii=PiiInfo(isPii=IsPii.MAYBE),
5582+
is_in_otel=False,
5583+
has_dynamic_suffix=True,
5584+
example="body > div#app",
5585+
aliases=["cls.source.<key>"],
5586+
sdks=["javascript-browser"],
5587+
changelog=[
5588+
ChangelogEntry(version="next", prs=[234]),
5589+
],
5590+
),
55505591
"browser.web_vital.cls.value": AttributeMetadata(
55515592
brief="The value of the recorded Cumulative Layout Shift (CLS) web vital",
55525593
type=AttributeType.DOUBLE,
@@ -5723,6 +5764,24 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
57235764
ChangelogEntry(version="0.0.0"),
57245765
],
57255766
),
5767+
"cls.source.<key>": AttributeMetadata(
5768+
brief="The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
5769+
type=AttributeType.STRING,
5770+
pii=PiiInfo(isPii=IsPii.MAYBE),
5771+
is_in_otel=False,
5772+
has_dynamic_suffix=True,
5773+
example="body > div#app",
5774+
deprecation=DeprecationInfo(
5775+
replacement="browser.web_vital.cls.source.<key>",
5776+
reason="The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.",
5777+
status=DeprecationStatus.BACKFILL,
5778+
),
5779+
aliases=["browser.web_vital.cls.source.<key>"],
5780+
sdks=["javascript-browser"],
5781+
changelog=[
5782+
ChangelogEntry(version="next", prs=[234]),
5783+
],
5784+
),
57265785
"cls": AttributeMetadata(
57275786
brief="The value of the recorded Cumulative Layout Shift (CLS) web vital",
57285787
type=AttributeType.DOUBLE,
@@ -10124,6 +10183,7 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
1012410183
"browser.script.invoker_type": str,
1012510184
"browser.script.source_char_position": int,
1012610185
"browser.version": str,
10186+
"browser.web_vital.cls.source.<key>": str,
1012710187
"browser.web_vital.cls.value": float,
1012810188
"browser.web_vital.inp.value": float,
1012910189
"browser.web_vital.lcp.value": float,
@@ -10138,6 +10198,7 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
1013810198
"cloudflare.d1.duration": int,
1013910199
"cloudflare.d1.rows_read": int,
1014010200
"cloudflare.d1.rows_written": int,
10201+
"cls.source.<key>": str,
1014110202
"cls": float,
1014210203
"code.file.path": str,
1014310204
"code.filepath": str,

‎shared/deprecated_attributes.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1059,6 +1059,30 @@
10591059
}
10601060
]
10611061
},
1062+
{
1063+
"key": "cls.source.<key>",
1064+
"brief": "The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N",
1065+
"type": "string",
1066+
"pii": {
1067+
"key": "maybe"
1068+
},
1069+
"is_in_otel": false,
1070+
"example": "body > div#app",
1071+
"sdks": ["javascript-browser"],
1072+
"deprecation": {
1073+
"replacement": "browser.web_vital.cls.source.<key>",
1074+
"reason": "The CLS source is now recorded as a browser.web_vital.cls.source.<key> attribute.",
1075+
"_status": "backfill"
1076+
},
1077+
"has_dynamic_suffix": true,
1078+
"alias": ["browser.web_vital.cls.source.<key>"],
1079+
"changelog": [
1080+
{
1081+
"version": "next",
1082+
"prs": [234]
1083+
}
1084+
]
1085+
},
10621086
{
10631087
"key": "code.filepath",
10641088
"brief": "The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path).",

0 commit comments

Comments
 (0)