MongoDB $listSessions Stage

What Is $listSessions?

$listSessions is a MongoDB aggregation stage that lists logical sessions across a sharded cluster when run on mongos—a single cluster-wide inventory instead of checking each shard with $listLocalSessions.

$listSessions = "who has sessions across the CLUSTER?"

db.getSiblingDB("admin").aggregate([
  { $listSessions: {} }
])

connect via mongos (sharded cluster)
must run on admin
must be the FIRST stage
allUsers: false → your sessions only (default)
allUsers: true  → every session in cluster scope
lastUse → when the session was last active

$this node only → $listLocalSessions
cluster view → $listSessions

How to Use $listSessions in MongoDB

Connect to mongos, run on admin, put the stage first, then filter or project.

1. Connect to mongos (sharded cluster router).
2. Switch to admin: db.getSiblingDB("admin").
3. Start with { $listSessions: {} } or { allUsers: true }.
4. Optional: $match on lastUse, $sort, $limit.
5. Optional: $project to keep id, user, and lastUse.

Pseudocode

assert: connected to mongos (sharded cluster)
assert: pipeline runs on admin
assert: $listSessions is stage 1

sessions = logical sessions visible cluster-wide

if allUsers is false:
  keep only sessions for current user
else:
  keep all sessions in cluster scope
  (requires privilege when auth is on)

for each session:
  emit { id, user, lastUse, … }

// later $match / $sort / $project reshape the list

Cheat Sheet

Keep these facts handy during cluster session audits.

Live Preview

Filter a sample cluster session snapshot (teaching model—not a live mongos connection).

appUser @ admin     lastUse: 2 min ago
appUser @ admin     lastUse: 40 min ago

Worked Walkthrough — List Your Cluster Sessions

You are connected to mongos with mongosh. Goal: see your logical sessions across the cluster, newest activity first.

1. Connect to mongos
2. db.getSiblingDB("admin")
3. $listSessions {}          ← first stage
4. Defaults: allUsers false  → only your sessions
5. $project id, user, lastUse
6. Optional: $sort { lastUse: -1 }

Any find()/update you run updates lastUse
on your client session record.

MongoDB Examples

These pipelines run on the admin database via mongos and inspect live session metadata (not a seeded collection). Results depend on who is connected to your cluster.

// Touch a session (any database is fine)
db.getSiblingDB("test").products.findOne()

// List sessions — must use admin on mongos
db.getSiblingDB("admin").aggregate([
  { $listSessions: {} }
])

{
  id: UUID("..."),
  lastUse: ISODate("..."),
  user: { user: "myApp", db: "admin" }
}
// Exact fields/values vary by MongoDB version and auth setup

db.getSiblingDB("admin").aggregate([
  { $listSessions: {} },
  {
    $project: {
      sessionId: "$id",
      username: "$user.user",
      authDb: "$user.db",
      lastUse: 1,
      _id: 0
    }
  },
  { $sort: { lastUse: -1 } }
])

Your mongosh / driver sessions appear
Other users stay hidden (default scope)
Safe pattern for non-admin developers

const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000)

db.getSiblingDB("admin").aggregate([
  { $listSessions: { allUsers: true } },
  { $match: { lastUse: { $gte: oneHourAgo } } },
  {
    $group: {
      _id: { user: "$user.user", db: "$user.db" },
      sessionCount: { $sum: 1 },
      latestActivity: { $max: "$lastUse" }
    }
  },
  { $sort: { sessionCount: -1 } }
])

// allUsers: true needs listSessions privilege when auth is enabled
// Prefer mongos — cluster-oriented view vs $listLocalSessions

{
  _id: { user: "appUser", db: "admin" },
  sessionCount: 28,
  latestActivity: ISODate("...")
}
// High sessionCount can mean connection-pool pressure

Performance Notes

Prefer narrow projections and time filters so dashboards stay small. Pair with $currentOp when you also need running operations.

Key Takeaways