# Data Models (/operate/observability/api-reference/data-models) These are the data-transfer objects (DTOs) the KubeMQ management API returns across its endpoints — the structures a dashboard, console, or tooling client consumes and renders. Each group below names which endpoint returns it. Field types use TypeScript notation; a trailing `?` marks an optional field that the server omits when empty. For the response envelope and status-code rules, see the [Management API overview](/operate/observability/api-reference). ## Response envelope [#response-envelope] Every HTTP endpoint except `/health`, `/ready`, and `/metrics` wraps its payload in a standard envelope. The DTOs below are what you find inside the `data` field. | Field | Type | Description | | -------------- | --------------- | ------------------------------------------------------ | | `error` | `boolean` | `true` if the request failed | | `error_string` | `string` | Error message when `error` is `true`; empty on success | | `data` | `any` or `null` | The response payload — one of the DTOs documented here | ## Snapshot DTOs [#snapshot-dtos] These DTOs make up the dashboard data model. The top-level `SnapshotDTO` is returned by `GET /api/snapshot` and `GET /api/cluster-snapshot`, and streamed every 2 seconds over `WS /api/connection`; the rest are nested inside it. ### SnapshotDTO [#snapshotdto] The main dashboard data structure — channel and client totals, per-family detail, traffic topology, and pre-computed stat cards for one node or the whole cluster. | Field | Type | Description | | ------------------- | -------------------- | --------------------------------------------- | | `hostsInfo` | `HostInfoDTO[]` | One entry per cluster node | | `topologyNodes` | `TopologyNodesDTO` | Cluster-to-client connection graph | | `trafficChannels` | `TrafficChannelsDTO` | Per-channel client connections with direction | | `statsCards` | `StatCardDTOs` | Pre-computed dashboard stat cards | | `topChannels` | `TopChannelDTO[]` | Top 10 most recently active channels | | `lastActivity` | `number` | Unix-ms timestamp of last activity | | `lastActivityHuman` | `string` | Humanized, e.g. `"2 seconds ago"` | | `total` | `BaseValuesDTO` | Combined incoming + outgoing | | `incoming` | `BaseValuesDTO` | Aggregate incoming | | `outgoing` | `BaseValuesDTO` | Aggregate outgoing | | `channels` | `number` | Total channel count | | `channelsHuman` | `string` | Formatted count, e.g. `"1,234"` | | `clients` | `number` | Total client count | | `clientsHuman` | `string` | Formatted count | | `activeChannels` | `number` | Currently active channels | | `queues` | `FamilyDTO` | Queue channels family | | `pubsub` | `FamilyDTO` | Events + Events Store family | | `commandsQueries` | `FamilyDTO` | Commands + Queries family | | `nodeType` | `string` | Node type from configuration | | `node` | `string` | Node hostname | Notes: * `pubsub` merges `events` and `events_store` channels into one family. * `commandsQueries` merges `commands` and `queries` into one family (its internal `name` is `request_reply`). * `topChannels` is limited to 10 entries, sorted by most recent activity. * Every `*Human` field is a pre-formatted string ready to display. ### HostInfoDTO [#hostinfodto] System information for a single cluster node — one element of `SnapshotDTO.hostsInfo`. | Field | Type | Description | | -------------------- | -------- | ------------------------------------------------------------- | | `host` | `string` | Node hostname | | `version` | `string` | KubeMQ version | | `lastUpdate` | `string` | `"2006-01-02 15:04:05"` format | | `status` | `string` | `"Running"` (updated within the last 10s) or `"Disconnected"` | | `role` | `string` | `"Leader"`, `"Follower"`, or a title-cased role | | `uptime` | `string` | Go duration format, e.g. `"24h30m15s"` | | `memoryAllocated` | `string` | Humanized bytes, e.g. `"256 MB"` | | `memoryUsed` | `string` | Humanized bytes | | `memoryUtilization` | `number` | 0–100 percentage | | `osThreads` | `number` | OS thread count | | `cpuCores` | `number` | CPU core count | | `cpuUtilization` | `number` | 0–100 percentage | | `activeClients` | `number` | Active client connections | | `storageAllocated` | `string` | Humanized bytes | | `storageUsed` | `string` | Humanized bytes | | `storageUtilization` | `number` | 0–100 percentage | | `memoryAvailable` | `string` | Humanized bytes, `"N/A"` if unknown | ### TopologyNodesDTO [#topologynodesdto] The cluster topology graph — node and client lists plus the edges between them, used to render the dashboard's topology view. ```typescript interface TopologyNodesDTO { clusterNodesList: string[]; // KubeMQ node hostnames clientNodesList: string[]; // Connected client identifiers clusterClientConnections: ClusterClientConnectionDTO[]; // Edges } interface ClusterClientConnectionDTO { clusterNode: number; // Index into clusterNodesList clientNode: number; // Index into clientNodesList } ``` `clusterNodesList` and `clientNodesList` are the two groups of graph nodes; `clusterClientConnections` are edges joining a cluster node to a client node by array index. Only connections seen within the last 5 minutes are included. ### TrafficChannelsDTO [#trafficchannelsdto] Maps each channel to the clients connected to it and their direction, powering the dashboard's traffic map. ```typescript interface TrafficChannelsDTO { channels: Record; // key: "{type}/{channel}" } interface TrafficChannelConnectionDTO { clientId: string; side: string; // "send" or "receive" } ``` The map key is `"{channelType}/{channelName}"` (e.g. `"queues/orders"`). Only clients seen within the last 5 minutes are included. ### StatCardDTOs [#statcarddtos] The four pre-computed cards on the dashboard overview — channels, clients, incoming, and outgoing — each with a primary/secondary value pair and a per-family breakdown. ```typescript interface StatCardDTOs { channels: StatCardDTO; outgoing: StatCardDTO; incoming: StatCardDTO; clients: StatCardDTO; } interface StatCardDTO { primaryItemCaption: string; // e.g. "Active", "Messages", "Total" primaryItemValue: string; // e.g. "5", "50,000" secondaryItemCaption: string; // e.g. "Total", "Volume", "" (clients) secondaryItemValue: string; // e.g. "10", "48 MB" queues?: StatCardSectionDTO; pubsub?: StatCardSectionDTO; commandsQueries?: StatCardSectionDTO; } interface StatCardSectionDTO { title: string; // "Queues", "PubSub", or "Commands & Queries" caption: string; // e.g. "(3/5)" or "(5,000/4.9 MB)" value: string; // Percentage, e.g. "50.0%" } ``` Each card pairs a primary and secondary value with a per-family section: the channels card shows active/total counts, clients shows per-family counts, and incoming/outgoing show messages/volume with each family's share of total volume. ### TopChannelDTO [#topchanneldto] A single row in the dashboard's "Top Channels" table — one entry per recently active channel inside `SnapshotDTO.topChannels`. | Field | Type | Description | | -------------- | -------- | ---------------------------------------------------------------------- | | `type` | `string` | Display type: `Queue`, `Events`, `Events-Store`, `Commands`, `Queries` | | `channel` | `string` | Channel name | | `lastActivity` | `string` | Humanized, e.g. `"2 seconds ago"` | | `sent` | `string` | `"messages/volume"`, e.g. `"5,000/4.9 MB"` | | `delivered` | `string` | `"messages/volume"` | | `clients` | `string` | `"active/total"`, e.g. `"3/5"` | | `channelKey` | `string` | Unique key `"{type}-{channel}"`, e.g. `"Queue-orders.process"` | The internal channel type maps to a display type: `queues → Queue`, `events → Events`, `events_store → Events-Store`, `commands → Commands`, `queries → Queries`. ### FamilyDTO [#familydto] Detailed data for a channel family — the full list of channels with their metrics. The `queues`, `pubsub`, and `commandsQueries` fields of `SnapshotDTO` are each a `FamilyDTO`. | Field | Type | Description | | --------------------- | --------------- | ---------------------------------------------------------------- | | `name` | `string` | `queues`, `pubsub`, or `request_reply` | | `lastActivity` | `number` | Unix-ms timestamp | | `lastActivityHuman` | `string` | Humanized, e.g. `"5 seconds ago"` | | `total` | `BaseValuesDTO` | Combined metrics | | `incoming` | `BaseValuesDTO` | Incoming metrics | | `outgoing` | `BaseValuesDTO` | Outgoing metrics | | `channelsList` | `ChannelDTO[]` | All channels in this family, sorted by `lastActivity` descending | | `channels` | `number` | Channel count | | `channelsHuman` | `string` | Formatted count | | `clients` | `number` | Total clients across all channels | | `clientsHuman` | `string` | Formatted count | | `activeChannels` | `number` | Active channel count | | `activeChannelsHuman` | `string` | Formatted count | | `isActive` | `boolean` | `true` if `lastActivity` was within the last 5 minutes | Family names: Queues holds Queue channels (`queues`), PubSub holds Events + Events Store channels (`pubsub`), and Commands & Queries holds Commands + Queries channels (`request_reply`). ### ChannelDTO [#channeldto] Detailed data for a single channel, including its per-client breakdown — an element of `FamilyDTO.channelsList`. | Field | Type | Description | | ------------------- | --------------- | ------------------------------------------------------------ | | `name` | `string` | Channel name | | `type` | `string` | `queues`, `events`, `events_store`, `commands`, or `queries` | | `lastActivity` | `number` | Unix-ms timestamp | | `lastActivityHuman` | `string` | Humanized, e.g. `"10 seconds ago"` | | `total` | `BaseValuesDTO` | Combined incoming + outgoing | | `incoming` | `BaseValuesDTO` | Incoming metrics | | `outgoing` | `BaseValuesDTO` | Outgoing metrics | | `isActive` | `boolean` | `true` if active within the last 5 minutes | | `channelKey` | `string` | Unique key `"{type}-{name}"` | | `clients` | `ClientDTO[]` | Clients connected to this channel | ### ClientDTO [#clientdto] Metrics for a single client connected to a specific channel — an element of `ChannelDTO.clients`. | Field | Type | Description | | ------------------- | --------------- | ------------------------------------------ | | `name` | `string` | Client identifier | | `lastActivity` | `number` | Unix-ms timestamp | | `lastActivityHuman` | `string` | Humanized, e.g. `"3 seconds ago"` | | `total` | `BaseValuesDTO` | Combined incoming + outgoing | | `incoming` | `BaseValuesDTO` | Incoming metrics for this client | | `outgoing` | `BaseValuesDTO` | Outgoing metrics for this client | | `isActive` | `boolean` | `true` if active within the last 5 minutes | ### BaseValuesDTO [#basevaluesdto] The fundamental metrics unit used throughout the snapshot DTOs — raw numeric values paired with pre-formatted humanized strings. Appears as the `total`, `incoming`, and `outgoing` field on snapshots, families, channels, and clients. | Field | Type | Description | | ---------------------------------------- | ------------------- | -------------------------------------- | | `messages` / `messagesHumanized` | `number` / `string` | Total message count | | `volume` / `volumeHumanized` | `number` / `string` | Total volume in bytes | | `errors` / `errorsHumanized` | `number` / `string` | Error count | | `waiting` / `waitingHumanized` | `number` / `string` | Waiting messages (Queues only) | | `clients` / `clientsHumanized` | `number` / `string` | Client count | | `lastActivity` / `lastActivityHumanized` | `number` / `string` | Unix-ms timestamp | | `expired` / `expiredHumanized` | `number` / `string` | Expired message count (Queues only) | | `delayed` / `delayedHumanized` | `number` / `string` | Delayed message count (Queues only) | | `responses` / `responsesHumanized` | `number` / `string` | Response count (Commands/Queries only) | Which fields are populated depends on the channel type: | Field | Queues | Events | Events Store | Commands | Queries | | ----------------------------------------- | ------ | ------ | ------------ | -------- | ------- | | `messages`, `volume`, `errors`, `clients` | Y | Y | Y | Y | Y | | `waiting`, `expired`, `delayed` | Y | N | N | N | N | | `responses` | N | N | N | Y | Y | ## Charts [#charts] These DTOs are returned by the `get_charts_array` action on [`POST /api/request`](/operate/observability/api-reference/actions) and drive the dashboard's time-series charts. ### ChartsArrayDTO / ChartDataDTO [#chartsarraydto--chartdatadto] `ChartsArrayDTO` bundles four time series — incoming/outgoing messages and volume — each a `ChartDataDTO` of parallel label and value arrays. ```typescript interface ChartsArrayDTO { incomingMessages: ChartDataDTO; incomingVolume: ChartDataDTO; outgoingMessages: ChartDataDTO; outgoingVolume: ChartDataDTO; } interface ChartDataDTO { labels: string[]; // X-axis time labels, e.g. ["12:00", "12:05", "12:10"] data: string[]; // Y-axis values, e.g. ["150", "200", "175"] } ``` The label format depends on the requested time range and uses Go's reference-time layout (not locale-specific names): | Time range | Layout | Example | | ----------------------- | -------------- | -------------- | | `1h`, `2h`, `6h`, `12h` | `15:04` | `14:35` | | `1d` | `15:00` | `14:00` | | `7d` | `01-02 15:00` | `03-01 14:00` | | `14d`, `30d` | `01-02` | `03-01` | The `time_zone` parameter on the request is an integer offset in **minutes**, applied as `adjusted_time = timestamp + (time_zone * -1)` minutes. This matches the browser's `new Date().getTimezoneOffset()` (positive west of UTC, negative east), so pass that value directly: | Location | `getTimezoneOffset()` | Pass as `time_zone` | | -------------- | --------------------- | ------------------- | | UTC | `0` | `0` | | EST (UTC−5) | `300` | `300` | | IST (UTC+5:30) | `-330` | `-330` | ## Health & billing [#health--billing] These two small DTOs are returned by the system endpoints documented under [Health & System Endpoints](/operate/observability/api-reference/health-system). ### HealthState [#healthstate] Returned (without an envelope) by `GET /ready` — the node's health and readiness, plus its role in the cluster. | Field | Type | Description | | ------------------------- | --------- | --------------------------------------------------------------------- | | `is_healthy` | `boolean` | Process health | | `is_ready` | `boolean` | Ready to accept traffic | | `current_leadership_role` | `string` | The node's cluster leadership role: `"leader"`, `"follower"`, or `""` | ### Billing [#billing] A usage summary returned by `GET /billing`. | Field | Type | Description | | -------------- | -------- | -------------------------------------------- | | `hostname` | `string` | Node hostname | | `uptime` | `number` | Uptime in seconds | | `messages` | `number` | Total messages processed | | `volume` | `number` | Total volume in bytes | | `last_message` | `number` | Unix timestamp (seconds) of the last message | ## Stats [#stats] These DTOs are returned by the read-only statistics endpoints under [Stats Endpoints](/operate/observability/api-reference/stats). ### Queues / Queue [#queues--queue] Queue and Events Store statistics from the persistence engine, returned by `GET /v1/stats/queues` and `GET /v1/stats/events_stores`. `Queues` is the summary; `Queue` is one per-stream entry in its `queues` array. ```typescript interface Queues { now: string; // RFC3339 timestamp total_queues: number; // Total queue count sent: number; // Total messages sent waiting: number; // Total messages waiting delivered: number; // Total messages delivered queues: Queue[]; // Per-queue detail } interface Queue { name: string; // Queue/stream name messages: number; // Total stored messages bytes: number; // Total stored bytes first_sequence: number; // First message sequence last_sequence: number; // Last message sequence sent: number; // Messages sent subscribers: number; // Active subscriber count waiting: number; // Messages waiting for delivery delivered: number; // Messages delivered } ``` ### ChannelStats / ChannelsSummery [#channelstats--channelssummery] Per-channel and per-type stats returned by `GET /v1/stats/channels`. `ChannelStats` is one channel; `ChannelsSummery` aggregates by channel type. ```typescript interface ChannelStats { kind: string; // "queues", "events", "events_store", "commands", "queries" name: string; // Channel name total_messages: number; total_volume: number; // Bytes total_errors: number; } interface ChannelsSummery { kind: string; // Channel type total_channels: number; // Count of channels of this type total_messages: number; total_volume: number; total_errors: number; } ``` ### ClientsStats [#clientsstats] Per-client stats returned by `GET /v1/stats/clients`. | Field | Type | Description | | ---------------- | -------- | --------------------- | | `name` | `string` | Client identifier | | `total_messages` | `number` | Total messages | | `total_volume` | `number` | Total volume in bytes | | `total_errors` | `number` | Total errors | | `total_pending` | `number` | Pending messages | ### MinimalChannelDTO [#minimalchanneldto] A lightweight channel representation used in list-channels responses, carrying just the identifying fields and a compact metrics pair. ```typescript interface MinimalChannelDTO { name: string; type: string; lastActivity: number; // Unix-ms timestamp isActive: boolean; // Active within the last 5 minutes incoming: MinimalBaseValuesDTO; outgoing: MinimalBaseValuesDTO; } interface MinimalBaseValuesDTO { messages: number; volume: number; waiting: number; expired: number; delayed: number; responses: number; } ``` ## Monitor transports [#monitor-transports] The [`GET /api/monitor`](/operate/observability/api-reference/websockets) WebSocket streams each frame as pretty-printed JSON with no wrapping envelope and no `type` field. There are five transport DTOs, one per monitored channel kind; the client identifies the type from the fields present. ### TransportPubSubMessageDto [#transportpubsubmessagedto] Events and Events Store monitoring (`kind = events` or `events_store`). ```typescript interface TransportPubSubMessageDto { messageId: string; metadata?: string; // omitted if empty body?: any; // omitted if empty; auto-detected format timestamp?: string; // "2006-01-02 15:04:05"; omitted if zero sequence?: number; // omitted if zero tags?: string; // JSON string; omitted if empty } ``` ### TransportRequestMessageDto [#transportrequestmessagedto] Commands and Queries monitoring (`kind = commands` or `queries`). ```typescript interface TransportRequestMessageDto { requestId: string; metadata?: string; // omitted if empty timestamp?: string; // "2006-01-02 15:04:05" (set to current time) body?: any; // omitted if empty timeout?: number; // milliseconds; omitted if zero tags?: string; // JSON string; omitted if empty } ``` ### TransportResponseMessageDto [#transportresponsemessagedto] A response delivered to a monitored request. ```typescript interface TransportResponseMessageDto { requestId: string; metadata?: string; // omitted if empty body?: any; // omitted if nil timestamp?: string; // "2006-01-02 15:04:05"; omitted if zero tags?: string; // JSON string; omitted if empty error?: string; // omitted if empty executed?: boolean; // omitted if false } ``` ### TransportResponseErrorMessageDto [#transportresponseerrormessagedto] A monitored request that ended in error. ```typescript interface TransportResponseErrorMessageDto { requestId: string; error?: string; // omitted if empty timestamp?: string; // "2006-01-02 15:04:05" (set to current time) } ``` ### TransportQueueMessageDto [#transportqueuemessagedto] Queue monitoring (`kind = queue`). ```typescript interface TransportQueueMessageDto { messageId: string; metadata?: string; // omitted if empty body?: any; // omitted if empty timestamp?: string; // "2006-01-02 15:04:05"; omitted if zero sequence?: number; // omitted if zero tags?: string; // JSON string; omitted if empty receivedCount?: number; // omitted if zero reRoutedFrom?: string; // omitted if empty expirationAt?: string; // "2006-01-02 15:04:05"; omitted if zero delayedTo?: string; // "2006-01-02 15:04:05"; omitted if zero } ``` ### Identifying the transport type [#identifying-the-transport-type] Because monitor frames carry no discriminator, identify the type from the fields present: | Distinguishing fields | Transport type | | ------------------------------------------------------ | ----------------------- | | `messageId` + `sequence`, no `receivedCount` | PubSub message | | `messageId` + `receivedCount` | Queue message | | `requestId` + `timeout` | Request (command/query) | | `requestId` + `executed` | Response | | `requestId` + `error`, no `executed`/`body`/`metadata` | Response error | ## Channel-type reference [#channel-type-reference] Channel types are represented as strings throughout the API: | Value | Display name | Description | | -------------- | ------------ | ----------------------------------------------------- | | `queues` | Queue | Persistent message queues with at-least-once delivery | | `events` | Events | Fire-and-forget pub/sub (no persistence) | | `events_store` | Events Store | Persistent pub/sub with replay | | `commands` | Commands | Fire-and-confirm RPC pattern | | `queries` | Queries | Request-response RPC pattern | The `create_channel` and `delete_channel` actions accept exactly these five values: `queues`, `events`, `events_store`, `commands`, `queries`. ### Body data-type handling [#body-data-type-handling] Several request types accept an `any`-typed `body`. The server detects the type automatically: * **Sending (any → bytes):** a `string` is UTF-8 encoded; a JSON `object` or `array` is serialized to JSON bytes; any other type is an error. * **Receiving (bytes → any):** valid JSON object or array bytes are returned as that structure; anything else is returned as a string. ### Tags format [#tags-format] In **action requests**, tags use a comma-separated `key=value` format: ```text priority=high,region=us-east,version=2 ``` In **response objects**, tags are returned as a JSON string: ```json "{\"priority\":\"high\",\"region\":\"us-east\"}" ``` ### Timestamp conventions [#timestamp-conventions] | Context | Format | Unit | | ------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------ | | `SnapshotDTO.lastActivity`, `BaseValuesDTO.lastActivity`, `ChannelDTO.lastActivity`, `ClientDTO.lastActivity` | Unix timestamp | Milliseconds | | `SubscribePubSubMessage.timestamp`, `SubscribeCQRSRequestMessage.timestamp` | Unix timestamp | Milliseconds | | `ReceiveQueueMessageResponse.timestamp`, `ReceiveCQRSResponse.timestamp` | Unix timestamp | Milliseconds | | `SendQueueMessageResponse.sentAt` | ISO 8601 / RFC3339 | String | | `SendQueueMessageResponse.expiresAt`, `HostInfoDTO.lastUpdate` | `"2006-01-02 15:04:05"` | String | | `Billing.last_message` | Unix timestamp | Seconds | ## Related [#related]