Monitoring¶
Look inside a running EPT API: the most recent log events it produced, and a live snapshot of process health. Use it to answer "what just happened?" — which validation ran, why a conversion failed, how many requests the API is serving — without SSH-ing into the container to read log files.
Endpoints¶
Authentication: Authorization: Bearer <access_token>.
Usage¶
curl "${EPT_API_URL}/v1/monitoring/logs?level=INFO&limit=100" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" | jq .
Python (httpx)¶
import os
import httpx
response = httpx.get(
f"{os.environ['EPT_API_URL']}/v1/monitoring/logs",
headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
params={"level": "INFO", "limit": 100},
timeout=30.0,
)
response.raise_for_status()
events = response.json()["events"]
Querying logs¶
All parameters are optional; combine them freely:
| Parameter | Default | Meaning |
|---|---|---|
level |
INFO |
Minimum log level: DEBUG, INFO, WARNING, ERROR, CRITICAL. |
logger |
— | Only loggers whose name starts with this prefix, e.g. ept.features.validate_stac. |
event |
— | Only events tagged with this name, e.g. http_request. |
since |
— | Only events at or after this time (ISO 8601). |
q |
— | Case-insensitive substring match across the message, logger name, event tag, and structured fields. |
limit |
100 |
Maximum events returned (1–100000), newest first. |
Examples:
# Everything the validate STAC feature logged today at INFO or above
curl "${EPT_API_URL}/v1/monitoring/logs?logger=ept.features.validate_stac&level=INFO" ...
# Free-text search — matches messages, logger names, event tags, and fields
curl "${EPT_API_URL}/v1/monitoring/logs?q=adapter" ...
# Only request-lifecycle logs
curl "${EPT_API_URL}/v1/monitoring/logs?event=http_request" ...
Response (logs)¶
{
"events": [
{
"ts": "2026-10-14T10:38:46.123456+00:00",
"level": "INFO",
"logger": "ept.features.validate_stac.adapter",
"event": null,
"message": "VALIDATE OK: https://.../catalog.json [catalog] id='root' depth=0 schema=0.0421s edito=0.0018s issues=0",
"fields": {"stac_url": "https://..."}
}
],
"matched": 42,
"returned": 42,
"buffer_size": 512,
"buffer_capacity": 200000,
"dropped": 0
}
events— newest first.fieldsholds the structured extras the emitting code attached; sensitive values (tokens, passwords) are redacted automatically.matched/returned— how many events pass the filters in total, and how many are on this page. Raiselimitor narrow the filters to see more.buffer_size/buffer_capacity/dropped— log-store health.dropped > 0means the oldest events were pruned because the retention capacity was reached.
Response (status)¶
{
"status": "ok",
"version": "1.0.0",
"python_version": "3.13.7",
"pid": 7,
"started_at": "2026-10-14T08:00:00.000000+00:00",
"uptime_seconds": 9531.4,
"log_level": "INFO",
"log_file": "logs/api.log",
"buffer": {"capacity": 200000, "size": 512, "dropped": 0},
"requests": {"active": 1, "total": 843, "server_errors": 2}
}
Good to know¶
- The log store is a local SQLite database written next to the API log (
<API_LOG dir>/monitoring.db, overridable viaMONITORING_DB_PATH): it survives restarts, is not shared between workers, and retains the most recent 200000 events (hardcoded inept/infrastructure/utils/monitoring.py).dropped > 0on the status endpoint means eviction pressure. If the store can't be created (read-only directory), monitoring falls back to in-memory and the API still starts. The complete unpruned history stays in the rotating log file (API_LOG,logs/api.logby default). - Searching with
qalso matches the logger name and event tag — soq=adapterfinds logs emitted byept.features.validate_stac.adapter, even when the message itself does not contain the word. - Requests to the monitoring endpoints themselves are not logged, so the UI polling them does not flood the buffer with its own traffic.
- Some detail is only logged at
DEBUG(e.g. per-object validation outcomes); the buffer capturesept.*DEBUG records regardless ofLOG_LEVEL, so query them withlevel=DEBUGwithout changing process logging. - A typical workflow: validate a catalog, then check
/v1/monitoring/logs?logger=ept.features.validate_stacto see the run's step-by-step log trail.