MongoDB $listLocalSessions Stage

What Is $listLocalSessions?

$listLocalSessions is a MongoDB aggregation stage that lists logical sessions on the current mongod (or mongos)—server-side records used for retryable writes, transactions, and causal consistency.

$listLocalSessions = "who has sessions on THIS node?"

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

must run on admin
must be the FIRST stage
allUsers: false → your sessions only (default)
allUsers: true  → every session on this node
lastUse → when the session was last active

$this node only → not cluster-wide
cluster view → $listSessions

How to Use $listLocalSessions in MongoDB

Run on admin, put the stage first, then filter or project.

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

Pseudocode

assert: pipeline runs on admin
assert: $listLocalSessions is stage 1

sessions = logical sessions cached on THIS node

if allUsers is false:
  keep only sessions for current user
else:
  keep all sessions on this node
  (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 session audits.

Live Preview

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

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

Worked Walkthrough — List Your Sessions

You are connected with mongosh. Goal: see your logical sessions on this node, newest activity first.

1. db.getSiblingDB("admin")
2. $listLocalSessions {}     ← first stage
3. Defaults: allUsers false  → only your sessions
4. $project id, user, lastUse
5. 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 and inspect live session metadata (not a seeded collection). Results depend on who is connected to your server.

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

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

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

db.getSiblingDB("admin").aggregate([
  { $listLocalSessions: {} },
  {
    $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([
  { $listLocalSessions: { 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
// Still THIS node only — check each replica set member separately

{
  _id: { user: "appUser", db: "admin" },
  sessionCount: 12,
  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