# How to Monitor TREK Performance Using the Health Endpoint API

> Easily monitor TREK performance with the health endpoint API. Integrate with Prometheus, Grafana, or uptime tools for seamless runtime metadata insights. Learn more now.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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:

```yaml
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`](https://github.com/mauriceboe/TREK/blob/main/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

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

```

Expected output:

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

```

### Node.js CI Pipeline Probe

```javascript
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

```typescript
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`](https://github.com/mauriceboe/TREK/blob/main/mfaPolicy.ts)) and global authentication middleware ([`globalMiddleware.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/health/health.controller.ts) and the legacy Express route in [`server/src/nest/platform/platform.routes.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/middleware/mfaPolicy.ts) and [`server/src/middleware/globalMiddleware.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.