diff --git a/docs/user/debugging/android.md b/docs/user/debugging/android.md index a88f681145..661d17df2b 100644 --- a/docs/user/debugging/android.md +++ b/docs/user/debugging/android.md @@ -54,6 +54,12 @@ persist until the application is closed or manually reset. > --es tagPings test-metrics-ping > ``` +Debugging features in Android can also be enabled using environment variables. +For more information on the available features accessible through this method +and how to enable them, see [Enabling debugging features through environment variables](./index.md). + +These environment variables must be set on the device that is running the application. + ### Glean Log messages When running a Glean-powered app in the Android emulator or on a device connected to your computer via cable, there are several ways to read the log output. diff --git a/docs/user/debugging/index.md b/docs/user/debugging/index.md index 25f7798cb2..70233bced2 100644 --- a/docs/user/debugging/index.md +++ b/docs/user/debugging/index.md @@ -12,12 +12,25 @@ There are 3 available commands that you can use with the Glean SDK debug tools -- `logPings`: This is either true or false and will cause pings that are submitted to also be echoed to the device's log +- `logPings`: This is either true or false and will cause pings that are submitted to also be echoed to the device's log. - `tagPings`: This command will tag outgoing pings with the provided value, in order to identify them in the Glean Debug View. Tags need to be string with upper and lower case letters, numbers and dashes, with a max length of 20 characters. - `sendPing`: This command expects a string name of a ping to force immediate collection and submission of. Different platforms have different ways to send these commands. +### Enabling debugging features through environment variables + +Some of the debugging features described above may also be enabled using environment variables: + +- `logPings`: May be set by the `GLEAN_LOG_PINGS` environment variable. The accepted values are +`true` or `false`. Any other value will be ignored. +- `tagPings`: May be set by the `GLEAN_DEBUG_VIEW_TAG` environment variable. Any valid HTTP header value maybe set here +(e.g. any value that matches the regex `[a-zA-Z0-9-]{1,20}`). Invalid values will be ignored. + +These variables must be set at runtime, not at compile time. They will be checked upon Glean initialization. + +Enabling debugging features using environment variables is available for all supported platforms. + ### Important considerations when using Glean SDK debug tools - Options that are set using the flags are not immediately reset and will persist until the application is closed or manually reset. diff --git a/docs/user/debugging/ios.md b/docs/user/debugging/ios.md index 133b897f7a..8329d31cfd 100644 --- a/docs/user/debugging/ios.md +++ b/docs/user/debugging/ios.md @@ -2,6 +2,14 @@ For debugging and validation purposes on iOS, Glean makes use of a custom URL scheme which is implemented _within the application_ that is consuming Glean. Glean provides some convenience functions to facilitate this, but it's up to the consuming application to enable this functionality. Applications that enable this Glean SDK feature will be able to launch the application from a URL with the Glean debug commands embedded in the URL itself. +Debugging features in iOS can also be enabled using environment variables. +For more information on the available features accessible through this method +and how to enable them, see [Enabling debugging features through environment variables](./index.md). + +These environment variables must be set on the device that is running the application. + +> **Note** To set environment variables to the process running your app in an iOS device or emulator you need to edit the scheme for your app. In the Xcode IDE, you can use the shortcut `Cmd + <` to open the scheme editor popup. The environment variables editor is under the `Arguments` tab on this popup. + ### Available commands and query format There are 3 available commands that you can use with the Glean SDK debug tools diff --git a/docs/user/debugging/python.md b/docs/user/debugging/python.md index f2cde1d709..5dff863000 100644 --- a/docs/user/debugging/python.md +++ b/docs/user/debugging/python.md @@ -1,37 +1,24 @@ # Debugging Python applications using the Glean SDK -Glean provides a couple of configuration flags to assist with debugging Python applications. +Debugging features in Python can be enabled using environment variables. +For more information on the available features and how to enable them, +see [Enabling debugging features through environment variables](./index.md). -## Tagging pings +## Sending pings -The `Glean.configuration.ping_tag` property can be used to add a special flag to the HTTP header so that the ping will end up in the [Glean Debug View](./debug-ping-view.md). +Unlike other platforms, Python doesn't expose convenience methods to send pings on demand. -You can set it after `Glean.initialize` is called: - -```py -from Glean import Glean, Configuration -Glean.initialize( - application_id="my-app-id", - application_version="0.1.0", - upload_enabled=True, -) - -# ... - -Glean.configuration.ping_tag = "my-ping-tag" -``` - -After doing so, something like `pings.custom_ping.submit()` will send the custom ping to the Glean Debug View. +In case that is necessary, calling the `submit` function for a given ping, +such as `pings.custom_ping.submit()`, will send it. ## Logging pings -If the `Glean.configuration.log_pings` property is set to `True`, pings are -logged to the console on `DEBUG` level whenever they are submitted. You can set -this property in a similar way as the `ping_tag` property above. +If the `GLEAN_LOG_PINGS` environment variable is set to `true`, pings are +logged to the console on `DEBUG` level whenever they are submitted. Make sure that when you configure logging in your application, you set the level for the `glean` logger to `DEBUG` or higher. Otherwise pings won't be -logged even if `log_pings` is set to `True`. +logged even if `GLEAN_LOG_PINGS` is set to `true`. You can set the logging level for Glean to `DEBUG` as follows: