> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stellartrail.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring & Health

> How StellarTrail exposes operational health, background queue status, and observability tooling.

# Monitoring & Health

StellarTrail provides a suite of health endpoints and integrates with several observability tools to ensure reliable operation across all services.

## Health Endpoints

All health endpoints are served under `/api/health`. Public endpoints require no authentication. Admin endpoints require the `x-admin-secret` header.

| Endpoint                     | Auth  | Purpose                                                               |
| ---------------------------- | ----- | --------------------------------------------------------------------- |
| `/api/health`                | No    | Basic status check with overall degradation signal                    |
| `/api/health/live`           | No    | Kubernetes-style liveness probe                                       |
| `/api/health/ready`          | No    | Readiness probe with dependency checks                                |
| `/api/health/detailed`       | Admin | Full dependency details including memory, uptime, and provider status |
| `/api/health/queues`         | No    | Queue summary with aggregate job counts                               |
| `/api/health/queues/details` | Admin | Per-queue job statistics                                              |
| `/api/health/coach`          | No    | AI Coach service availability                                         |
| `/api/health/charting`       | No    | Market data provider availability                                     |

Each endpoint returns a `status` field (typically `ok` or `degraded`). The `/ready` endpoint returns `503` when the server cannot accept traffic; all other public endpoints return `200` unless a service is fully unavailable.

## Background Queues

StellarTrail uses BullMQ backed by Redis for asynchronous job processing. Nine queues handle distinct workloads:

| Queue                  | Purpose                              | Concurrency |
| ---------------------- | ------------------------------------ | ----------- |
| `usage`                | Persist usage records                | 5           |
| `trade-index`          | Vector indexing of trades            | 3           |
| `email`                | Transactional email delivery         | 5           |
| `cleanup`              | Maintenance and data cleanup         | 1           |
| `brokerage-sync`       | Plaid brokerage synchronization      | 2           |
| `reports`              | Performance report generation        | 3           |
| `notifications`        | User notification dispatch           | 5           |
| `market-snapshot`      | Daily market summary snapshots       | 1           |
| `ai-signal-generation` | AI-powered trading signal generation | 1           |

Queue health is classified as **degraded** when any single queue exceeds 10 failed or 50 waiting jobs, and **unhealthy** when a queue exceeds 100 failed or 500 waiting jobs.

## Monitoring Tools

StellarTrail integrates the following tools for production observability:

* **Sentry** -- Error tracking and performance monitoring. Captures unhandled exceptions across both the server and client with full stack traces and request context.
* **PostHog** -- Product analytics and feature flag management. Tracks user engagement, feature adoption, and conversion funnels.
* **Pino** -- Structured JSON logging on the server. Provides request-level tracing with correlation IDs for debugging production issues.
* **LangSmith** -- LLM observability and tracing. Records AI Coach prompt chains, token usage, and latency for each conversation turn.
* **BullBoard** -- Admin dashboard for inspecting queue state. Provides a visual interface for monitoring job progress, retrying failed jobs, and draining queues.

## Status Page

StellarTrail maintains a public status page in a separate repository within the organization. Check the status page for real-time service availability and incident history.