diff --git a/docs/administration/error-reporting.md b/docs/administration/error-reporting.md index 8ec83bdf0..e04372338 100644 --- a/docs/administration/error-reporting.md +++ b/docs/administration/error-reporting.md @@ -2,7 +2,17 @@ ## Sentry -NetBox v3.2.3 and later support native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this feature, begin by creating a new project in Sentry to represent your NetBox deployment and obtain its corresponding data source name (DSN). This looks like a URL similar to the example below: +### Enabling Error Reporting + +NetBox v3.2.3 and later support native integration with [Sentry](https://sentry.io/) for automatic error reporting. To enable this functionality, simply set `SENTRY_ENABLED` to True in `configuration.py`. Errors will be sent to a Sentry ingestor maintained by the NetBox team for analysis. + +```python +SENTRY_ENABLED = True +``` + +### Using a Custom DSN + +If you prefer instead to use your own Sentry ingestor, you'll need to first create a new project under your Sentry account to represent your NetBox deployment and obtain its corresponding data source name (DSN). This looks like a URL similar to the example below: ``` https://examplePublicKey@o0.ingest.sentry.io/0 @@ -12,9 +22,11 @@ Once you have obtained a DSN, configure Sentry in NetBox's `configuration.py` fi ```python SENTRY_ENABLED = True -SENTRY_DSN = "https://YourDSNgoesHere@o0.ingest.sentry.io/0" +SENTRY_DSN = "https://examplePublicKey@o0.ingest.sentry.io/0" ``` +### Assigning Tags + You can optionally attach one or more arbitrary tags to the outgoing error reports if desired by setting the `SENTRY_TAGS` parameter: ```python @@ -24,6 +36,11 @@ SENTRY_TAGS = { } ``` +!!! warning "Reserved tag prefixes" + Avoid using any tag names which begin with `netbox.`, as this prefix is reserved by the NetBox application. + +### Testing + Once the configuration has been saved, restart the NetBox service. -To test Sentry operation, try generating a 404 (page not found) error by navigating to an invalid URL, such as `https://netbox/404-error-testing`. After receiving a 404 response from the NetBox server, you should see the issue appear shortly in Sentry. +To test Sentry operation, try generating a 404 (page not found) error by navigating to an invalid URL, such as `https://netbox/404-error-testing`. (Be sure that debug mode has been disabled.) After receiving a 404 response from the NetBox server, you should see the issue appear shortly in Sentry. diff --git a/docs/configuration/optional-settings.md b/docs/configuration/optional-settings.md index 4a2d62e91..58f8cb526 100644 --- a/docs/configuration/optional-settings.md +++ b/docs/configuration/optional-settings.md @@ -426,7 +426,7 @@ Set to True to enable automatic error reporting via [Sentry](https://sentry.io/) ## SENTRY_TAGS -An optional dictionary of tags to apply to Sentry error reports. `SENTRY_ENABLED` must be True for this parameter to take effect. For example: +An optional dictionary of tag names and values to apply to Sentry error reports. `SENTRY_ENABLED` must be True for this parameter to take effect. For example: ``` SENTRY_TAGS = { @@ -435,6 +435,9 @@ SENTRY_TAGS = { } ``` +!!! warning "Reserved tag prefixes" + Avoid using any tag names which begin with `netbox.`, as this prefix is reserved by the NetBox application. + --- ## SESSION_COOKIE_NAME diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py index e539ecbbe..2dfbf9be6 100644 --- a/netbox/netbox/settings.py +++ b/netbox/netbox/settings.py @@ -1,3 +1,4 @@ +import hashlib import importlib import logging import os @@ -42,6 +43,7 @@ if sys.version_info < (3, 8): f"NetBox requires Python 3.8 or later. (Currently installed: Python {platform.python_version()})" ) +DEFAULT_SENTRY_DSN = 'https://198cf560b29d4054ab8e583a1d10ea58@o1242133.ingest.sentry.io/6396485' # # Configuration import @@ -115,7 +117,7 @@ REMOTE_AUTH_GROUP_SEPARATOR = getattr(configuration, 'REMOTE_AUTH_GROUP_SEPARATO REPORTS_ROOT = getattr(configuration, 'REPORTS_ROOT', os.path.join(BASE_DIR, 'reports')).rstrip('/') RQ_DEFAULT_TIMEOUT = getattr(configuration, 'RQ_DEFAULT_TIMEOUT', 300) SCRIPTS_ROOT = getattr(configuration, 'SCRIPTS_ROOT', os.path.join(BASE_DIR, 'scripts')).rstrip('/') -SENTRY_DSN = getattr(configuration, 'SENTRY_DSN', None) +SENTRY_DSN = getattr(configuration, 'SENTRY_DSN', DEFAULT_SENTRY_DSN) SENTRY_ENABLED = getattr(configuration, 'SENTRY_ENABLED', False) SENTRY_TAGS = getattr(configuration, 'SENTRY_TAGS', {}) SESSION_FILE_PATH = getattr(configuration, 'SESSION_FILE_PATH', None) @@ -451,6 +453,12 @@ if SENTRY_ENABLED: ) for k, v in SENTRY_TAGS.items(): sentry_sdk.set_tag(k, v) + # If using the default DSN, append a unique deployment ID tag for error correlation + if SENTRY_DSN == DEFAULT_SENTRY_DSN: + sentry_sdk.set_tag( + 'netbox.deployment_id', + hashlib.sha256(SECRET_KEY.encode('utf-8')).hexdigest()[:16] + ) #