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(channel:, max_messages:, wait_timeout_seconds:, peek: true) is the same call your consumers use, just with peek set to true: the broker returns a snapshot of messages currently queued 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 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
• Ruby SDK installed (gem install kubemq)

Code

require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
channel = 'ruby-queues.peek-messages'

begin
  client = KubeMQ::QueuesClient.new(address: address, client_id: 'peek-example')
  puts "Connected to #{address}"

  3.times do |i|
    msg = KubeMQ::Queues::QueueMessage.new(channel: channel, metadata: "item-#{i}", body: "data-#{i}")
    client.send_queue_message(msg)
  end
  puts 'Sent 3 messages'

  peeked = client.receive_queue_messages(channel: channel, max_messages: 10, wait_timeout_seconds: 5, peek: true)
  puts "Peeked #{peeked.size} messages (still in queue):"
  peeked.each { |m| puts "  #{m.metadata}: #{m.body}" }

  remaining = client.receive_queue_messages(channel: channel, max_messages: 10, wait_timeout_seconds: 5)
  puts "Received #{remaining.size} messages (removed from queue)"
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Done'
end

How It Works

• Setting peek: true in receive_queue_messages returns messages without removing them from the queue.
• Peeked messages remain available for subsequent receive operations.
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Pattern overview
• Ruby SDK Reference
• Send & Receive