tutorial

How to Monitor Lightrun with Vigilmon (HTTP + TCP + Alerts)

Lightrun is a live code debugging and observability platform that lets developers insert dynamic logs, non-breaking breakpoints, and metrics directly into ru...

Lightrun is a live code debugging and observability platform that lets developers insert dynamic logs, non-breaking breakpoints, and metrics directly into running production applications — without redeploying. Its management server coordinates all agent connections, stores snapshots, manages licensing, and serves the web console. When it goes down, every agent attached to your Java, Node.js, or Python services loses its communication channel: debugging sessions vanish, snapshots stop collecting, and your team is blind to production behaviour until the server comes back up. Vigilmon's free tier lets you monitor the Lightrun management server with HTTP and TCP checks so you get alerted before your developers start filing confused tickets.

Why Lightrun needs external monitoring

  • Management server crash: When the Lightrun server process dies, all WebSocket connections from attached agents are severed immediately. Agents enter a reconnection loop but cannot deliver snapshots or accept new instrumentation commands. The failure is silent to developers — the IDE plugin shows a disconnected state, but there is no automatic alert to operations teams unless external monitoring is in place.

  • Database connection failure: Lightrun stores snapshots, audit logs, and agent registration records in a relational database. If the database becomes unreachable — due to a network partition, disk exhaustion, or a credentials rotation — the management server may continue to respond on the network while silently failing to persist any data. Snapshots appear to be collected but are never written, and developers lose debugging history without any obvious error.

  • Agent registration failure: New agents starting up attempt to register with the management server over HTTPS and then establish a persistent WebSocket connection for command delivery. If the registration endpoint is overloaded or misconfigured after a deployment, freshly started application instances cannot attach. The application itself runs fine, which makes this failure invisible to standard uptime monitors that only watch the application process.

  • WebSocket connection drops: Lightrun agents maintain a long-lived WebSocket connection back to the management server to receive instrumentation commands in real time. A load balancer timeout, a TLS certificate renewal, or a network policy change can silently drop these connections. The agent reconnects in the background, but any breakpoints or dynamic logs added during the disconnection window are lost without notification.

  • Licensing service unavailability: Lightrun enforces seat limits and feature availability through its licensing subsystem. If the licensing service component becomes unreachable — either because it is a remote endpoint for SaaS-licensed deployments or an internal component for on-premise — agents may be refused new instrumentation requests even though the management server itself appears healthy from the outside.

What you'll need

  • A running Lightrun management server deployment (self-hosted on-premise, self-hosted on a cloud VM, or access to the SaaS endpoint at app.lightrun.com)
  • A reachable URL or IP address for the management server, with its health or API endpoint accessible from the public internet or from Vigilmon's monitoring network
  • A free Vigilmon account — no credit card required

Step 1: Expose Lightrun's health endpoint

Self-hosted Lightrun runs the management server as a Spring Boot application, which exposes Spring Actuator endpoints. The default port is 8080 for HTTP and 443 when deployed behind a reverse proxy with TLS termination.

Check whether the management server is reachable and inspect its health endpoint:

# Check if the Lightrun management server is responding
curl -v http://your-lightrun-host:8080/actuator/health

# For TLS-terminated deployments behind a reverse proxy
curl -v https://lightrun.yourdomain.com/actuator/health

# Expected healthy response
# {"status":"UP","components":{"db":{"status":"UP"},"diskSpace":{"status":"UP"}}}

# Check the API health endpoint (available on all Lightrun versions)
curl -s https://lightrun.yourdomain.com/api/v1/health | jq .

# Verify the agent WebSocket endpoint is accepting connections
curl -v --no-buffer -H "Upgrade: websocket" \
  -H "Connection: Upgrade" \
  https://lightrun.yourdomain.com/ws/agent

For self-hosted deployments, use the actuator health endpoint as your primary HTTP monitor target:

https://lightrun.yourdomain.com/actuator/health

If actuator endpoints are disabled in your configuration, the general API health check is a reliable fallback:

