Pulsar分区主题未消费消息数查询异常：API返回值始终为0

首先需要明确两个核心概念，这是解决问题的关键：

• 未被任何消费者获取的消息：即主题的backlog，指生产者已发送到主题，但还未被任何消费者拉取（或拉取后超时重新放回）的消息总数。
• 已被消费者获取但未确认的消息：即unacked messages，这类消息已被消费者拉取，但尚未发送确认（ack），不属于主题级backlog，仅存在于具体订阅的统计中。

情况1：查询未被任何消费者获取的消息数（Backlog） #

你之前使用的/backlog和/stats接口本身是正确的，但出现返回0的情况可能有以下原因：

1. 分区主题路径错误：分区主题的完整格式为persistent/public/default/{topic-name}-partition-{n}（比如mytopic-partition-0）。如果直接查询父主题名（如mytopic），返回的是所有分区backlog的总和；若每个分区的backlog确实为0，总和自然是0。
   • 解决：单独查询每个分区的backlog，或确认父主题的总和是否符合预期。
2. 消息已被消费者拉取：即使消息未被确认，只要已经被消费者拉取（分配到消费者处理），就会从主题backlog中移除，直到消费者超时未确认才会重新放回。此时主题backlog为0是正常现象。

Python调用示例（查询主题总backlog） #

import requests

pulsar_admin_url = "http://你的PulsarAdmin地址:8080"
topic_full_path = "persistent/public/default/你的主题名"

response = requests.get(f"{pulsar_admin_url}/admin/v2/{topic_full_path}/backlog")
if response.status_code == 200:
    total_backlog = response.json()
    print(f"未被任何消费者获取的消息总数：{total_backlog}")
else:
    print(f"请求失败：{response.status_code} - {response.text}")

情况2：查询已被获取但未确认的消息数（Unacked） #

如果你的实际需求是这类消息，主题级接口无法返回，必须查询具体订阅的统计接口：

1. 使用订阅状态接口：GET /admin/v2/persistent/public/default/{topic-name}/subscriptions/{subscription-name}
2. 使用订阅统计接口：GET /admin/v2/persistent/public/default/{topic-name}/subscriptions/{subscription-name}/stats

返回的JSON中，unackedMessages字段即为已拉取未确认的消息数，backlog字段为该订阅下未被拉取的消息数。

Python调用示例（查询订阅的未确认消息数） #

import requests

pulsar_admin_url = "http://你的PulsarAdmin地址:8080"
topic_full_path = "persistent/public/default/你的主题名"
subscription_name = "你的订阅名"

response = requests.get(f"{pulsar_admin_url}/admin/v2/{topic_full_path}/subscriptions/{subscription_name}/stats")
if response.status_code == 200:
    subscription_stats = response.json()
    unacked_count = subscription_stats.get("unackedMessages", 0)
    subscription_backlog = subscription_stats.get("backlog", 0)
    print(f"该订阅已获取未确认消息数：{unacked_count}")
    print(f"该订阅未被获取的消息数：{subscription_backlog}")
else:
    print(f"请求失败：{response.status_code} - {response.text}")

额外注意事项 #

• 确认Pulsar版本：v2版本的Admin API是稳定的，若使用旧版本可能存在接口差异。
• 订阅类型影响统计：共享订阅下，unackedMessages是各消费者的未确认消息总和；独占/故障转移订阅下，该数值对应单个活跃消费者的未确认消息数。

内容的提问来源于stack exchange，提问作者VVictor