From e7f4b28cc79647b89b21c3bb871890dac241ad0a Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 14 Oct 2025 06:44:13 +0200 Subject: [PATCH 1/6] fix: Clarify error level impact on sessions Clarify in the develop docs that only events with level error or higher must mark sessions as errored. --- develop-docs/sdk/telemetry/sessions/index.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 29698b79548a2b..b8ca4a1ac1d232 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -271,7 +271,7 @@ not report any more session updates or start a new session. SDKs are encouraged to distinguish between different ways of ending a session: -- `exited`: this means the session ended cleanly. It's is the same as the +- `exited`: this means the session ended cleanly. It's is the same as the session staying in `ok` from the point of success reports. However only sessions ending in `exited` will be considered for session durations. A session is allowed to go to `exited` even if errors occurred. @@ -309,10 +309,12 @@ application restart to close the session as `abnormal`. Errored sessions are determined by an `errors` counter greater than zero. The client is required to count events that are considered errors and send the -count along with session updates. A session that is `ok` and has an error -count of greater than zero is considered an errored session. All crashed and -abnormal sessions are also at all times considered errored but subtracted from -the final errored session count. +count along with session updates. Only events with a level of `error` or higher +(such as `fatal`) must increment the errors counter. Events with a level of +`warning` or lower (such as `info` or `debug`) must not affect the session's +error count. A session that is `ok` and has an error count of greater than zero +is considered an errored session. All crashed and abnormal sessions are also at +all times considered errored but subtracted from the final errored session count. ### Exited From f198f61e5a5f30e27ca1cb887ac559f52b1b1723 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 14 Oct 2025 12:26:45 +0000 Subject: [PATCH 2/6] Refine session error tracking logic Co-authored-by: philipp.hofmann --- develop-docs/sdk/telemetry/sessions/index.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index b8ca4a1ac1d232..5b427134f8783b 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -309,12 +309,13 @@ application restart to close the session as `abnormal`. Errored sessions are determined by an `errors` counter greater than zero. The client is required to count events that are considered errors and send the -count along with session updates. Only events with a level of `error` or higher -(such as `fatal`) must increment the errors counter. Events with a level of -`warning` or lower (such as `info` or `debug`) must not affect the session's -error count. A session that is `ok` and has an error count of greater than zero -is considered an errored session. All crashed and abnormal sessions are also at -all times considered errored but subtracted from the final errored session count. +count along with session updates. Only events that stem from `captureException` or +`captureError` must increment the errors counter and affect the session's error +status. Events stemming from `captureEvent` or `captureMessage` must not affect +the session's error count, regardless of their log level. A session that is `ok` +and has an error count of greater than zero is considered an errored session. +All crashed and abnormal sessions are also at all times considered errored but +subtracted from the final errored session count. ### Exited From 616d47472d4962db9689e26e271aaa0ea5c89b18 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 14 Oct 2025 12:29:09 +0000 Subject: [PATCH 3/6] Refine session error tracking logic Co-authored-by: philipp.hofmann --- develop-docs/sdk/telemetry/sessions/index.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 5b427134f8783b..57d61d7ea58560 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -309,13 +309,14 @@ application restart to close the session as `abnormal`. Errored sessions are determined by an `errors` counter greater than zero. The client is required to count events that are considered errors and send the -count along with session updates. Only events that stem from `captureException` or +count along with session updates. Events that stem from `captureException` or `captureError` must increment the errors counter and affect the session's error -status. Events stemming from `captureEvent` or `captureMessage` must not affect -the session's error count, regardless of their log level. A session that is `ok` -and has an error count of greater than zero is considered an errored session. -All crashed and abnormal sessions are also at all times considered errored but -subtracted from the final errored session count. +status. Additionally, `captureEvent` can also increment the errors counter when +used to manually create exception events. Events stemming from `captureMessage` +must not affect the session's error count, regardless of their log level. A +session that is `ok` and has an error count of greater than zero is considered +an errored session. All crashed and abnormal sessions are also at all times +considered errored but subtracted from the final errored session count. ### Exited From 394469f336f1928c429b6deaaf2ad374bbf9f67c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 14 Oct 2025 12:31:36 +0000 Subject: [PATCH 4/6] Update session error tracking documentation Co-authored-by: philipp.hofmann --- develop-docs/sdk/telemetry/sessions/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 57d61d7ea58560..4fd44018b7b032 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -309,10 +309,10 @@ application restart to close the session as `abnormal`. Errored sessions are determined by an `errors` counter greater than zero. The client is required to count events that are considered errors and send the -count along with session updates. Events that stem from `captureException` or -`captureError` must increment the errors counter and affect the session's error -status. Additionally, `captureEvent` can also increment the errors counter when -used to manually create exception events. Events stemming from `captureMessage` +count along with session updates. Events that stem from `captureException`, +`captureError`, or `captureEvent` must increment the errors counter and affect +the session's error status. `captureEvent` is included because users might +manually create exception events with it. Events stemming from `captureMessage` must not affect the session's error count, regardless of their log level. A session that is `ok` and has an error count of greater than zero is considered an errored session. All crashed and abnormal sessions are also at all times From ad899c4721a5c3c130213dcddc3fa85da1c18734 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Tue, 14 Oct 2025 14:43:01 +0200 Subject: [PATCH 5/6] reword --- develop-docs/sdk/telemetry/sessions/index.mdx | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 4fd44018b7b032..6cb0813b5b5307 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -309,14 +309,19 @@ application restart to close the session as `abnormal`. Errored sessions are determined by an `errors` counter greater than zero. The client is required to count events that are considered errors and send the -count along with session updates. Events that stem from `captureException`, -`captureError`, or `captureEvent` must increment the errors counter and affect -the session's error status. `captureEvent` is included because users might -manually create exception events with it. Events stemming from `captureMessage` -must not affect the session's error count, regardless of their log level. A -session that is `ok` and has an error count of greater than zero is considered -an errored session. All crashed and abnormal sessions are also at all times -considered errored but subtracted from the final errored session count. +count along with session updates. A session that is `ok` and has an error +count of greater than zero is considered an errored session. All crashed and +abnormal sessions are also at all times considered errored but subtracted from +the final errored session count. + +Only events that stem from `captureException`, `captureError`, or `captureEvent` +must increment the `errors` counter when their level is `error` or higher. As SDKs +set the default level to `error` for these methods, a level lower than `error` +means the users changed it manually. This gives the users the ability to capture +error events not marking sessions as errored. `captureEvent` is included because +users might manually create exception events with it. Events stemming from +`captureMessage` must not affect the session's error count, regardless of their +log level. ### Exited From a5ef22f5947c5f6e0a530b5e8aeecf52043ffcb3 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Wed, 15 Oct 2025 10:49:53 +0200 Subject: [PATCH 6/6] add table --- develop-docs/sdk/telemetry/sessions/index.mdx | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/sessions/index.mdx b/develop-docs/sdk/telemetry/sessions/index.mdx index 6cb0813b5b5307..b5d10a9eaeead6 100644 --- a/develop-docs/sdk/telemetry/sessions/index.mdx +++ b/develop-docs/sdk/telemetry/sessions/index.mdx @@ -321,7 +321,21 @@ means the users changed it manually. This gives the users the ability to capture error events not marking sessions as errored. `captureEvent` is included because users might manually create exception events with it. Events stemming from `captureMessage` must not affect the session's error count, regardless of their -log level. +log level. For all methods, it doesn't matter if the event has a stack trace or not. +The following table summarizes the behavior of the methods: + +| method | level | increments `errors` counter | +| --- | --- | --- | +| captureException / captureError | `fatal` | `yes` | +| captureException / captureError | `error` | `yes` | +| captureException / captureError | `warning` | `no` | +| captureEvent | `fatal` | `yes` | +| captureEvent | `error` | `yes` | +| captureEvent | `warning` | `no` | +| captureMessage | `fatal` | `no` | +| captureMessage | `error` | `no` | +| captureMessage | `warning` | `no` | + ### Exited