Message Introspection

Message introspection lets you view the full lifecycle of messages flowing through your queues — from sent to processed, failed, or dead-lettered. It is invaluable for debugging and monitoring.

Inspecting Messages

Filter and paginate messages with inspect:

const q = rinda.queue('QUEUE_ID');

const result = await q.inspect({
  status: 'FAILED',
  limit: 50,
});

console.log(`Found ${result.data.length} failed messages`);
for (const msg of result.data) {
  console.log(`${msg.providerMessageId}: ${msg.errorMessage}`);
}

// Pagination
if (result.pagination.hasMore) {
  const nextPage = await q.inspect({
    status: 'FAILED',
    cursor: result.pagination.nextCursor,
  });
}

Filter Options

Filter	Description
status	Filter by lifecycle status
groupId	Filter by FIFO message group
deduplicationId	Filter by deduplication ID
search	Text search in message body
cursor	Pagination cursor from previous response
limit	Max results (default: 50, max: 100)

Message Statuses

Status	Description
QUEUED	Message is in the queue, waiting to be received
PROCESSING	Message has been received and is being processed
PROCESSED	Message was successfully processed and deleted
FAILED	Message processing failed (will be retried)
DEAD_LETTERED	Message exceeded max retries and was moved to DLQ
DELETED	Message was explicitly deleted
EXPIRED	Message exceeded retention period
DEDUPLICATED	Duplicate message was suppressed

Full-Text Search

Search messages by body content using PostgreSQL full-text search:

const result = await q.search('order-123', 20);

console.log(`Found ${result.data.length} matching messages`);
for (const msg of result.data) {
  console.log(`${msg.providerMessageId}: ${msg.status}`);
}

Message Groups (FIFO)

View message groups and their aggregated statistics for FIFO queues:

const result = await q.groups(10);

for (const group of result.data) {
  console.log(`Group: ${group.groupId}`);
  console.log(`  Total: ${group.messageCount}`);
  console.log(`  Queued: ${group.queued}`);
  console.log(`  Processing: ${group.processing}`);
  console.log(`  Processed: ${group.processed}`);
  console.log(`  Failed: ${group.failed}`);
  console.log(`  Dead-lettered: ${group.deadLettered}`);
}

Statistics

Get a high-level breakdown of message statuses:

const result = await q.breakdown();

console.log('Message breakdown:');
for (const { status, count } of result.data.byStatus) {
  console.log(`  ${status}: ${count}`);
}
console.log('Total deduplicated:', result.data.totalDeduplicated);

Use Cases

• Debugging — Find out why a specific message failed
• Monitoring — Track message throughput and failure rates
• Auditing — Full message lifecycle for compliance
• Alerting — Detect message processing issues early