Documentation

Diagnostic tools

Diagnosing effectively means knowing which tool probes which layer. VIGIL-MESH offers four: the /healthz health endpoint to check that a service answers, the real-time topology in the console to see the network as the vigie sees it, logs and enrolment status to understand a device's state, and connectivity checks to validate a link end to end. This page describes each one and says when to use it.

The /healthz health endpoint

The simplest entry point to know whether a service answers is /healthz. A GET request on this endpoint returns the health state of the queried service: it is the first check to run when you do not yet know whether the problem comes from the service itself or from its connectivity.

A healthy response indicates the service is alive and answering requests. It is a “yes” to the question “is the service running?”, not proof that the whole network path works.
No response: the service is not running, not listening, or not reachable from where you are testing. Tell these cases apart by testing from another point.
Use /healthz as a first triage: if it answers, look for the problem higher up (access policy, path, subscription); if it does not answer, look on the service side or at basic reachability.

Real-time topology in the console

The console offers an overview that local tests do not give: the device inventory, their status and the network topology as the vigie sees it. It is the place to check at a glance that a device is present, active, and linked to its peers.

Inventory: each device is listed with its status (active, pending, suspended…), its mesh address and its name.
Topology: a device's links to its peers on the same network are shown, which helps spot an isolated node.
State indicators: they show whether a peer is online and since when.

Logs and enrolment status

When a device does not behave as expected, two sources tell you about its state: its local logs and its enrolment status. The enrolment status says whether the device is admitted and approved; the logs say what it is attempting and where it fails.

Source	What it tells you	When to consult it
Enrolment status	Is the device admitted, pending approval, suspended, revoked or expired?	When a node has no address or does not show as active.
Node local logs	What the node attempts, its errors, its relay/direct and tcp-only switchovers.	When the node is connected but misbehaving, or stays on the relay.
Console	Status as seen by the vigie, correlated with the inventory and the topology.	To cross-check the local view against the central view.

Verifying connectivity

Once the service is healthy and the device active, what remains is to validate the link end to end. The connectivity verification procedure chains a few simple checks — assigned address, peer reachability, name resolution, topology — each of which isolates a different layer.

1
Confirm the assigned addressDoes the device carry a 100.64.x address? Without an address, it did not complete its enrolment.
2
Reach a peerSend a ping to the address of another active device. A reply confirms the path is established, even via the relay.
3
Check name resolutionResolve a peer's name and reach it by name: if the address answers but the name does not, the problem is on the resolution side, not the connectivity side.
4
Observe the topologyCross-check with the console, allowing one refresh cycle (~30 s) to pass.

Frequently asked questions

Which tool should I start a diagnosis with?

With the broadest triage: GET /healthz to know whether the service answers, then the console to check that the device is active and linked. Only then move down to the logs and the connectivity checks.

A device does not appear in the console, is it necessarily a failure?

Not necessarily. The topology is refreshed roughly every 30 seconds: a device that has just connected or left can take that long to be reflected. Let one cycle pass before concluding.

What exactly does /healthz tell me?

Only that the queried service is alive and answering. It says nothing about the network path, multicast subscriptions or access policies — it is a starting point, not a full diagnosis.

The node is connected but misbehaving, where do I look?

In its local logs: they show what it is attempting, its relay/direct and tcp-only switchovers, and its errors. First check that the enrolment status is indeed “active”.