From a76e0c37126397ecb0e993d8dcd8cedf43b9cf09 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 12 Dec 2024 09:38:17 +0100 Subject: [PATCH 1/3] feat(develop-docs): SDK Debug Mode Add docs for the SDK debug mode. Explain that SDKs can choose the default log level themselves. --- develop-docs/sdk/expected-features/index.mdx | 21 ++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index cead4316a1f2b..b85588fffd34e 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -77,6 +77,27 @@ Backend SDKs (typically used in server applications) should have backpressure ma See Backpressure Management for details. +## Debug Mode + +Every SDK must implement a debug mode, which is disabled by default. Users can enable it by setting the option `debug` to `true`. If the debug mode is enabled, the SDK prints out useful debugging information for two main purposes: + + 1. It helps users identify and fix SDK problems, such as misconfigurations or something going wrong with sending data to Sentry. + 2. It can help Sentry SDK engineers investigate issues in Sentry SDKs, which can be done while developing or by asking a user to enable the debug mode and share the debug logs. + +As the log output can add unnecessary overhead, we advise users to refrain from enabling this in production. When using debug mode extensively for the second use case, we recommend adding the diagnostic level because users could easily miss error or fatal log messages. + +### Diagnostic Level + +SDKs may offer an optional diagnostic level, which controls the verbosity of the debug mode. There are five different levels: + +- `debug`: The most verbose mode +- `info`: Informational messages +- `warning`: Warning that something might not be right +- `error`: Only SDK internal errors are printed +- `fatal`: Only critical errors are printed + +The default level can be **debug** or **error** depending on the SDK's usage of log messages. When the volume of log message is low, the default can be debug. When it is high, users might easily miss errors or fatal messages. In that case, the SDK should set the default level to **error**. This choice must be clearly documented in the user-facing docs. + ## In-App frames Stack parsing can tell which frames should be identified as part of the user’s application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix. From 2c61a336da404d58f8d8efe7189636b6ae750fd8 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 12 Dec 2024 10:12:48 +0100 Subject: [PATCH 2/3] add auto debug mode --- develop-docs/sdk/expected-features/index.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index b85588fffd34e..2e8773ed96503 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -98,6 +98,10 @@ SDKs may offer an optional diagnostic level, which controls the verbosity of the The default level can be **debug** or **error** depending on the SDK's usage of log messages. When the volume of log message is low, the default can be debug. When it is high, users might easily miss errors or fatal messages. In that case, the SDK should set the default level to **error**. This choice must be clearly documented in the user-facing docs. +### Auto Debug Mode + +So users can easily spot errors during development, the SDK can automatically enable debug mode when it reliably detects it's running in a debug build. When doing so, the SDK must communicate this in the docs and with a log message when initializing the SDK. When the user explicitly sets the `debug` option to `false`, the SDK must disable the debug mode. + ## In-App frames Stack parsing can tell which frames should be identified as part of the user’s application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix. From 2cb7755a8b2f6b0e79c02c0a906f0e10ca595db7 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Fri, 13 Dec 2024 10:56:20 +0100 Subject: [PATCH 3/3] code review --- develop-docs/sdk/expected-features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 2e8773ed96503..6e289961777ab 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -84,7 +84,7 @@ Every SDK must implement a debug mode, which is disabled by default. Users can e 1. It helps users identify and fix SDK problems, such as misconfigurations or something going wrong with sending data to Sentry. 2. It can help Sentry SDK engineers investigate issues in Sentry SDKs, which can be done while developing or by asking a user to enable the debug mode and share the debug logs. -As the log output can add unnecessary overhead, we advise users to refrain from enabling this in production. When using debug mode extensively for the second use case, we recommend adding the diagnostic level because users could easily miss error or fatal log messages. +As the log output can add unnecessary overhead, we advise users to refrain from enabling the debug mode in production. Still, SDKs may log fatal error messages even when the debug mode is disabled. When using debug mode extensively for the second use case, we recommend adding the diagnostic level because users could easily miss error or fatal log messages. ### Diagnostic Level