Monitoring Service
The service that runs your checks, and the modes you can run it in.
What it does
The monitoring service is the part of Miru that actually checks your services. It splits into two halves:
- Core talks to the database. It hands out the list of monitors to run, records the pings that come back, and opens or resolves Auto Incidents.
- Agent does the checking. It asks core what to run, sends the requests on schedule, and pushes the results back.
Agents never touch the database. Everything they need arrives over the core API, which is what lets you run one somewhere core cannot reach.
Modes
Set MIRU_ROLE to pick which halves a process runs.
| Mode | Runs | Needs a database | Use it for |
|---|---|---|---|
all | Core and agent | Yes | The default. One machine, one container, no extras. |
core | Core only | Yes | The hub when your agents live elsewhere. |
agent | Agent only | No | A probe in another region. |
If you do not set MIRU_ROLE, you get all. Core and agent run in the same process and talk to each other over loopback, so a normal install needs none of this.
Why the split exists
Checking a service from one place tells you whether that one place can reach it. Running agents in more than one region lets you tell "the service is down" apart from "the route from Frankfurt is down". Every ping records the region that produced it.
Splitting also keeps your database credentials in one place. A machine running agent only needs a URL and a shared token.
Configuration
| Variable | Modes | Default | What it does |
|---|---|---|---|
MIRU_ROLE | all | all | Which halves this process runs. |
AGENT_TOKEN | all | Random per process | Shared secret the agent presents to core. Required for core and agent. |
CORE_URL | agent | http://127.0.0.1:8080 | Where the agent reaches core. |
REGION | agent, all | local | Name recorded on every ping this agent produces. |
DATABASE_URL | all, core | none | Required by core. An agent process ignores it. |
PORT | all | 8080 | Port the service listens on. |
About AGENT_TOKEN
Core will not serve its agent endpoints without it, because those endpoints hand out request configurations that can contain credentials.
Leave it unset on a single machine and each process generates a random token at startup. Core and the agent inside it share that token, and nothing else can reach the endpoints.
The moment you split the roles across machines, set it explicitly and set it to the same value on both sides. Generate one with:
openssl rand -base64 32Running an agent in another region
Deploy a second container with MIRU_ROLE=agent, point it at your core, and give it the same token.
services:
monitor-agent:
container_name: monitor-agent
image: git.nordstud.io/nord-studio/miru/monitor:latest
volumes:
- ./config.toml/:/config.toml
environment:
- MIRU_ROLE=agent
- CORE_URL=https://monitor.example.com
- AGENT_TOKEN=${AGENT_TOKEN}
- REGION=eu-westCore has to be reachable from wherever the agent runs, and the connection between them should be over TLS or a private network, since it carries your monitors' credentials.
Running agents in more than one region is supported by the service, but the admin panel does not yet break uptime or latency down per region. Pings record which agent produced them, so the data is there waiting.
How an agent stays in step
Agents pull rather than being pushed to, which keeps the failure modes dull:
- An agent asks core for its monitor list on an interval and starts, stops or restarts checks to match. Creating or editing a monitor takes effect on its own, with nothing to restart.
- If core is unreachable, the agent keeps running the monitors it already knows about and buffers the results until it can deliver them. Losing core is when monitoring matters most, so an agent never stops on its own.
- Monitors on the same interval are spread across it rather than all firing on the same second.
The agent token
AGENT_TOKEN is the only thing standing between a stranger and the endpoints that run
requests with your stored credentials, so set it.
- With it set,
/agent/monitors,/agent/results,/testand/pingall require it. The web app reads the same variable and sends it, so set it on both. - With it unset, a random token is generated at startup. That still shuts the
/agentendpoints to everyone, but/testand/pingstay open, because a token that only exists inside one process is one the web app could never present. The service warns about this at startup. - Running
coreoragentrefuses to start without it. Those halves talk over the network, and a random token would mean an agent that fails every sync and quietly monitors nothing.
Whatever you do with the token, the monitoring service is an internal service. Do not publish its port. The web app reaches it over the internal network.
What's next?
Read the Monitors concept to learn what an individual check looks like, or the Configuration page for the settings that live in config.toml rather than the environment.