Ping

Overview

A ping is a lightweight liveness check — you call it to confirm the broker is actually reachable before sending real traffic, without standing up a publisher, subscriber, or queue client just to find out. It's the tool of choice for startup readiness checks, container liveness/readiness probes, and connection-health dashboards that need a fast, cheap go/no-go signal.

KubeMQ.Client.ping/1 issues a minimal RPC to the server and returns {:ok, %KubeMQ.ServerInfo{}} (host, version, uptime) confirming the broker answered. It works over the same connection regardless of which messaging pattern you use elsewhere on that client — events, queues, commands, or queries.

Gotchas: a failed ping doesn't close the client — the SDK's reconnect logic keeps retrying in the background, so pattern-match on the {:error, error} tuple yourself rather than assume the client tears itself down. A successful ping only confirms the broker process answered, not that a specific channel or queue exists or has capacity. And since the underlying connection is often established lazily, the first call you make is what actually triggers it.

Prerequisites

• KubeMQ server running on localhost:50000
• Elixir SDK installed ({:kubemq, "~> 1.0"} in mix.exs)

Code

IO.puts("Connecting to KubeMQ server...")
{:ok, client} = KubeMQ.Client.start_link(address: "localhost:50000", client_id: "elixir-ping-example")

case KubeMQ.Client.ping(client) do
  {:ok, info} ->
    IO.puts("Ping successful!")
    IO.puts("  Host: #{info.host}")
    IO.puts("  Version: #{info.version}")
    IO.puts("  Server start time: #{info.server_start_time}")
    IO.puts("  Server up time: #{info.server_up_time_seconds}s")

  {:error, error} ->
    IO.puts("Ping failed: #{error.message}")
end

KubeMQ.Client.close(client)

How It Works

• ping/1 returns {:ok, %KubeMQ.ServerInfo{}} with server metadata on success
• The ServerInfo struct contains host, version, server_start_time, and server_up_time_seconds
• Useful for health checks and connectivity verification

Related

• Connect
• Elixir SDK Reference