Monitor the systems your product depends on

Uptrail checks services from the server where it is deployed. That detail matters: a target that is reachable from your laptop may not be reachable from the Uptrail process, container, or private network. Design checks around the path your production users and workloads actually take.

1. 1

   Open the control plane

   Sign in, create or select a workspace, then open Monitors. Workspace boundaries isolate monitors, incidents, settings, and members.
2. 2

   Create a service group

   Use a stable product or capability name such as Checkout API. A group rolls its child monitor states into one status-page service.
3. 3

   Add the first monitor

   Choose the protocol, enter its connection details, and keep the initial interval at 60 seconds. Start with three down retries to filter brief network noise.
4. 4

   Run Check now

   Trigger an immediate check. Confirm the response code, matched value, latency, and any error before relying on scheduled checks.
5. 5

   Configure alert delivery

   Add workspace notification destinations, then test a controlled failure. An alerting system is only complete after the delivery path is verified.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "dependencies": {
    "database": "ok"
  }
}

Uptrail consists of a static marketing site, a Vite-built React control plane, an Express API, a background monitor scheduler, WebSocket updates, and a MySQL application database. In production, run one authoritative scheduler process unless you have explicitly added distributed locking; duplicate schedulers can perform duplicate checks and alerts.

Production checklist

1. 1

   Provision MySQL

   Create a dedicated database and least-privilege user. Back it up on the same schedule as other operational data.
2. 2

   Build the client

   Install dependencies and run npm run build. Set VITE_API_BASE_URL before building only when the API lives on another origin.
3. 3

   Set production secrets

   At minimum set NODE_ENV=production, a random SESSION_SECRET, database credentials, APP_BASE_URL, and the exact CORS_ORIGINS.
4. 4

   Place behind TLS

   Terminate HTTPS at a trusted reverse proxy, forward WebSocket upgrades for /ws, and set TRUST_PROXY=true.
5. 5

   Verify network reachability

   Allow the Uptrail host to reach every monitored host and port. Restrict inbound access to the UI/API and outbound access to only required targets where practical.

NODE_ENV=production
PORT=3001
APP_BASE_URL=https://uptime.example.com
CORS_ORIGINS=https://uptime.example.com
TRUST_PROXY=true
SESSION_SECRET=replace-with-at-least-32-random-bytes

MYSQL_HOST=mysql.internal
MYSQL_PORT=3306
MYSQL_USER=uptrail
MYSQL_PASSWORD=replace-me
MYSQL_DATABASE=uptrail

RESEND_API_KEY=re_...
EMAIL_FROM=Uptrail <[email protected]>

Values are read when the server starts, except VITE_API_BASE_URL, which is compiled into the frontend at build time. Durations ending in _MS are milliseconds; monitor and cron form windows use seconds.

Every monitor belongs to a group and produces timestamped check runs. A check is successful only when the connection/probe completes and its configured assertion passes.

Retry timing example

With a 60-second interval and three down retries, a continuously failing service is normally marked down after the third failed check—approximately two to three minutes depending on where the failure begins relative to the schedule. Manual Check now is useful for diagnosis, but should not replace a realistic retry policy.

Use HTTP monitors for APIs, web applications, health endpoints, and authenticated synthetic requests. Uptrail sends the configured request and can assert both the status code and a value inside a JSON response.

URL: https://api.example.com/v1/health/deep
Method: POST
Headers JSON:
{
  "Authorization": "Bearer <read-only-token>",
  "Content-Type": "application/json"
}
Body:
{
  "check": ["database", "queue"]
}
Expected status: 200
Expected JSON path: status
Expected JSON value: ok

A MySQL monitor opens a fresh connection, runs one query, compares the first returned scalar value when an expectation is configured, then closes the connection. The default query is SELECT 1 AS health.

Connection JSON:
{
  "host": "mysql.internal",
  "port": 3306,
  "user": "uptrail_probe",
  "password": "<secret>",
  "database": "app_db",
  "connectTimeout": 5000
}

Probe command:
SELECT IF(@@read_only = 0, 'primary', 'replica') AS role

Expected probe value:
"primary"

PostgreSQL checks follow the same assertion model as MySQL: connect, execute one query, inspect the first scalar value, and disconnect. The default probe is SELECT 1 AS health.

Connection JSON:
{
  "host": "postgres.internal",
  "port": 5432,
  "user": "uptrail_probe",
  "password": "<secret>",
  "database": "app_db",
  "ssl": { "rejectUnauthorized": true },
  "connectionTimeoutMillis": 5000
}

Probe command:
SELECT CASE WHEN pg_is_in_recovery() THEN 'replica' ELSE 'primary' END

