How to Monitor TREK Performance Using the Health Endpoint API

TREK exposes a lightweight health endpoint at GET /api/health that returns runtime metadata and can be integrated with Prometheus, Grafana, or uptime monitoring tools without requiring authentication.

The open-source mauriceboe/TREK repository provides a robust mechanism to monitor TREK performance through a standardized health check API. This endpoint delivers real-time operational status, version information, and environment details while bypassing all authentication layers to ensure external monitoring systems can continuously assess availability.

Health Endpoint Architecture

TREK implements its monitoring capability across multiple architectural layers to guarantee high availability and backward compatibility with legacy deployments.

NestJS Health Controller

The primary implementation resides in server/src/nest/health/health.controller.ts, where the HealthController registers the route under the NestJS application router. The controller merges a static ok: true flag with dynamic metadata supplied by the HealthService, including the application version, environment name, and server start time.

Express Fallback Route

For compatibility with existing Express middleware stacks, server/src/nest/platform/platform.routes.ts (lines 105–115) provides a legacy route that also serves GET /api/health. This route proxies to the same underlying logic, ensuring the endpoint remains accessible regardless of whether the request hits the modern NestJS controller or the legacy Express pipeline.

Authentication and Middleware Exemptions

To guarantee that monitoring probes are never blocked by security policies, the health path is explicitly exempted from authentication and rate limiting. In server/src/middleware/mfaPolicy.ts (lines 8–9), the MFA policy returns true early when the request method is GET and the path equals /api/health. Similarly, server/src/middleware/globalMiddleware.ts (lines 144–147) skips all global middleware—including authentication—when req.path === '/api/health', allowing unconditional access for health checks.

Response Contract and Performance Characteristics

The health endpoint is optimized for high-frequency polling with negligible resource consumption.

• No Database Queries: The HealthService serves in-memory metadata without touching persistent storage, ensuring sub-millisecond response times suitable for aggressive scraping intervals.
• Stable JSON Schema: The response always contains ok: boolean plus extended fields such as version, env, and startedAt. New keys are added only as optional expansions, maintaining backward compatibility with existing monitors.
• HTTPS-Aware Exemptions: As verified in server/tests/integration/misc.test.ts (test case MISC-008), the endpoint is excluded from FORCE_HTTPS redirects, enabling plain HTTP probes when TLS termination occurs at a reverse proxy.

Monitoring Stack Integration

Prometheus Scraping

Configure Prometheus to scrape http://<trek-host>:3000/api/health every 15 seconds. Because the endpoint returns JSON, use a JSON exporter sidecar to parse specific fields:

scrape_configs:
  - job_name: 'trek'
    metrics_path: '/api/health'
    static_configs:
      - targets: ['trek.example.com:3000']
    scheme: http

Grafana and Uptime Monitoring

Import dashboards that visualize the ok status field, or configure HTTP(S) checks in UptimeRobot, healthchecks.io, or Pingdom against /api/health. The predictable JSON structure allows these tools to parse the version or environment for tagging alerts.

Client-Side Health Verification

The frontend wrapper in client/src/api/client.ts (lines 758–760) exposes healthApi.features(), which queries the health endpoint to toggle UI capabilities based on server-reported status. This allows the React client to gracefully degrade features when the backend reports degraded health.

Implementation Examples

Simple curl Health Check

curl -s http://localhost:3000/api/health | jq .

Expected output:

{
  "ok": true,
  "version": "2.5.1",
  "env": "production",
  "startedAt": "2026-07-10T08:12:34.567Z"
}

Node.js CI Pipeline Probe

import fetch from 'node-fetch';

async function probe() {
  const res = await fetch('http://localhost:3000/api/health');
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  if (!data.ok) throw new Error('Health flag not true');
  console.log('TREK is healthy – version', data.version);
}

probe().catch(err => {
  console.error('Health check failed:', err);
  process.exit(1);
});

Frontend Feature Flag Check

import { healthApi } from '../../api/client';

healthApi.features()
  .then(f => console.log('Available features:', f))
  .catch(() => console.warn('Health probe failed'));

Summary

• TREK provides a unified health endpoint at /api/health implemented in both the NestJS HealthController and the legacy Express stack.
• The endpoint is explicitly exempt from MFA policies (mfaPolicy.ts) and global authentication middleware (globalMiddleware.ts) to ensure reliable external access.
• It returns a high-performance JSON payload containing ok: true and runtime metadata without database queries, making it safe for 15-second Prometheus scraping intervals.
• Integration patterns include Prometheus metrics extraction, Node.js CI probes, and the client-side healthApi.features() wrapper for UI capability detection.

Frequently Asked Questions

What URL should I use to monitor TREK performance?

Send a GET request to /api/health on your TREK host (e.g., http://localhost:3000/api/health). This path is served by both the NestJS controller in server/src/nest/health/health.controller.ts and the legacy Express route in server/src/nest/platform/platform.routes.ts, ensuring consistent availability across different deployment configurations.

Does the health endpoint require authentication?

No. According to the source code in server/src/middleware/mfaPolicy.ts and server/src/middleware/globalMiddleware.ts, the health path is explicitly bypassed. The MFA policy returns true early for GET requests to /api/health, and the global middleware skips authentication checks when req.path === '/api/health', allowing unauthenticated probes from monitoring systems.

What data does the TREK health endpoint return?

The endpoint returns a JSON object containing a static ok: true flag combined with runtime metadata from the HealthService, including the application version, environment name, and server start time. As implemented in server/src/nest/health/health.controller.ts, the response excludes database-dependent fields to ensure high performance and stability for monitoring tools.

How can I integrate TREK health checks into my CI/CD pipeline?

Use a simple Node.js script that fetches http://localhost:3000/api/health and asserts that the response status is 200 and the ok field is true. The integration tests in server/tests/integration/misc.test.ts demonstrate this pattern, verifying that the endpoint is publicly accessible and returns the expected payload structure without requiring credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}