Skip to content

GET /api/admin/inspect-ready-q/v1

Info

This page was generated by extracting information from a JSON Schema data file for the API. It may be missing some information, or otherwise suggest approximate or placeholder values based on information in the schema file; this is due to limitations on how that data is extracted from the underlying Rust code and into the JSON Schema, and then again from there and into these docs.

Retrieve a snapshot of a ready queue's state, configuration, and the dispatcher tasks that are currently handling connections on its behalf.

This API endpoint is used by the kcli inspect-ready-q command.

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

Query Parameters

  • queue_name - required string. The name of the ready queue to inspect.

Responses

Status 200

Ready queue snapshot

Content-Type: application/json

Response body for the inspect-ready-q endpoint.

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

This is an object value, with the following properties:

  • constraints - required EffectiveConstraints. Steady-state throughput ceilings implied by path_config. Each axis is tagged with the configuration term that produced it, so operators can tell whether a plateau in the observed rate is the result of shaping configuration or the remote side.

  • dispatchers - required array of DispatcherSummary.

  • egress_pool - required string.

  • egress_source - required string.

  • mx - optional nullable MxResolution.

  • now - required string (date-time).

  • path_config - required object. Snapshot of the egress path configuration in effect for this queue.

  • protocol - required string. Protocol identifier as it appears in the ready queue name.

  • queue_name - required string.

  • state - required ReadyQueueStateSnapshot. Snapshot of the operational state of a ready queue.

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

Examples

{
  "constraints": {
    "max_concurrent_dispatchers": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    },
    "max_connection_rate": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    },
    "max_message_rate": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    },
    "max_message_rate_declared": "string",
    "max_source_selection_rate": {
      "display": "string",
      "source": {
        "kind": "primary"
      },
      "value": 4.2
    }
  },
  "dispatchers": [
    {
      "age": "string",
      "delivered_this_connection": 42,
      "detail": "string",
      "messages_delivered": 42,
      "messages_failed": 42,
      "messages_transfailed": 42,
      "overall_rate_per_sec": 4.2,
      "phase": "Starting",
      "session_id": "9511a32e-66f8-42aa-b151-ccb176df47d9",
      "started_at": "1990-12-31T23:59:60Z",
      "time_in_current_phase": "string"
    }
  ],
  "egress_pool": "string",
  "egress_source": "string",
  "mx": {
    "by_preference": {},
    "is_domain_literal": false,
    "is_mx": false,
    "is_secure": false,
    "site_name": "string"
  },
  "now": "1990-12-31T23:59:60Z",
  "path_config": {},
  "protocol": "smtp_client",
  "queue_name": "string",
  "state": {
    "connection_count": 42,
    "connection_limited": {
      "context": "TooManyLeases for queue",
      "since": "1990-12-31T23:59:60Z"
    },
    "connection_rate_throttled": {
      "context": "TooManyLeases for queue",
      "since": "1990-12-31T23:59:60Z"
    },
    "ready_count": 42,
    "suspended": {
      "duration": "string",
      "expires": "1990-12-31T23:59:60Z",
      "id": "9511a32e-66f8-42aa-b151-ccb176df47d9",
      "name": "source_name->(alt1|alt2|alt3|alt4)?.gmail-smtp-in.l.google.com@smtp_client",
      "reason": "pause while working on resolving a block with the destination postmaster"
    },
    "watchdog_threshold": "string"
  }
}

Status 404

No such ready queue