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 peerOpen that device's latency sheet in the console or the app. Replies coming back confirm 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.

Measuring a link's latency and loss

The console and the app show the latency of a link between two devices. This is not a system ping: VIGIL never uses ICMP, neither to measure nor to discover. An application-level probe travels inside the encrypted session itself, exactly where your traffic goes — so what is measured is the real path, not a parallel channel that firewalls treat differently.

A probe inside the session

A small echo message leaves once per second toward the target device, which sends it straight back. It rides the end-to-end encrypted session, direct or relayed.

Round trip timed locally

The time is measured on the probing machine, between sending and return. No timestamp from the peer enters the calculation: a device cannot flatter its own latency.

Loss actually counted

The echo travels with no delivery guarantee. A probe left unanswered after two seconds counts as lost — the figure shown is a real loss rate, not a number stuck at zero.

The latency sheet is identical on every client: time on the horizontal axis (a 60-second window, with the present moment at the right edge), latency in milliseconds on the vertical axis, and four figures — minimum, average, maximum and loss — computed over that same window. A lost probe shows up as a red band on the graph: the curve breaks, it never dips to zero.

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”.