Expected probe value:
"primary"

Redis monitors connect, issue one command, optionally assert the response, and close cleanly. The default command is PING and its default expectation is "PONG".

# Simple whitespace form
GET uptime:sentinel

# Unambiguous JSON-array form
["SET", "uptime:last_probe", "healthy service", "EX", "120"]

# Typical read-only assertion
Probe command: GET app:deployment
Expected probe value: "2026.06.29"

Nats checks connect to one or more servers and execute a JetStream-aware probe. Use jetstream.info for general availability, stream.info for a critical stream, and consumer-lag probes when backlog growth is the operational risk.

Connection JSON

Every supported probe command

Connection JSON:
{
  "servers": [
    "nats://nats-a.internal:4222",
    "nats://nats-b.internal:4222"
  ],
  "user": "uptrail_probe",
  "pass": "<secret>",
  "name": "uptrail-production",
  "timeoutMs": 5000,
  "lag_thresholds": {
    "ORDERS_WORKER": 250,
    "EMAIL_WORKER": 1000,
    "default": 500
  }
}

Probe command:
consumer.lag:ORDERS:ORDERS_WORKER:200

Expected probe value:
"ok"

How consumer lag is evaluated

Uptrail evaluates pending acknowledgement count, waiting pull requests, pending delivery, and changes from the previous sample. A consumer is reported as lagging when its computed backlog exceeds the effective threshold. Threshold selection is deterministic:

1. Consumer-specific key in the monitor’s lag_thresholds.
2. Threshold appended to the probe command.
3. default in the monitor’s lag_thresholds.
4. Built-in fallback of 128.

TCP monitors test whether a socket can be opened. They are ideal for basic reachability of protocols without a dedicated Uptrail probe, but they do not prove that the application protocol is healthy.

{
  "host": "smtp.internal",
  "port": 587,
  "timeoutMs": 5000
}

Expected probe value: "open"

Cron monitoring tracks whether scheduled work starts and, optionally, continues to report progress. Enable cron monitoring at the workspace level, then define each job’s schedule, delivery mechanism, and timing windows.

HTTP cron triggers call an endpoint with GET or POST. Use GET only for an idempotent trigger; use POST when creating a run or sending a payload.

Trigger type: HTTP
Method: POST
Endpoint: https://jobs.example.com/v1/run/nightly-report
Headers JSON:
{
  "Authorization": "Bearer <job-trigger-token>",
  "Content-Type": "application/json"
}
Body:
{
  "source": "uptrail",
  "job": "nightly-report"
}

Nats triggers publish the cron payload to a subject. Configure the workspace connection first under Settings → Nats Cron Trigger; these credentials are separate from Nats service-monitor connection JSON.

# Shared worker with job name in payload
crons.uptrail

# Environment-scoped subjects
production.crons.billing
staging.crons.billing

Open an incident when users need context beyond a red monitor. The title should name the customer-visible symptom, while updates explain impact, investigation, mitigation, and recovery.

1. 1

   Open

   Use a concise title such as “Elevated checkout failures” and include the observed impact in the first message.
2. 2

   Update

   Post material changes: confirmed scope, workaround, mitigation deployed, and monitoring results. Avoid low-information updates.
3. 3

   Close

   Add a resolution note stating what recovered and how it was verified. Closing moves the incident into the public history.

We identified elevated database lock contention affecting checkout writes.
A configuration change was deployed at 14:32 UTC. Error rates have returned
below 0.2%, and we are monitoring recovery before resolving the incident.

The incident timeline records who opened, updated, and closed the incident. Editors can mutate incidents; viewers can inspect them. Press Escape or use the circular close control to dismiss the incident detail dialog without changing state.

The public incidents page exposes current health and incident history at a stable workspace URL. Open it from the Incidents header, copy the link, or copy the generated iframe snippet.

<iframe
  src="https://uptime.example.com/incidents-public/YOUR_PUBLIC_ID"
  width="100%"
  height="640"
  style="border:0"
  title="Service status"
  loading="lazy"
></iframe>

Notification settings are workspace-scoped. Configure destinations for monitor state changes and cron failures, then test both failure and recovery messages. Email requires server-level Resend configuration; workspace settings determine recipients and event behavior.

Use a team-owned destination rather than an individual inbox. Route critical production alerts to a staffed operational channel, and use lower-noise destinations for non-production workspaces.

Workspaces isolate configuration and membership. Owners and administrators should be limited to people who manage monitors, integrations, branding, and users. Editors can operate monitoring resources; viewers should receive read-only access when they only need visibility.