Metrics reference

AIP exposes process health, work capacity, fleet state, and bounded activity counters through three different metric surfaces. This reference is for operators who need to select the correct endpoint, recognize every current product-neutral family, and interpret an absent or reset series safely.

This inventory describes source revision 97be86e9efedf07ecf1783b03800f683f107fb04. It covers aipd, the shared host used by Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty, and the connector lifecycle control plane. It does not invent provider-specific business metrics.

Surface selector

The three paths have the same name but not the same representation. Do not configure a Prometheus text parser against the control-plane JSON endpoint.

Stable names versus current emission

The observability crate declares 11 stable metric names for AIP implementations. A declaration fixes a shared name and meaning; it does not register or emit a series.

Only the two rows marked Yes are emitted by the pinned product-neutral processes. Do not create alerts or dashboards for the other nine until an implementation registers them. No product-neutral histogram is emitted at this revision.

aipd Prometheus families

Readiness and native traffic

aip_actions_total is not a success counter. Pair it with durable action state and error evidence when calculating outcomes.

Fleet maintenance and registry pools

The six pool gauges describe the registry owned by aipd; they do not describe the separate lifecycle control-plane process.

Remote admission and event ingress

The remote admission gauges are refreshed immediately before aipd renders a metrics scrape, but only when the scheduler is configured.

Event-ingress capacity gauges are also refreshed at scrape time when central connector event ingress is configured.

Both ingress URL paths use the same counters. The metrics do not separate connector events from stream callbacks and do not carry connector, replica, or tenant labels.

Runtime work budgets and retention

The capacity gauges express concurrency permits, not queue depth. A value of zero available with nonzero capacity means the corresponding work class is saturated at that sample.

Connector-host Prometheus families

Every one of the six standalone connector hosts renders all eight families on each scrape. The endpoint uses local atomics and has no metric labels.

requests_total - rejected_total is not a supported success calculation. Response-signing and process failures can occur outside a counter update, and accepted action state is owned by the durable lifecycle rather than this arithmetic.

Control-plane JSON snapshot

The connector lifecycle control plane returns a ConnectorRegistryPoolSnapshot as JSON:

{
  "control_size": 1,
  "control_idle": 1,
  "control_max": 4,
  "data_size": 1,
  "data_idle": 1,
  "data_max": 4
}

These values are a point-in-time JSON diagnostic. A Prometheus collector must transform them explicitly or use a separate JSON exporter; they are not native Prometheus series.

Labels and cardinality

The current product-neutral Prometheus emitters use one metric label: message_type on aip_envelopes_received_total. Its value comes from the bounded AIP message-type enum. Every other current daemon and host family is unlabeled.

Stable tracing fields such as action ID, message ID, session ID, correlation ID, delegation ID, connector ID, and error code are not metric labels. Keep those values in traces and structured logs. Do not add tenant, action, resource, provider request, free-form message, or replica identifiers as Prometheus labels.

Use target metadata outside the application to distinguish processes, regions, connector types, and immutable deployment artifacts. Keep the target-label set bounded and controlled by the monitoring system.

Series activation and reset behavior

Prometheus recorder families are registered lazily when code updates them. Consequently:

• aip_daemon_ready and aip_gateway_ready may be absent until readiness has been evaluated;
• remote admission and ingress gauges are absent when their optional subsystem is not configured;
• fleet and pool gauges are absent until a successful maintenance cycle, and pool gauges also require a pool snapshot;
• traffic, failure, and retention counters may be absent until their first update;
• the nine stable names with no emitter remain absent for the entire process.

Absence is not zero. Monitor the scrape target and the corresponding health or configuration boundary separately. All counters and gauges are process-local; they reset when the process restarts. Use rate or increase semantics for counters and tolerate a reset.

Operational interpretation

Deployment-owned service objectives determine alert thresholds and windows. This source defines signals and semantics, not universal thresholds.

Endpoint security

At this revision, each metrics path is mounted outside the process’s native application-auth middleware. Keep it on a private operations network or place it behind authenticated, authorized, and encrypted monitoring ingress.

The current families deliberately avoid tenant and resource identifiers, but they still reveal capacity, readiness, connection-pool, traffic, and failure information. Do not expose them as public diagnostics.

Related operations

• Observe and recover
• Operator runbooks
• Errors and retry decisions
• Native HTTP API
• Connector fleet HTTP API