DEV Community

Vigilmon
Vigilmon

Posted on

How to Monitor Your Temporal.io Workflows with Vigilmon

#temporal #workflows #monitoring #devops

Temporal.io is a durable execution platform for long-running workflows. When Temporal goes down, your business logic stops — orders don't process, emails don't send, data pipelines halt. While Temporal has built-in visibility tools, you still need external uptime monitoring. Here's how to monitor Temporal with Vigilmon.

Temporal Architecture: What to Monitor

A Temporal deployment has multiple components:

  1. Temporal Server — the core service (frontend, history, matching, worker services)
  2. Web UI — the Temporal dashboard (default port 8080)
  3. Your Worker processes — your application code that executes workflows
  4. Persistence — Cassandra or PostgreSQL backend

Monitoring priorities:

  • Critical: Temporal frontend service (gRPC port 7233 or HTTP health)
  • Important: Your worker processes
  • Nice to have: Web UI

Health Check Endpoints

Temporal exposes HTTP health checks on the frontend service:

# Temporal server health (returns "SERVING" or similar)
curl http://temporal-frontend:7233/api/v1/cluster/health

# Or via the Temporal CLI
temporal operator cluster health
Enter fullscreen mode Exit fullscreen mode

For HTTP-based monitoring (what Vigilmon uses), use the cluster info endpoint:

GET http://your-temporal-host:7233/api/v1/cluster/info
Enter fullscreen mode Exit fullscreen mode

This returns cluster metadata and a 200 status if healthy.

Adding an HTTP Health Wrapper

If your Temporal frontend isn't directly accessible via HTTP (common in private networks), add a thin health service alongside your workers:

// healthServer.ts
import express from 'express'
import { Connection } from '@temporalio/client'

const app = express()

app.get('/health', async (req, res) => {
  try {
    const connection = await Connection.connect({
      address: process.env.TEMPORAL_ADDRESS || 'localhost:7233',
    })
    // Attempt to describe the default namespace
    const client = connection.workflowService
    await client.describeNamespace({ namespace: 'default' })
    res.json({ status: 'ok', temporal: 'connected' })
  } catch (err) {
    res.status(503).json({ status: 'error', message: String(err) })
  }
})

app.listen(8090, () => console.log('Health server on :8090'))
Enter fullscreen mode Exit fullscreen mode

Deploy this alongside your workers and point Vigilmon at http://your-worker-host:8090/health.

Monitoring Temporal Cloud

If you're using Temporal Cloud instead of self-hosting, you don't need to monitor the server itself (Temporal SLA covers that). Focus on monitoring your workers:

// Worker health check
app.get('/health', async (req, res) => {
  // Check if worker is registered and processing
  if (worker.getState() === 'RUNNING') {
    res.json({ status: 'ok' })
  } else {
    res.status(503).json({ status: 'degraded', state: worker.getState() })
  }
})
Enter fullscreen mode Exit fullscreen mode

Setting Up Vigilmon

  1. Sign up at vigilmon.online (free tier: 5 monitors)

  2. Create a monitor for your Temporal health endpoint:

Setting Value
URL http://your-temporal-host:8090/health
Method GET
Interval 60 seconds
Expected status 200
Keyword ok
  1. Optionally add the Temporal Web UI as a second monitor: 
URL: http://your-temporal-host:8080
Expected status: 200
Enter fullscreen mode Exit fullscreen mode

What Breaks When Temporal Goes Down

Immediately:

  • New workflow executions can't start
  • Signal and query RPCs fail
  • Activity schedules pause

Within seconds-to-minutes:

  • In-flight workflows pause (they resume when Temporal comes back — that's the durability guarantee)
  • Worker SDK reconnect attempts fail, filling logs with errors

Business impact (depending on your use case):

  • Order processing halts
  • Background jobs stop
  • Email/notification pipelines freeze
  • Data sync workflows pause

Alerting Strategy

For Temporal production:

  • PagerDuty/on-call: if your workflows are business-critical
  • Slack webhook: for engineering teams
  • Email: for smaller setups

Vigilmon supports email alerts (free) and webhooks (for Slack, Discord, or custom HTTP endpoints).

Checking Workflow Backlog

Temporal Web UI shows workflow backlog — but only if the server is up. For proactive monitoring of workflow lag, use Temporal's SDK to export metrics (Prometheus endpoint) and alert on:

  • temporal_workflow_task_schedule_to_start_latency — queue wait time
  • temporal_activity_schedule_to_start_latency — activity lag

Vigilmon handles uptime; Temporal's built-in metrics handle performance. Both are necessary.

Summary

Temporal monitoring with Vigilmon:

  1. Expose an HTTP health endpoint from your workers (or use Temporal's built-in API endpoint)
  2. Create a Vigilmon monitor pointing at it
  3. Set up email or webhook alert
  4. Know within 60 seconds if your workflow engine is down

Start monitoring your Temporal setup free on Vigilmon →

Top comments (0)