Sentry integration¶
gluetool
integrates easily with Sentry platform, simplifying the collection of trouble issues, code crashes, warnings and other important events your deployed code produces. This integration is optional - it must be explicitly enabled - and transparent - it is not necessary to report common events, like exceptions.
When enabled, every unhandled exception is automatically reported to Sentry. Helpers for explicit reporting of handled exceptions and warnings are available, as well as the bare method for reporting arbitrary events.
Control¶
Sentry integration is controlled by environmental variables. It must be possible to configure itilable even before gluetool
has a chance to process given options. To enable Sentry integration, one has to set at least SENTRY_DSN
variable:
export SENTRY_DSN="https://<key>:<secret>@sentry.io/<project>"
This variable tells Sentry-related code where it should report the events. Without this variable set, Sentry integration is disabled. All relevant functions still can be called but do not report any events to Sentry, since they don’t know where to send their reports.
See also
- About the DSN
- for detaield information on Sentry DSN and their use.
gluetool.sentry module
- for developer documentation.
Sentry tags & environment variables¶
Sentry allows attaching “tags” to reported events. To use environment variables as such tags, set SENTRY_TAG_MAP
variable. It lists comma-separated pairs of names, tag and its source variable.
export SENTRY_TAG_MAP="username=USER,hostname=HOSTNAME"
Should there be an event to report, integration code will attach 2 labels to it, username
and hostname
, using environmen variables USER
and HOSTNAME
respectively as source of values.
See also
- Tagging Events
- for detailed information on event tags.
Logging of submitted events¶
Integration code is able to log every reported event. To enable this feature, simply set SENTRY_BASE_URL
environment variable to URL of the project gluetool
is reporting events to. While SENTRY_DSN
controls the whole integration and has its meaning within Sentry server your gluetool
runs report to, SENTRY_BASE_URL
is used only in a cosmetic way and gluetool
code adds ID of reported event to it. The resulting URL, if followed, should lead to your project and the relevant event.
As you can see, the exception, raised by gluetool
when there were no command-line options telling it what to do, has been submitted to Sentry, and immediately logged, with ERROR
loglevel.
See also
- Sentry - Control
- for more information about Sentry integration.
Warnings¶
By default, only unhandled exceptions are submitted to Sentry. it is however possible, among others, to submit warnings, e.g. in case when such warning is good to capture yet it is not necessary to raise an exception and kill the whole gluetool
pipeline. For that case, warn
logging method accepts sentry
keword parameter, which, when set to True
, uses Sentry-related code to submit given message to the configured Sentry instance. It is also always logged like any other warning.
Example:
from gluetool.log import Logging
logger = Logging.create_logger()
logger.warn('foo', sentry=True)
Output:
[17:16:50] [W] foo
Todo
- video
See also
- Object logging helpers
- for more information on logging methods.
gluetool.log.warn_sentry()
- for developer documentation.
Todo
Features yet to describe:
- all env variables are attached to events (breadcrumbs)
- logging records are attached to events (breadcrumbs)
- URL of every reported event available for examination by code
- soft-error tag for failure.soft errors
- raised exceptions can provide custom fingerprints and tags
- submit_exception and submit_warning for explicit submissions
- logger.warn(sentry=True)