@toa.io/storages.mongodb 1.0.0-alpha.243 → 1.0.0-alpha.246

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/storages.mongodb",
-  "version": "1.0.0-alpha.243",
+  "version": "1.0.0-alpha.246",
   "description": "Toa MongoDB Storage Connector",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,12 +20,12 @@
   },
   "dependencies": {
     "@toa.io/conveyor": "1.0.0-alpha.225",
-    "@toa.io/core": "1.0.0-alpha.243",
+    "@toa.io/core": "1.0.0-alpha.246",
     "@toa.io/generic": "1.0.0-alpha.225",
-    "@toa.io/pointer": "1.0.0-alpha.225",
+    "@toa.io/pointer": "1.0.0-alpha.246",
     "mongodb": "7.2.0",
-    "openspan": "1.0.0-alpha.173",
+    "openspan": "1.0.0-alpha.246",
     "saslprep": "1.0.3"
   },
-  "gitHead": "743e8060d35ca750f70487c04aef9698591c5edd"
+  "gitHead": "d6ee2a7246c64a44c50c28fadcfd1e27aaf137cb"
 }

package/readme.md

@@ -0,0 +1,16 @@
+# MongoDB Storage
+
+## Tracing
+
+Commands are recorded as `client` spans within the trace of the current invocation,
+using the [driver command monitoring events](https://www.mongodb.com/docs/drivers/node/current/monitoring/command-monitoring/).
+
+Spans are named `{command} {collection}` and carry `db.*` attributes following the
+[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/mongodb/):
+`db.system`, `db.namespace`, `db.collection.name`, `db.operation.name`.
+
+Commands executed outside of a sampled trace context (e.g. index management on startup)
+and internal driver commands (`hello`, `ping`, authentication) are not recorded.
+
+Monitoring is client-side only and does not affect the MongoDB server. Span recording
+adds no waiting to the query path: exporting is buffered and happens in the background.

package/src/client.js

@@ -11,6 +11,7 @@ const { Connector } = require('@toa.io/core')
 const { resolve } = require('@toa.io/pointer')
 const { ID } = require('./deployment')
 const { MongoClient } = require('mongodb')
+const { monitor } = require('./monitoring')
 
 /**
  * @type {Record<string, Promise<Instance>>}
@@ -112,6 +113,8 @@ class Client extends Connector {
     const client = new MongoClient(urls.join(','), OPTIONS)
     const hosts = urls.map((str) => new URL(str).host)
 
+    monitor(client)
+
     console.info('Connecting to MongoDB', { address: hosts.join(', ') })
 
     await client.connect()
@@ -156,7 +159,8 @@ function getKey (db, urls) {
 }
 
 const OPTIONS = {
-  ignoreUndefined: true
+  ignoreUndefined: true,
+  monitorCommands: true
 }
 
 const ALREADY_EXISTS = 48

package/src/monitoring.js

@@ -0,0 +1,87 @@
+'use strict'
+
+const { create, current, record } = require('openspan')
+
+/**
+ * Records MongoDB commands as client spans using the driver command monitoring events.
+ * Requires the client to be created with `monitorCommands: true`.
+ *
+ * Commands executed outside of a sampled trace context are not recorded.
+ *
+ * @param {import('mongodb').MongoClient} client
+ */
+function monitor (client) {
+  /** @type {Map<number, { context: object, time: number, attributes: object }>} */
+  const pending = new Map()
+
+  client.on('commandStarted', (event) => {
+    if (IGNORE.has(event.commandName))
+      return
+
+    const parent = current()
+
+    if (parent === undefined || !parent.sampled)
+      return
+
+    if (pending.size >= CAPACITY) // should never happen
+      pending.delete(pending.keys().next().value)
+
+    // https://opentelemetry.io/docs/specs/semconv/database/mongodb/
+    const attributes = {
+      'db.system': 'mongodb',
+      'db.namespace': event.databaseName,
+      'db.operation.name': event.commandName
+    }
+
+    const collection = event.command?.[event.commandName]
+
+    if (typeof collection === 'string')
+      attributes['db.collection.name'] = collection
+
+    pending.set(event.requestId, {
+      context: create(parent),
+      time: Date.now(),
+      attributes
+    })
+  })
+
+  client.on('commandSucceeded', (event) => complete(event))
+  client.on('commandFailed', (event) => complete(event, 'error'))
+
+  function complete (event, status) {
+    const started = pending.get(event.requestId)
+
+    if (started === undefined)
+      return
+
+    pending.delete(event.requestId)
+
+    const collection = started.attributes['db.collection.name']
+
+    const span = {
+      name: collection === undefined
+        ? event.commandName
+        : `${event.commandName} ${collection}`,
+      traceId: started.context.traceId,
+      spanId: started.context.spanId,
+      parentId: started.context.parentId,
+      kind: 'client',
+      time: started.time,
+      duration: event.duration,
+      attributes: started.attributes,
+      service: started.context.service
+    }
+
+    if (status !== undefined)
+      span.status = status
+
+    record(span)
+  }
+}
+
+// internal commands, including authentication and connection management
+const IGNORE = new Set(['hello', 'ismaster', 'ping', 'endSessions', 'saslStart', 'saslContinue'])
+
+const CAPACITY = 1024
+
+exports.monitor = monitor

package/test/monitoring.test.js

@@ -0,0 +1,99 @@
+'use strict'
+
+const { EventEmitter } = require('node:events')
+const { create, exporting, run, traces } = require('openspan')
+const { monitor } = require('../src/monitoring')
+
+let client
+let spans
+
+beforeEach(() => {
+  client = new EventEmitter()
+  spans = []
+
+  exporting([{ export: (span) => spans.push(span) }])
+  monitor(client)
+})
+
+afterEach(() => {
+  traces()
+})
+
+const started = {
+  requestId: 1,
+  commandName: 'find',
+  databaseName: 'toa-dev',
+  command: { find: 'pots', filter: {} }
+}
+
+const succeeded = { requestId: 1, commandName: 'find', duration: 1.5 }
+const failed = { requestId: 1, commandName: 'find', duration: 0.5, failure: 'boom' }
+
+it('should record a command as a client span', () => {
+  const context = create()
+
+  run(context, () => client.emit('commandStarted', started))
+  client.emit('commandSucceeded', succeeded)
+
+  expect(spans).toHaveLength(1)
+
+  expect(spans[0]).toMatchObject({
+    name: 'find pots',
+    traceId: context.traceId,
+    parentId: context.spanId,
+    kind: 'client',
+    duration: 1.5,
+    attributes: {
+      'db.system': 'mongodb',
+      'db.namespace': 'toa-dev',
+      'db.operation.name': 'find',
+      'db.collection.name': 'pots'
+    }
+  })
+
+  expect(spans[0].status).toBeUndefined()
+})
+
+it('should record failed commands with error status', () => {
+  run(create(), () => client.emit('commandStarted', started))
+  client.emit('commandFailed', failed)
+
+  expect(spans).toHaveLength(1)
+  expect(spans[0].status).toBe('error')
+})
+
+it('should not record commands outside of a trace context', () => {
+  client.emit('commandStarted', started)
+  client.emit('commandSucceeded', succeeded)
+
+  expect(spans).toHaveLength(0)
+})
+
+it('should not record commands of unsampled traces', () => {
+  const context = { ...create(), sampled: false }
+
+  run(context, () => client.emit('commandStarted', started))
+  client.emit('commandSucceeded', succeeded)
+
+  expect(spans).toHaveLength(0)
+})
+
+it('should ignore internal commands', () => {
+  run(create(), () => {
+    client.emit('commandStarted', { ...started, commandName: 'hello', command: { hello: 1 } })
+  })
+
+  client.emit('commandSucceeded', { ...succeeded, commandName: 'hello' })
+
+  expect(spans).toHaveLength(0)
+})
+
+it('should name spans without a collection by the command', () => {
+  const start = { ...started, commandName: 'listIndexes', command: { listIndexes: 1 } }
+
+  run(create(), () => client.emit('commandStarted', start))
+  client.emit('commandSucceeded', { ...succeeded, commandName: 'listIndexes' })
+
+  expect(spans).toHaveLength(1)
+  expect(spans[0].name).toBe('listIndexes')
+})