Peek Messages

Overview

Peeking lets you look at what's sitting in a queue without touching it — the messages stay exactly where they are, still waiting for whichever consumer eventually receives them. It's the tool you reach for when you need visibility into queue state — checking backlog depth, inspecting payloads while debugging a stuck pipeline, or building an operational dashboard — without risking a collision with real consumers competing for the same work.

receive_queue_messages(client, channel, is_peek: true) is the same call your consumers use, just with is_peek set to true: the broker returns a snapshot of messages currently queued, confirmed by the is_peek flag on the result, but never marks them as delivered, locks them, or starts a visibility timeout — so no acknowledgment is needed or even possible.

Gotchas: peeked messages aren't reserved for you — a consumer calling without is_peek: true can remove them the instant after you peek, so treat the count as a point-in-time estimate, not a guarantee. Peek also won't surface messages already locked inside another consumer's in-flight receive, and it's not a substitute for receiving when you actually intend to process what you see.

Prerequisites

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

Code

channel = "elixir-queues.peek-messages"
{:ok, client} = KubeMQ.Client.start_link(address: "localhost:50000", client_id: "elixir-queue-peek")

for i <- 1..3 do
  {:ok, _} = KubeMQ.Client.send_queue_message(client,
    KubeMQ.QueueMessage.new(channel: channel, body: "Peekable message #{i}"))
end

IO.puts("Sent 3 messages")

case KubeMQ.Client.receive_queue_messages(client, channel,
       max_messages: 10,
       wait_timeout: 5_000,
       is_peek: true
     ) do
  {:ok, result} ->
    IO.puts("Peeked #{result.messages_received} messages (is_peek: #{result.is_peek})")

    Enum.each(result.messages, fn msg ->
      IO.puts("  #{msg.body}")
    end)

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

case KubeMQ.Client.receive_queue_messages(client, channel,
       max_messages: 10,
       wait_timeout: 5_000
     ) do
  {:ok, result} ->
    IO.puts("After peek, received #{result.messages_received} messages (still available)")

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

KubeMQ.Client.close(client)

How It Works

• is_peek: true inspects messages without removing them from the queue
• Messages remain available for subsequent receive operations
• Useful for monitoring queue depth and message content

Related

• Send & Receive
• Poll Mode