https://lightrun.yourdomain.com/api/v1/health

For SaaS / cloud-hosted Lightrun (app.lightrun.com), you cannot access internal actuator endpoints, but you can monitor the console's availability and the agent registration endpoint:

# Check the SaaS management console is reachable
curl -o /dev/null -s -w "%{http_code}\n" https://app.lightrun.com/

# Check the agent API endpoint (returns 401 without credentials, but confirms the server is up)
curl -o /dev/null -s -w "%{http_code}\n" https://app.lightrun.com/api/v1/health

A 200 or 401 response both confirm the server is up; a connection timeout or 5xx response indicates a problem.

Step 2: Set up HTTP monitoring in Vigilmon

  1. Log in to vigilmon.online and navigate to Monitors in the left sidebar.
  2. Click New Monitor and select HTTP(S) as the monitor type.
  3. In the URL field, enter your Lightrun health endpoint — for example, https://lightrun.yourdomain.com/actuator/health.
  4. Set Check interval to 60 seconds and Timeout to 10 seconds.
  5. Under Expected status code, enter 200. Click Save to activate the monitor.

Add a monitor for Lightrun's agent connectivity endpoint

Agents register and maintain state through the /api/v1/agent namespace. Monitoring this separately catches failures in the agent registration path that do not affect the main health endpoint:

  1. Click New Monitor and select HTTP(S).
  2. Enter https://lightrun.yourdomain.com/api/v1/health (or https://app.lightrun.com/api/v1/health for SaaS).
  3. Set the Expected status codes to 200, 401 — a 401 confirms the endpoint is alive even without valid credentials.
  4. Set Check interval to 60 seconds and enable SSL certificate monitoring to catch certificate expiry before agents start rejecting the TLS handshake.
  5. Click Save.

Why external monitoring catches what Kubernetes misses

Kubernetes liveness and readiness probes run inside the cluster network and check whether the container process is alive. They do not verify that the management server's database connection is healthy, that the WebSocket upgrade path is working, or that the TLS certificate presented to external agents is valid. Vigilmon's checks originate from outside your infrastructure and follow the same network path your Lightrun agents and developers use, meaning they catch TLS errors, reverse proxy misconfigurations, and network policy changes that internal probes miss entirely.

Step 3: Monitor Lightrun's TCP port

A TCP monitor confirms that the management server's listening port is accepting connections, independently of the application layer. This catches cases where the process crashes but the port remains briefly bound by the OS, or where a firewall rule change silently blocks agent traffic.

  1. In Vigilmon, click New Monitor and select TCP as the monitor type.
  2. In Host, enter your Lightrun server hostname or IP address.
  3. In Port, enter 443 for TLS-terminated deployments, or 8080 for plain HTTP self-hosted deployments.
  4. Set Check interval to 60 seconds and Timeout to 5 seconds.
  5. Click Save.

For self-hosted deployments that expose both ports, add a second TCP monitor on port 8080 to catch cases where the application port is up but the reverse proxy routing has failed.

Step 4: Configure alert channels

Email alerts

  1. In Vigilmon, go to Alert Channels and click New Channel.
  2. Select Email and enter the address of your on-call operations team or your team distribution list.
  3. Assign this channel to all three Lightrun monitors created in Steps 2 and 3.
  4. Set Alert after to 2 consecutive failures to avoid noise from transient network blips.

Webhook alerts

For integration with Slack, PagerDuty, or your internal incident management system:

  1. In Alert Channels, click New Channel and select Webhook.
  2. Paste your Slack incoming webhook URL or PagerDuty Events API endpoint.
  3. Vigilmon will POST a JSON payload on each state change. A typical alert payload looks like this:
{
  "monitor_id": "lightrun-health-http",
  "monitor_name": "Lightrun Management Server — Health",
  "status": "DOWN",
  "previous_status": "UP",
  "checked_at": "2026-07-11T09:23:41Z",
  "reason": "Connection timed out after 10000ms",
  "url": "https://lightrun.yourdomain.com/actuator/health",
  "response_time_ms": null,
  "region": "eu-west"
}

