App observability

Availability

The observability API is partially implemented. Two data sources are useful today:

an append-only, manually populated event timeline; and
current VM resource allocation reported by libvirt.

The following are contract previews only:

request analytics returns an empty rollup list because access-log ingestion is not running;
uptime-probe configuration persists, but no scheduler performs the HTTP checks;
resource samples are empty because the sampler is not running; and
app log streaming is not implemented.

There is no completed observability dashboard. A stored probe configuration is not proof that an endpoint was checked.

Current REST surface

The routes sit below /api/app-gateway.

Method	Path	What it proves today
`GET`	`/analytics/{slug}?days=7`	The contract is reachable; `rollups` is expected to be empty.
`PUT`	`/probes/{slug}`	The probe configuration was validated and stored.
`GET`	`/probes/{slug}`	The stored configuration can be read. Runtime status remains unset.
`DELETE`	`/probes/{slug}`	The stored configuration was removed.
`POST`	`/events/{slug}`	A caller-supplied event was appended.
`GET`	`/events/{slug}?limit=100`	Stored events can be read newest-first.
`GET`	`/metrics/{slug}?vm_name={name}`	Current allocation may be returned; `samples` is empty.

Probe configuration


PUT /api/app-gateway/probes/my-app
Content-Type: application/json
 
{
  "path": "/healthz",
  "interval_s": 60,
  "expected_status": 200,
  "timeout_s": 5,
  "enabled": true
}

A read currently looks like this:


{
  "config": {
    "path": "/healthz",
    "interval_s": 60,
    "expected_status": 200,
    "timeout_s": 5,
    "enabled": true
  },
  "last_run_at": null,
  "last_status": null,
  "last_http_status": null,
  "consecutive_failures": 0
}

The null runtime fields are the important signal: no check has run. Use an external monitor for availability alerting until the scheduler ships.

Events

Events are durable records written through the API, not an automatically complete audit trail. Deployment, checkpoint, domain, and walker hooks are still pending, so callers must not assume those activities will appear without an explicit append.

Treat event metadata as caller-supplied data. Do not place secrets in it.

Resource allocation

The metrics route can report assigned vCPUs, memory, and disks when a matching VM is available from libvirt. It does not yet report a time series or application-level health. Allocation is capacity configuration, not evidence that the application used or survived that capacity.

Operational guidance

Until ingestion and worker loops are deployed:

use an external HTTP monitor for uptime;
collect application logs with an operator-managed mechanism;
use libvirt or host telemetry for actual utilization; and
attach timestamps and source evidence to incident records rather than relying on the preview event list alone.

The feature can be presented as ready only after restart-safe ingest, probe, sampling, and log-stream workers have passed end-to-end failure and recovery tests.