Skip to main content

Sentry Plugin (Web Only)

This guide explains how to configure Sentry error and performance monitoring for a Zapp Web application. Sentry is wired into the web client at two layers: deployment-level environment variables and a Zapp dashboard plugin for runtime-tunable values.

Web only. The Sentry integration is only supported on the web target.

Prerequisites​

  • A Sentry account with access to an organization and project.
  • A DSN for the project (from Sentry → Settings → Projects → [your project] → Client Keys (DSN)).
  • The Zapp on-premises web release artifact (see below).
  • Access to the Zapp dashboard for the relevant app version (only needed if you want to tune sample rates per-app-version without redeploying).

Where to set environment variables​

Zapp delivers the web app as an on-premises release artifact — a folder containing a pre-populated Dockerfile along with assets and configuration files. You configure all environment variables inside this Dockerfile before building and hosting the image on your infrastructure.

A typical artifact folder looks like this:

1.9.9-81-web-release/
├── Dockerfile                       # populated with your app's configuration
├── docker-compose.version-test.yml  # for local testing
├── public-assets/
├── variables/
├── sourcemaps.zip
└── readme-first.md

Inside the Dockerfile you will already find Sentry-related placeholders, commented out:

# Uncomment and set value if you want to override the environment for Sentry
# ENV SENTRY_ENV=
# ENV SENTRY_SERVER_SAMPLE_RATE=
# ENV SENTRY_CLIENT_SAMPLE_RATE=
# ENV SENTRY_SERVER_TRACES_SAMPLE_RATE=
# ENV SENTRY_CLIENT_TRACES_SAMPLE_RATE=
# ENV SENTRY_SERVER_DEBUG=
# ENV SENTRY_CLIENT_DEBUG=

To enable Sentry, uncomment and set the values you need, and add the required SENTRY_DSN line (it is not pre-included in the placeholders). Then build and run the image as described in the artifact's readme-first.md.

Step 1 — Set the required environment variables​

At minimum, add SENTRY_DSN to the Dockerfile. Without it, Sentry initialization is skipped on both server and client and no events are sent.

# Required — add this line to the Dockerfile
ENV SENTRY_DSN=https://<key>@<org>.ingest.sentry.io/<project-id>

# Optional but recommended — environment label shown in Sentry events
# Falls back to NODE_ENV if unset
ENV SENTRY_ENV=production

After updating the Dockerfile, rebuild and redeploy the image. Sentry initializes automatically:

  • Server — initialized on app startup.
  • Client — initialized on first page render once the DSN reaches the browser via the root loader.

Step 2 — (Optional) Configure sample rates via environment variables​

Sample rates control what percentage of events and traces are sent to Sentry. Values are floats between 0.0 and 1.0. If unset, defaults are used.

# Server-side
ENV SENTRY_SERVER_SAMPLE_RATE=1.0           # error events. Default: 1.0
ENV SENTRY_SERVER_TRACES_SAMPLE_RATE=0.2    # performance traces. Default: 1.0

# Client-side
ENV SENTRY_CLIENT_SAMPLE_RATE=1.0           # error events. Default: 1.0
ENV SENTRY_CLIENT_TRACES_SAMPLE_RATE=0.2    # performance traces. Default: 1.0

For high-traffic production apps, lower the traces sample rate (e.g. 0.1–0.2) to control Sentry quota costs.

Step 3 — (Optional) Configure client sample rates from the Zapp dashboard​

The Sentry plugin in Zapp lets you tune client sample rates per app version without redeploying. This is useful when the same deployment serves multiple Zapp app versions that need different sampling.

  1. Open the Zapp dashboard and navigate to your app version.
  2. Open the plugins panel and add or open the Sentry plugin.
  3. Configure the following fields:
    • Client Sample Rate — fallback for SENTRY_CLIENT_SAMPLE_RATE (events). Defaults to 1.0.
    • Client Traces Sample Rate — fallback for SENTRY_CLIENT_TRACES_SAMPLE_RATE (performance traces). Defaults to 1.0.
  4. Save and publish the app version.

Precedence for client sample rates​

When the client initializes Sentry, sample rates resolve in this order:

  1. Environment variable (SENTRY_CLIENT_SAMPLE_RATE / SENTRY_CLIENT_TRACES_SAMPLE_RATE)
  2. Zapp plugin configuration value
  3. Default 1.0

Server sample rates are only read from environment variables — the Zapp plugin does not affect them.

Step 4 — (Optional) Enable debug logging​

To see detailed Sentry SDK output in the console (useful when verifying setup or debugging missing events):

ENV SENTRY_SERVER_DEBUG=true   # logs from server-side Sentry SDK
ENV SENTRY_CLIENT_DEBUG=true   # logs from client-side Sentry SDK

Disable these in production — they are verbose and add noise.

Step 5 — Verify the integration​

  1. Build and deploy the image with SENTRY_DSN set.
  2. Open the app in a browser and trigger an error (e.g. via a test route or throw new Error('sentry-test') temporarily added to a loader).
  3. Check the Sentry dashboard → Issues. The event should appear within a few seconds.
  4. If you do not see events, enable SENTRY_CLIENT_DEBUG=true / SENTRY_SERVER_DEBUG=true and check the browser console / server logs for SDK output indicating why initialization may have been skipped.