Introspection

As an application grows, its structure becomes hard to hold in mind. Which components exist? Which events connect them? Which of them actually call each other? The answers are spread over manifests owned by different people, and some are not written anywhere.

Introspection collects those answers into one view: the topology of the application, as a graph of components and the interactions between them.

§Declared and observed

The topology has two sources.

What is declared. Manifests state each component’s entity, operations, events, and receivers. From receivers, the event relations between components are known exactly: billing receives orders.approved.

What is observed. Calls are made from code, through the context, and no manifest lists them. The runtime sees every call it carries, so it records which components and services called which.

Together they show the structure the application was designed with and the paths it actually exercises. A dependency nobody intended becomes visible, as does a declared relation that never fires.

§What is and is not collected

An observed call is recorded as the pair it connects and nothing more. What a call carried — its input, its reply, the data of users — is not collected. The topology describes the shape of the application, not its contents.

A component can be excluded from the topology by saying so in its manifest.

§Uses

Understanding. The topology is published as a browsable graph and through an interface that can be queried. A newcomer can see the system, and an experienced developer can confirm an assumption.

Finding cycles before they close. Call chains refuse a circle when it runs. The topology shows the event subscriptions that could form one.

Deciding on boundaries. Components that call each other constantly are candidates for sharing a composition. The observed graph is evidence for that decision.

Knowing that nothing is running. Because the topology records whether anything was called, it can answer whether a deployment is idle. Halt relies on this to stop a deployment only at a moment when nothing is in progress.

§Why the platform can do this

In most systems a topology diagram is drawn by hand and is out of date soon after. It can be generated here because the facts it needs are already in the platform’s hands. Structure is declared, and interaction passes through the runtime. Nothing has to be added to business code for the application to describe itself.