Skip to content

08. Observability diagnostics

Reference index

This category covers dispatch_options_t/dispatch_diagnostics_options_t, which configure the trace/metric/log recording level; framework_runtime_t, which reads host/topology status; and the framework_error_kind_t correspondence table used to judge failures across every category. The exact signatures are owned by the Monitoring exact interface and the Channel messaging exact interface (Korean-only).

configure_dispatch().diagnostics (configuration time)

Sets the trace/metric recording level and sampling.

options.configure_dispatch()
  .message_flow(zlink::framework::message_flow_log_mode_t::normal)
  .trace_sample_rate(0.1)
  .include_message_sizes(true);

Options. This call carries the following modifiers.

Modifier Default Meaning
.message_flow(message_flow_log_mode_t) errors The detail level to record: one of off/errors/normal/detailed
.trace_sample_rate(double) Implementation default 0.0..1.0. NaN or out of range is a configuration error
.include_message_sizes(bool) false Whether to include the payload size distribution in telemetry. The payload content itself is never recorded

Each modifier is a synchronous fluent call returning dispatch_options_t — not a registration with no return value.

Completion result. The Framework writes structured records to the standard logger, trace, and metric providers configured by the application. A provider failure is isolated as separate diagnostics and does not change the original message operation's terminal result. Dispatch options expose no file path, callback observer, runtime error sink, or raw event DTO. send and publish have no reply path, so reply_error cannot be used in the unhandled policy.

When to use. Use this to set the default recording level at startup. To change only the level while running, use app_t::set_message_flow_mode in the host-lifecycle category.

framework_runtime_t::status / observe (read/observe)

Queries or observes the host-wide status (lifecycle state, relocation/termination results, Core HWM accounting, and Application Job Queue backpressure).

zlink::framework::framework_runtime_status_t status = framework_runtime.status();
bool can_accept_new_operations = status.is_ready && status.accepting_work;

auto observation = framework_runtime.observe(
  /*capacity=*/64,
  [](const auto &observed) {
      // check observed.status.capacity.application_job_queue and observed.status.state
  });

Options. This entry point has no modifiers.

Completion result. status() is a synchronous call that returns a value immediately. observe(...) delivers observed_status_t<framework_runtime_status_t> to the callback, and the loss field tells you whether observations were lost. framework_runtime_status_t::capacity (host_capacity_status_t) contains the independent core_hwm_status_t and application_job_queue_status_t snapshots. Correlate accounted bytes with permits_in_use, capacity_waiters, wait count, and wait duration rather than treating them as one queue limit.

When to use. Use this to diagnose the host's overall lifecycle state or capacity backpressure. Use the status-query entry in the topology-discovery category for a specific MeshName/ChannelName's availability.

framework_error_kind_t correspondence table

When a Framework operation fails, framework_exception_t::kind() tells you the cause family. This table is the shared basis for the completion-kind descriptions in every category.

Kind What the application should check
not_found Whether the requested Actor, Spot, handler, route, or target exists
already_exists Whether create and registration must be handled idempotently
type_mismatch Whether the stable type matches the requested application type
not_configured Whether the required role, handler, Store, or object client was registered at startup
rejected Framework admission, a filter, or a runtime policy without a typed result rejected the operation
unavailable Whether the target, route, Store, or worker can currently handle the operation
capacity_exceeded Whether placement, queue, or a bounded resource has no room left
deadline_exceeded The operation did not complete within the deadline. Whether the result had side effects follows that operation's contract
shutting_down The runtime is not accepting new admission. Use a different serving instance
protocol_error Whether the protocol or reply contract matches the peer
invalid_operation The requested operation is not allowed in the current object/session/runtime state
data_lost A published relocation payload could not be found, or failed validation. There is no arbitrary rollback to the previous owner
internal_failure A Framework failure not expressible by the categories above. Check log and trace correlation information for the cause

Completion result. Only the Framework creates a framework_exception_t, and what() is a description for human diagnosis, not a programmatic branching target. code() adds diagnostic information when there is a platform cause such as a timeout or transport, but it does not substitute for the common failure classification. Configuration validation failures (such as a std::invalid_argument before startup) and argument errors are a different layer from this kind classification. This kind does not tell you whether to retry — the application decides that directly, checking the operation's completion condition, idempotency, and business state.

When to use. Use this table to look back at the kind given in each category entry's "Completion result" and decide how to respond.

See the Monitoring exact interface and the Channel messaging exact interface (Korean-only) for the full rationale.