$listLocalSessions是MongoDB聚合管道体系中的一个诊断型阶段，它并不用于数据读写，而是直接读取当前mongod或mongos进程内存里维护的本地会话缓存。理解这个阶段之前，需要先明确一个背景：MongoDB从3.6版本开始引入逻辑会话概念，用于支持因果一致性、重试写入以及事务等能力。驱动与数据库建立连接后，会在服务端生成对应的会话记录，这些记录就存放在节点本地缓存中。$listLocalSessions的作用，就是把当前节点上仍然活跃的本地会话条目以文档形式输出，方便后续用聚合管道做过滤、排序和投影。
这个阶段只能在admin库下通过db.aggregate()执行。也就是说，即使你要排查的是业务库中的会话，也必须先切换到admin库再运行聚合命令。它的输出不是永久存储的数据，而是实时内存快照，因此每次执行都可能因为连接的建立或释放而有所变化。对于单机实例或副本集成员来说，本地会话缓存只包含当前节点自己接收到的会话，不会自动汇总其他节点上的信息。这个特性在排查问题时需要特别注意，避免误判为全局会话数量。
$listLocalSessions的语法与返回结构
基本语法并不复杂，核心就是在一个聚合管道中放入$listLocalSessions阶段。该阶段接受一个对象作为参数，常用形式有两种：一种是{ allUsers: true }，表示列出所有用户的本地会话；另一种是users数组，用来精确指定要查看的用户和数据库。需要注意的是，如果使用users数组，每个元素需要包含user和db两个字段，否则会报错。
下面是一个在admin库下查询所有本地会话并限制返回5条的示例：
db.getSiblingDB("admin").aggregate([
{ $listLocalSessions: { allUsers: true } },
{ $limit: 5 }
])
返回的每个文档通常包含_id字段，它是一个由id和uid组成的复合对象，用来唯一标识一个逻辑会话。username和userDb分别表示该会话所属的数据库用户及其认证数据库。local对象则记录了当前节点上的本地信息，例如connectionId是建立该会话的连接编号，lastUse是最后一次使用该会话的时间。对于排查空闲连接来说，local.lastUse是一个很关键的字段。
实际返回的文档结构大致如下：
{
"_id": { "id": UUID("f47ac10b-58cc-4372-a567-0e02b2c3d479"), "uid": BinData(0, "xxx") },
"username": "app_user",
"userDb": "mydb",
"local": {
"connectionId": 12,
"lastUse": ISODate("2025-04-10T08:00:00Z")
}
}
这里需要留意一点，$listLocalSessions返回的lastUse时间是服务端记录的会话活动时间，它可能和连接建立时间不同。如果一个连接长时间没有发起新的操作，其会话的lastUse就会停留在较早的时间点，这个特征正好可以用来发现连接池中未被释放的空闲会话。
本地会话缓存与逻辑会话的区别
很多初次接触这个阶段的人容易把本地会话缓存和逻辑会话本身混为一谈。逻辑会话是由客户端驱动和MongoDB服务端共同维护的抽象概念，它有一个全局唯一的_id，用于串联同一业务操作中的多个读写请求。在分片集群中，逻辑会话信息会持久化到config库的system.sessions集合里，以便跨节点协调。而本地会话缓存只是当前节点从驱动连接中读取到的一部分会话信息，它更偏向于运行时状态，不会持久化。
正因为如此，$listLocalSessions和$listSessions这两个聚合阶段虽然名字相似，但行为差异很大。$listSessions可以列出集群中已经持久化的逻辑会话记录，在分片集群下通常需要连接到mongos执行，且可能涉及config库的读取。$listLocalSessions则只查看当前节点内存中的缓存，速度快、开销低，但范围也仅限于当前实例。如果在一个三节点副本集中，你需要在每个节点上分别执行$listLocalSessions，才能拼出整个副本集的本地会话分布。
可以用一个简单的对比来理解：逻辑会话更像是账户档案，记录了这个会话从创建到结束的完整生命周期；本地会话缓存则像是前台登记表，只记录当前还在节点上活跃的连接和最后活动时间。当连接断开或会话被清理后，本地缓存中的条目会消失，但逻辑会话可能仍然在config库中保留一段时间，直到过期被回收。
实战排查：定位空闲连接与异常会话
运维中最常见的一个场景是：应用连接池配置过大，或者某些服务没有正确关闭连接，导致mongod上堆积大量空闲会话。这些会话虽然不一定会消耗CPU，但会占用内存和一些内部资源，极端情况下可能触发会话缓存压力。通过$listLocalSessions配合聚合管道，可以快速找出长时间未活动的会话。
下面的示例会筛选出最近30分钟都没有活动过的本地会话，并按最后使用时间从早到晚排序，只输出用户名、数据库、连接编号和最后使用时间：
db.getSiblingDB("admin").aggregate([
{ $listLocalSessions: { allUsers: true } },
{ $match: { "local.lastUse": { $lt: new Date(Date.now() - 30 * 60 * 1000) } } },
{ $sort: { "local.lastUse": 1 } },
{ $project: { username: 1, userDb: 1, lastUse: "$local.lastUse", connectionId: "$local.connectionId" } }
])
如果只想查看特定用户的会话，避免全量扫描带来的干扰，可以把allUsers换成users数组。例如只查看业务库mydb中用户app_user的本地会话：
db.getSiblingDB("admin").aggregate([
{ $listLocalSessions: { users: [ { user: "app_user", db: "mydb" } ] } },
{ $limit: 20 }
])
这种方式在生产环境中更加安全，因为它只读取与目标用户相关的缓存条目，不会一次性遍历所有会话。对于连接数达到数千甚至上万的实例，直接执行allUsers: true可能会返回大量文档，增加聚合处理的负担。建议先用$limit限制输出，或者通过$match缩小范围。
权限控制、性能影响与使用边界
执行$listLocalSessions需要一定的权限。通常来说，用户需要在admin库上拥有clusterMonitor角色，或者具备listSessions这个特权动作。如果只是普通业务账号，运行时会收到权限不足的错误。为了最小化授权原则，可以创建一个专门用于会话排查的角色，只授予listSessions动作，再把这个角色分配给运维人员。
下面是一个创建自定义角色的示例，该角色只允许列出集群中的会话信息：
use admin
db.createRole({
role: "sessionInspector",
privileges: [
{ resource: { cluster: true }, actions: [ "listSessions" ] }
],
roles: []
})
从性能角度看，$listLocalSessions本身只是读取内存缓存，不像聚合普通集合那样需要扫描磁盘，因此执行速度通常很快。但如果本地会话数量极大，再加上$sort、$match这类操作，仍然可能占用一部分CPU和内存。建议在业务低峰期进行全量排查，或者优先使用带users过滤的查询方式。
另一个需要明确的边界是，这个阶段无法跨节点合并结果。在分片集群中，每个mongos和每个分片节点都有各自的本地会话缓存，$listLocalSessions只能反映当前连接到的那个节点的信息。如果想查看整个集群范围的会话情况，应该使用$listSessions并通过mongos执行，同时结合config库中的持久化会话记录做进一步分析。
总的来说，$listLocalSessions是一个轻量、实时的本地会话诊断工具。它适合用来快速定位单节点上的空闲连接、异常用户会话以及连接泄漏问题。理解它和$listSessions的差异，掌握正确的权限配置和过滤技巧，可以让你在遇到MongoDB会话相关问题时少走很多弯路。
MongoDB$listLocalSessions聚合管道修改时间：2026-10-05 05:23:35