Debugging products using the Glean SDK
Platform-specific debugging
- Debugging Android applications using the Glean SDK
- Debugging iOS applications using the Glean SDK
- Debugging Python applications using the Glean SDK
General debugging information
Available debugging features
The Glean SDK has 4 available debugging features:
logPings
: This is eithertrue
orfalse
and will cause all subsequent pings that are submitted, to also be echoed to the device's log. Once enabled, the only way to disable this feature is to restart or manually reset the application.debugViewTag
: This will tag all subsequent outgoing pings with the provided value, in order to identify them in the Glean Debug View. Once enabled, the only way to disable this feature is to restart or manually reset the application.sourceTags
: This will tag all subsequent outgoing pings with a maximum of 5 comma-separated tags. Once enabled, the only way to disable this feature is to restart or manually reset the application.sendPing
: This expects the name of a ping and forces its immediate collection and submission. This feature is only available for Android and iOS.
Different platforms may have different ways to enable these features.
Enabling debugging features through environment variables
Some of the debugging features described above may be enabled using environment variables:
logPings
: May be set by theGLEAN_LOG_PINGS
environment variable. The accepted values aretrue
orfalse
. Any other value will be ignored.debugViewTag
: May be set by theGLEAN_DEBUG_VIEW_TAG
environment variable. Any valid HTTP header value is expected here (e.g. any value that matches the regex[a-zA-Z0-9-]{1,20}
). Invalid values will be ignored.sourceTags
: May be set by theGLEAN_SOURCE_TAGS
environment variable. A comma-separated list of valid HTTP header values is expected here (e.g. any value that matches the regex[a-zA-Z0-9-]{1,20}
). Invalid values will be ignored. The special value ofautomation
is meant for tagging pings generated on automation: such pings will be specially handled on the pipeline (i.e. discarded from non-live views).
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.
Note Although it is technically possible to use the environment variables described here to enable debugging features in Android, the Glean team is not currently aware of a proper way to set environment variables in Android devices or emulators.
Important considerations when using Glean SDK debug features
-
Enabled features will persist until the application is closed or manually reset. When enabled by environment variables, the variables need to be cleared upon resetting for the feature to be disabled.
-
There are a couple different ways in which to send pings using the Glean SDK debug tools.
- You can tag pings using the debug tools and trigger them manually using the UI. This should always produce a ping with all required fields.
- You can tag and send pings using the debug tools. This has the side effect of potentially sending a ping which does not include all fields because
sendPing
triggers pings to be sent before certain application behaviors can occur which would record that information. For example,duration
is not calculated or included in a baseline ping sent withsendPing
because it forces the ping to be sent before theduration
metric has been recorded. Keep in mind that there may be nothing to send, in which case no ping is generated. - You can trigger a command while the instrumented application is still running. This is useful for toggling commands or for triggering pings that have schedules that are difficult to trigger manually. This is especially useful if you need to trigger a ping submission after some activity within the application, such as with the metrics ping.
Glean SDK Log messages
The Glean SDK logs warnings and errors through the platform-specific logging frameworks. See the platform-specific instructions for information on how to view the logs.
Implementation details
See Debug Pings.