Merge pull request #24 from thegreenwebfoundation/ca-issue-21-add-sentry

Add sentry - resolves #21

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Fixed, Changed, Added, Removed, Fixed, Security
+
+## Unreleased
+
+
+- Add support for generating JSON Schema representation with CLI and API
+- Add support for using Sentry to track exceptions, performance and so on.
+
+## [0.0.7]
+
+### Added
+
+- First release using the formal changelog

docs/deployment.md

@@ -120,3 +120,20 @@ Django version 5.1.3, using settings 'local_config'
 Starting development server at http://127.0.0.1:8000/
 Quit the server with CONTROL-C.
 ```
+
+
+### Monitoring and tracking errors with Sentry
+
+The Django application served by the carbon.txt validator is set up to support instrumentation with Sentry.
+
+To activate it, you need to declare the `SENTRY_DSN`, `SENTRY_TRACE_SAMPLE_RATE` and `SENTRY_PROFILE_SAMPLE_RATE` environment variables when running the web server.
+
+The easiest way to do this is declare them in an .env file like so:
+
+```
+# .env
+
+SENTRY_DSN="https://LONG_ALPHANUMERIC_STRING.ingest.de.sentry.io/NUMERIC_ID"
+SENTRY_TRACE_SAMPLE_RATE="1.0"
+SENTRY_PROFILE_SAMPLE_RATE="1.0"
+```

justfile

@@ -32,6 +32,9 @@ test-watch *options:
 serve *options:
   uv run python ./src/carbon_txt/web/manage.py runserver {{ options }}
 
+manage *options:
+  uv run python ./src/carbon_txt/web/manage.py {{ options }}
+
 # generate docs into the docs/_build/html directory
 docs *options:
   uv run sphinx-build docs docs/_build/html {{ options }}

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "carbon-txt"
-version = "0.0.6"
+version = "0.0.7"
 description = "A command line tool containing a validator for carbon.txt files, by the Green Web Foundation"
 authors = [
     { name = "Chris Adams" },
@@ -19,6 +19,7 @@ dependencies = [
     "granian>=1.6.2",
     "httpx>=0.27.2",
     "rich>=13.9.2",
+    "sentry-sdk[django]>=2.18.0",
     # faster, but not yet supported by python 3.13 yet
     # "rtoml>=0.11.0",
     "typer>=0.12.5",

src/carbon_txt/web/config/settings/base.py

@@ -10,11 +10,12 @@
 https://docs.djangoproject.com/en/5.1/ref/settings/
 """
 
-import pathlib
-import environ
+import logging
 import os
+import pathlib
 
-import logging
+import environ
+import sentry_sdk
 
 from carbon_txt.exceptions import InsecureKeyException
 
@@ -30,6 +31,9 @@
     DEBUG=(bool, False),
     SECRET_KEY=(str, os.getenv("SECRET_KEY", DEFAULT_SECRET_KEY)),
     ENV_PATH=(str, ".env"),
+    SENTRY_DSN=(str, ""),
+    SENTRY_TRACE_SAMPLE_RATE=(float, 0),
+    SENTRY_PROFILE_SAMPLE_RATE=(float, 0),
 )
 
 # fetch environment variables from .env file
@@ -162,3 +166,16 @@
 # https://docs.djangoproject.com/en/5.1/ref/settings/#default-auto-field
 
 DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+
+if env("SENTRY_DSN"):
+    sentry_sdk.init(
+        dsn=env("SENTRY_DSN"),
+        # Set traces_sample_rate to 1.0 to capture 100%
+        # of transactions for tracing.
+        traces_sample_rate=env("SENTRY_TRACE_SAMPLE_RATE"),
+        # Set profiles_sample_rate to 1.0 to profile 100%
+        # of sampled transactions.
+        # We recommend adjusting this value in production.
+        profiles_sample_rate=env("SENTRY_PROFILE_SAMPLE_RATE"),
+    )