Runbook: diagnostic commands when an alert fires

Run these commands in sequence when Vigilmon reports the Lightrun management server as down:

# 1. Check whether the management server process is running
systemctl status lightrun-server
# or for Docker deployments:
docker ps --filter name=lightrun --format "table {{.Names}}\t{{.Status}}"

# 2. Inspect the management server logs for startup errors or DB failures
journalctl -u lightrun-server --since "10 minutes ago" --no-pager
# or:
docker logs lightrun-server --since 10m

# 3. Verify database connectivity from the server host
psql -h localhost -U lightrun -d lightrun -c "SELECT 1;" 2>&1
# or for MySQL:
mysql -u lightrun -p lightrun -e "SELECT 1;"

# 4. Check how many agents are currently connected (requires running server)
curl -s -H "Authorization: Bearer $LIGHTRUN_API_KEY" \
  https://lightrun.yourdomain.com/api/v1/agents | jq 'length'

# 5. Test the WebSocket upgrade path directly
curl -v --no-buffer \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  -H "Sec-WebSocket-Version: 13" \
  https://lightrun.yourdomain.com/ws/agent

# 6. Verify TLS certificate validity and expiry
echo | openssl s_client -connect lightrun.yourdomain.com:443 2>/dev/null \
  | openssl x509 -noout -dates

# 7. Check disk space — snapshot storage can fill the volume
df -h /var/lib/lightrun

Step 5: Create a public status page

  1. In Vigilmon, navigate to Status Pages and click New Status Page.
  2. Give the page a name such as "Lightrun Debugging Infrastructure" and set the URL slug to something memorable like lightrun-status.
  3. Add all three Lightrun monitors to the page: the health endpoint HTTP monitor, the agent API HTTP monitor, and the TCP port monitor.
  4. Toggle Show response time graph on to give developers visibility into latency trends, which can indicate an overloaded management server before it becomes fully unavailable.
  5. Click Publish. Share the status page URL with your development team so they can check server status themselves before filing incident tickets.

Putting it all together

| Monitor | Type | What it catches | |---|---|---| | Lightrun health endpoint (/actuator/health) | HTTP | Management server crash, database connection failure, Spring Boot startup errors | | Lightrun agent API (/api/v1/health) | HTTP | Agent registration path failures, licensing service errors, reverse proxy misrouting | | Lightrun server TCP port 443 | TCP | Port-level connectivity loss, firewall rule changes, TLS termination failures | | Lightrun server TCP port 8080 | TCP | Direct application port availability, reverse proxy bypass validation |

# Quick triage sequence — run top to bottom when an alert fires

# Is the process alive?
systemctl is-active lightrun-server || docker inspect -f '{{.State.Status}}' lightrun-server

# Can the database be reached?
pg_isready -h localhost -p 5432 -U lightrun

# How many agents were connected before the outage?
grep "Agent connected" /var/log/lightrun/server.log | tail -20

# Are agents currently in reconnection loop? (check agent-side logs on any app host)
grep -i "reconnect\|websocket\|lost connection" /var/log/myapp/lightrun-agent.log | tail -30

# Is the licensing endpoint responding?
curl -s -o /dev/null -w "%{http_code}" https://lightrun.yourdomain.com/api/v1/license/status

What's next

  • Add response time alerting — configure a Vigilmon threshold alert to notify you when the Lightrun health endpoint response time exceeds 2 seconds, which typically indicates database query slowness or JVM garbage collection pressure before the server becomes fully unresponsive.
  • Monitor the underlying infrastructure — add Vigilmon TCP monitors for the database port (5432 for PostgreSQL, 3306 for MySQL) and any external licensing endpoints so you can distinguish a Lightrun server failure from a dependency failure at a glance.
  • Set up multi-region checks — if your development teams are globally distributed and Lightrun agents run in multiple cloud regions, enable Vigilmon's multi-region monitoring so a regional network partition is reported separately from a full management server outage.

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles