What to monitor

Stoa is a self-hosted system, which means monitoring is your job, not a managed service. The good news: there's a small, well-defined set of signals that matter. Watch these and you'll catch most problems before users notice them.

Start with System status

Before you build any external dashboards, learn the in-product System status page. It covers host CPU, memory, disk, the live health of every internal service, how many model calls the deployment has made, and a separate panel for the attachment and web page cache, with a one-click way to clear it. For day-to-day checks, this is the first place to look. External monitoring is for what System status can't do: alerting, history, and correlation with the rest of your infrastructure.

Host metrics

These are the resources Stoa lives on. Forward them into whatever monitoring stack you already run (Prometheus and Grafana, Datadog, Zabbix, or similar).

• CPU usage. Sustained load above 85% means you're at the edge of your tier.
• System memory. Above 90% and the host starts swapping, which kills latency.
• GPU utilization as a load signal, plus GPU memory as the failure signal. Above 95% memory and you're one big request away from an out-of-memory error under load.
• Disk usage on the volume holding documents and indexes. Above 80% means start planning, above 90% means ingestion will start to fail.
• Network throughput between services and to clients. Useful when chats feel slow but the host looks idle.

Service health

System status reports the health of four internal services, each with a status badge and a latency reading:

• The document store, which holds knowledge bases, conversations, users, and settings.

• The cache, which speeds up repeated work and backs background jobs like ingestion and research.

• The document conversion service, which turns uploaded Office documents into text a knowledge base can index.

• The language model service, the AI model that answers chats and produces the embeddings knowledge base search relies on.

• Healthy means the service answers a probe quickly and without errors.

• Degraded means it's responding but slowly, or returning intermittent errors. Chats and queries still work but some requests take longer than they should.

• Down means the probe is failing entirely. That service is offline. The user-visible impact depends on which one (see System status for the breakdown).

A reasonable rule: if any service is degraded for more than 5 minutes, treat it as a real signal and investigate. Brief flickers during heavy use are normal.

There's no separate screen for background job queue depth today (ingestion and research both run as background jobs). An API endpoint reports it, waiting jobs, in-flight jobs, and how long the oldest has been held, so you can pull it into your own monitoring stack if you want to alert on it; see Integration patterns below.

Application signals

Beyond host and service health, watch these application-level signals:

• Queue depth on background jobs (ingestion, research). A queue that grows without draining means worker capacity isn't keeping up.
• Slow chats. Median response latency is the most direct user-facing signal. A jump usually points at the language model service or the GPU.
• Language model service latency, to distinguish "the model is slow" from "the network is slow." System status shows this reading live; trending it over time is what your own dashboard adds.
• KB ingestion backlog. Documents stuck in "processing" mean either the language model service (which produces embeddings) or the document conversion service (which reads Office documents) is behind.

Disk growth patterns

Three things on disk grow over time. Plan capacity around all three.

• KB indexes grow with the number of documents and the chunk size. Roughly 1.5 to 2x the size of the source documents.
• Audit log grows with usage. Heavy admin teams produce more entries than light ones. Check the configured retention, see Audit logging.
• Conversation history grows with the number of users and the length of their chats. Less per-user than the audit log, but it adds up.

Audit log as a security signal

The audit log is not just a compliance artifact, it's a real-time security feed. Watch for failed sign-ins from a single IP, role changes outside business hours, bulk document deletions, and configuration changes nobody on your team remembers making. See Audit logging for what gets recorded.

What to alert on vs what to dashboard

A practical split:

Alert (page someone)

• Any service down for more than 5 minutes.
• Host CPU sustained above 85% for more than 10 minutes.
• Host memory above 90%.
• Disk above 80% (warn) and 90% (critical).
• GPU memory above 95%.
• Failed sign-in spikes (a sudden burst from one source).

Dashboard (look at on your morning round)

• Latency trends per service.
• Queue depth and ingestion backlog.
• Daily active users and chat volume.
• Disk growth rate per data set.
• Top errors in the audit log over the last 24 hours.

Integration patterns

Most ops teams already run a monitoring stack. Stoa fits into it the way any other Linux service does: scrape host metrics with your existing agent, point health checks at the host, and forward the audit log to your SIEM if you have one. Your delivery engineer can help wire up the specifics for your environment, including for air-gapped sites where the monitoring host lives on the same isolated network.

Next

• Troubleshooting for what to do when an alert fires.
• Performance tuning for the levers that move the slow signals.
• Disaster recovery for the worst case.