DM-47716: Add optional support for Sentry

changelog.d/20241120_151854_rra_DM_47716_queue.md

@@ -0,0 +1,7 @@
+### New features
+
+- Add optional [Sentry](https://sentry.io/welcome/) support. If enabled and configured with the Sentry DSN secret, telemetry information will be sent to Sentry. Every trace is sampled and no effort has been made to exclude sensitive information, so this is currently only intended to be temporarily enabled in a non-production environment while debugging a specific problem.
+
+### Other changes
+
+- Update the Gafaelfawr secrets documentation with a link to the current Phalanx secrets management documentation and mark the secrets that are autogenerated by Phalanx tooling.

docs/_rst_epilog.rst

@@ -12,6 +12,7 @@
 .. _Sasquatch: https://sasquatch.lsst.io/
 .. _scriv: https://scriv.readthedocs.io/en/latest/
 .. _semver: https://semver.org/
+.. _Sentry: https://sentry.io/welcome/
 .. _structlog: https://www.structlog.org/en/stable/
 .. _tox: https://tox.wiki/en/latest/
 .. _uvicorn: https://www.uvicorn.org/

docs/dev/internals.rst

@@ -111,6 +111,9 @@ Python internal API
 .. automodapi:: gafaelfawr.pydantic
    :include-all-objects:
 
+.. automodapi:: gafaelfawr.sentry
+   :include-all-objects:
+
 .. automodapi:: gafaelfawr.services.admin
    :include-all-objects:
 

docs/user-guide/helm.rst

@@ -629,10 +629,13 @@ Set this with ``config.proxies``:
 If not set, defaults to the `RFC 1918 private address spaces <https://datatracker.ietf.org/doc/html/rfc1918>`__.
 See :ref:`client-ips` for more details.
 
+Alerts, metrics, and tracing
+============================
+
 .. _config-metrics:
 
 Metrics
-========
+-------
 
 Gafaelfawr can export events and metrics to Sasquatch_, the metrics system for Rubin Observatory.
 Metrics reporting is disabled by default.
@@ -670,7 +673,7 @@ There are some additional configuration settings, which normally will not need t
 .. _slack-alerts:
 
 Slack alerts
-============
+------------
 
 Gafaelfawr can optionally report uncaught exceptions to Slack.
 To enable this, set ``config.slackAlerts``:
@@ -682,6 +685,19 @@ To enable this, set ``config.slackAlerts``:
 
 You will also have to set the ``slack-webhook`` key in the Gafaelfawr secret to the URL of the incoming webhook to use to post these alerts.
 
+Sentry
+------
+
+Gafaelfawr can optionally report uncaught exceptions, traces, and performance information to Sentry_.
+To enable this, set ``config.enableSentry``:
+
+.. code-block:: yaml
+
+   config:
+     enableSentry: true
+
+You will also have to set the ``sentry-dsn`` key in the Gafaelfawr secret to the URL to which the telemetry will be sent.
+
 Maintenance
 ===========
 

docs/user-guide/secrets.rst

@@ -4,10 +4,13 @@
 Vault secrets
 #############
 
-Gafaelfawr uses secrets stored in `Vault`_ and uses `Vault Secrets Operator`_ to materialize those secrets in Kubernetes.
-The Phalanx installer expects a Vault secret named ``gafaelfawr`` in the relevant Science Platform environment containing the following keys:
+Gafaelfawr uses secrets stored in Vault_ and uses `Vault Secrets Operator`_ to materialize those secrets in Kubernetes.
 
-``bootstrap-token``
+The secrets marked autogenerated are automatically generated by the Phalanx secrets management tooling.
+See `Phalanx secrets management <https://phalanx.lsst.io/admin/secrets-setup.html>`__ for more information about how secrets are managed in Phalanx.
+Other secrets will need to be provided in the static secrets source used by the relevant Phalanx environment.
+
+``bootstrap-token`` (autogenerated)
     A Gafaelfawr token created with ``gafaelfawr generate-token`` (:doc:`CLI command <cli>`).
     Used to create service tokens, initialize admins, and do other privileged operations.
     See :ref:`bootstrapping` for more information.
@@ -45,15 +48,19 @@ The Phalanx installer expects a Vault secret named ``gafaelfawr`` in the relevan
     Must be a JSON list of objects, each of which must have ``id`` and ``secret`` keys corresponding to the ``client_id`` and ``client_secret`` parameters sent by OpenID Connect clients.
     See :ref:`openid-connect` for more information.
 
-``redis-password``
+``redis-password`` (autogenerated)
     The password to use for Redis authentication.
     This should be set to a long, randomly-generated alphanumeric string.
 
-``session-secret``
+``sentry-dsn`` (optional)
+    Sentry_ DSN URL to which to send telemetry information if Sentry is enabled.
+    Required if ``config.enableSentry`` is set to true.
+
+``session-secret`` (autogenerated)
     Encryption key for the Gafaelfawr session cookie.
     Generate with ``gafaelfawr generate-session-secret`` (:doc:`CLI command <cli>`).
 
-``signing-key`` (optional)
+``signing-key`` (optional, autogenerated)
     Only used if the Helm chart parameter ``config.oidcServer.enabled`` is set to true.
     The PEM-encoded RSA private key used to sign internally-issued JWTs.
     Generate with ``gafaelfawr generate-key`` (:doc:`CLI command <cli>`).

pyproject.toml

@@ -44,6 +44,7 @@ dependencies = [
     "pyyaml",
     "redis>=4.2.0",
     "safir[db,kubernetes]>=6.5.1",
+    "sentry-sdk[fastapi]",
     "sqlalchemy>=2.0.0",
     "structlog",
 ]