@aidra/pmx-io 9.18.0 → 9.20.0

package/index.d.ts

@@ -142,6 +142,12 @@ export interface IOConfig {
     proxy?: string
   }
   tracing?: boolean | TracingConfig
+  /**
+   * count every call this process makes or receives (HTTP, databases) per minute for prodman's
+   * Service Map, with tracing on or off (83 CMP-001); default env PMX_IO_SERVICE_MAP, else true.
+   * prodman's setting (`service_map`) takes precedence.
+   */
+  serviceMap?: boolean
   /** report exceptions that frameworks turn into ≥ 500 responses (80 NIO-223), default true */
   httpErrors?: boolean
   /** instrument Node descendants and worker threads through this process (80 NIO-290), default true */

package/lib/activate.js

@@ -347,11 +347,13 @@ function entryIsEsm (argv, execArgv) {
 
 /**
  * NIO-085 / NIO-210: register the module customization hooks that wrap ES-module libraries,
- * only when tracing is enabled (called from preload.mjs / standalone.mjs).
+ * only when tracing or the call map (83 CMP-003) is enabled (called from preload.mjs /
+ * standalone.mjs).
  */
 function registerEsmHooks () {
   const s = state()
-  if (!s.active || s.esmHooked || !s.instance || !s.instance._tracingEnabled()) return false
+  if (!s.active || s.esmHooked || !s.instance) return false
+  if (!s.instance._tracingEnabled() && !(typeof s.instance._serviceMapEnabled === 'function' && s.instance._serviceMapEnabled())) return false
   let mod
   try {
     mod = require('module')

package/lib/bun.js

@@ -37,9 +37,20 @@ function serverState (protocol, req, route) {
 function wrapHandler (fn, protocol, route) {
   const w = function (req) {
     const c = inbound.consumers
-    if (!c.metrics && !c.tracing && !c.errors) return fn.apply(this, arguments)
+    if (!c.metrics && !c.tracing && !c.errors && !c.callmap) return fn.apply(this, arguments)
     const doneMetric = c.metrics && c.metrics.start ? c.metrics.start(protocol) : null
     const st = serverState(protocol, req, route)
+    const cm = c.callmap
+    let key = null
+    if (cm) {
+      // 83 CMP-011: the server's port and the client's address (Bun.serve passes the server)
+      try {
+        const server = arguments[1]
+        const ip = server && typeof server.requestIP === 'function' ? server.requestIP(req) : null
+        key = cm.httpInKeyOf(server && typeof server.port === 'number' ? server.port : null, ip && ip.address)
+      } catch (_) {}
+    }
+    const t0 = key !== null ? cm.now() : 0
     if (c.tracing) {
       try {
         const host = (req.headers && req.headers.get && req.headers.get('host')) || 'localhost'
@@ -84,6 +95,7 @@ function wrapHandler (fn, protocol, route) {
           c.tracing.finishServerSpan(st.span, status, st.route, st.error)
         } catch (_) {}
       }
+      if (key !== null) cm.record(key, cm.now() - t0, status >= 500 || Boolean(st.error))
     }
     let r
     try {

package/lib/callmap.js

@@ -0,0 +1,427 @@
+// Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
+'use strict'
+
+// The call map (83-call-map.md): every outbound HTTP request, inbound HTTP request and database
+// operation is counted per UTC minute and key — whether tracing is on or not (CMP-002) — and the
+// finished minute is sent as one `service:calls` message (CMP-020…022).
+//
+// Recording (CMP-004) allocates nothing once a key exists: the hooks resolve a Key object (cached
+// in nested Maps by the strings and numbers they already hold, or on the connection / socket),
+// and the Key remembers its record for the current minute. Records of a minute live in a bucket
+// keyed by the key's identity string, so two Key objects with the same fields share one record.
+
+const MINUTE = 60000
+const MAX_KEYS = 200 // CMP-014
+const BUCKETS = 74 // CMP-015
+const MAX_BYTES = 256 * 1024 // CMP-022
+const MAX_DELAY_MS = 5000 // CMP-020
+const KEY_CACHE_MAX = 5000 // Key objects kept for lookups (a bound, not a protocol limit)
+const NAME_MAX = 100
+const OTHER = '(other)'
+// {"type":"service:calls","data":{"v":1,"minute":1234567890123,"calls":[]}}
+const ENVELOPE_BYTES = 80
+
+const FIELDS = {
+  http_out: ['host', 'port', 'scheme'],
+  http_in: ['local_port', 'peer'],
+  db: ['system', 'host', 'port', 'name']
+}
+const NUMERIC = new Set(['port', 'local_port'])
+
+// `on` is the one flag the hooks check (CMP-003 / ITG-007)
+const state = { on: false }
+// the message size limit (changed by the tests only)
+const limits = { maxBytes: MAX_BYTES }
+let send = null // (data) => void
+let epoch = 0 // raised by every flush of the current minute: Keys re-resolve their record
+const buckets = new Map() // minute → { minute, recs: Map<id, rec>, count, overflow: {kind: rec} }
+let timer = null
+let timerMinute = -1
+let exitHooked = false
+let keyCount = 0
+
+let perf = null
+/** Monotonic milliseconds (resolved on first use, NIO-024). */
+function now () {
+  if (perf === null) perf = globalThis.performance || require('perf_hooks').performance
+  return perf.now()
+}
+
+/** CMP-015: 0 for < 1 ms, else min(73, 1 + floor(4 · log2(ms))). */
+function bucketOf (ms) {
+  if (!(ms >= 1)) return 0
+  const b = 1 + Math.floor(4 * Math.log2(ms))
+  return b > BUCKETS - 1 ? BUCKETS - 1 : b
+}
+
+class Key {
+  constructor (kind, fields) {
+    this.kind = kind
+    this.fields = fields
+    let id = kind
+    for (const f of FIELDS[kind]) id += '\u0000' + (fields[f] === null ? '' : String(fields[f]))
+    this.id = id
+    this.minute = -1
+    this.epoch = -1
+    this.rec = null
+  }
+}
+
+// ------------------------------------------------------------------------------ key caches
+
+let outKeys = new Map() // scheme → host → authority → Key (ClientRequest)
+let originKeys = new Map() // origin → Key (fetch)
+let inKeys = new Map() // local port → peer → Key
+let dbKeys = new Map() // system → host → port → name → Key
+let byId = new Map() // id → Key (shares Keys between the caches)
+
+function sharedKey (kind, fields) {
+  if (keyCount >= KEY_CACHE_MAX) {
+    // bounded: dropped Keys are made again (their records are found by id)
+    outKeys = new Map()
+    originKeys = new Map()
+    inKeys = new Map()
+    dbKeys = new Map()
+    byId = new Map()
+    keyCount = 0
+  }
+  const k = new Key(kind, fields)
+  const prev = byId.get(k.id)
+  if (prev) return prev
+  byId.set(k.id, k)
+  keyCount++
+  return k
+}
+
+function sub (map, k) {
+  let m = map.get(k)
+  if (m === undefined) {
+    m = new Map()
+    map.set(k, m)
+  }
+  return m
+}
+
+/** CMP-010 host: lowercased, no trailing dot, no userinfo, IPv6 without brackets. */
+function normHost (host) {
+  let h = String(host || '')
+  const at = h.lastIndexOf('@')
+  if (at !== -1) h = h.slice(at + 1)
+  if (h.startsWith('[') && h.endsWith(']')) h = h.slice(1, -1)
+  if (h.endsWith('.')) h = h.slice(0, -1)
+  return h.toLowerCase() || 'localhost'
+}
+
+function defaultPort (scheme) {
+  return scheme === 'https' ? 443 : 80
+}
+
+/**
+ * CMP-010 for a ClientRequest: `protocol` ('http:' | 'https:'), `host` (req.host, the host the
+ * request connects to) and the Host header (its port, else the scheme's default).
+ */
+function httpOutKey (protocol, host, authority) {
+  const byHost = sub(outKeys, protocol)
+  const byAuth = sub(byHost, host)
+  const a = typeof authority === 'string' ? authority : ''
+  let k = byAuth.get(a)
+  if (k !== undefined) return k
+  const scheme = protocol === 'https:' ? 'https' : 'http'
+  let port = null
+  const m = /:(\d+)$/.exec(a)
+  if (m && !/^\[[^\]]*$/.test(a.slice(0, m.index))) port = Number(m[1])
+  k = sharedKey('http_out', { host: normHost(host), port: port || defaultPort(scheme), scheme })
+  byAuth.set(a, k)
+  return k
+}
+
+/** CMP-010 for fetch: the request's origin (`http://host:port`). */
+function originKey (origin) {
+  let k = originKeys.get(origin)
+  if (k !== undefined) return k
+  let scheme = 'http'
+  let host = 'localhost'
+  let port = null
+  try {
+    const u = new URL(String(origin))
+    scheme = u.protocol === 'https:' ? 'https' : 'http'
+    host = u.hostname
+    port = u.port ? Number(u.port) : null
+  } catch (_) {}
+  k = sharedKey('http_out', { host: normHost(host), port: port || defaultPort(scheme), scheme })
+  originKeys.set(origin, k)
+  return k
+}
+
+/** CMP-010 for a URL (Bun's fetch): parsed every call. */
+function urlKey (url) {
+  try {
+    const u = url instanceof URL ? url : new URL(String(url))
+    return originKey(u.origin)
+  } catch (_) {
+    return originKey('')
+  }
+}
+
+const SOCKET_KEY = Symbol('pmx-callmap-in')
+
+/** CMP-011: (local port, peer) of the request's socket, cached on the socket. */
+function httpInKey (socket) {
+  if (!socket) return inKey(null, null)
+  let k
+  try {
+    k = socket[SOCKET_KEY]
+    if (k !== undefined) return k
+    k = httpInKeyOf(socket.localPort, socket.remoteAddress)
+    socket[SOCKET_KEY] = k
+  } catch (_) {
+    k = inKey(null, null)
+  }
+  return k
+}
+
+/** CMP-011 from a local port and a peer address (IPv4-mapped IPv6 as IPv4); null when unknown. */
+function httpInKeyOf (localPort, address) {
+  const lp = typeof localPort === 'number' && localPort > 0 ? localPort : null
+  let peer = typeof address === 'string' && address ? address : null
+  if (peer !== null && peer.startsWith('::ffff:') && peer.indexOf('.') !== -1) peer = peer.slice(7)
+  return inKey(lp, peer)
+}
+
+function inKey (localPort, peer) {
+  const m = sub(inKeys, localPort)
+  let k = m.get(peer)
+  if (k === undefined) {
+    k = sharedKey('http_in', { local_port: localPort, peer })
+    m.set(peer, k)
+  }
+  return k
+}
+
+/** CMP-012: (system, host, port, name); port a number or null, name ≤ 100 characters or null. */
+function dbKey (system, host, port, name) {
+  const m = sub(sub(sub(dbKeys, system), host), port)
+  let k = m.get(name)
+  if (k === undefined) {
+    const n = name === null || name === undefined || name === '' ? null : String(name).slice(0, NAME_MAX)
+    k = sharedKey('db', { system: String(system || 'other'), host: host === null || host === undefined ? null : String(host), port: port === null || port === undefined || !Number.isFinite(Number(port)) ? null : Number(port), name: n })
+    m.set(name, k)
+  }
+  return k
+}
+
+/** A db Key from an integration's span attributes (server.address/port or net.peer.*, db.name). */
+function dbKeyFromTags (tags) {
+  const system = tags['db.system']
+  const host = tags['server.address'] !== undefined ? tags['server.address'] : tags['net.peer.name']
+  const rawPort = tags['server.port'] !== undefined ? tags['server.port'] : tags['net.peer.port']
+  const port = rawPort === undefined || rawPort === null || rawPort === '' ? null : Number(rawPort)
+  const name = system === 'redis' ? null : (tags['db.name'] !== undefined ? tags['db.name'] : tags['db.namespace'])
+  return dbKey(system, host === undefined ? null : host, Number.isFinite(port) ? port : null, name === undefined ? null : name)
+}
+
+// ------------------------------------------------------------------------------ recording
+
+function newRec (kind, fields) {
+  return { kind, fields, calls: 0, errors: 0, sum: 0, hist: new Uint32Array(BUCKETS) }
+}
+
+function overflowFields (kind) {
+  const o = {}
+  for (const f of FIELDS[kind]) o[f] = NUMERIC.has(f) ? null : OTHER
+  return o
+}
+
+function recFor (key, minute) {
+  let b = buckets.get(minute)
+  if (b === undefined) {
+    b = { minute, recs: new Map(), count: 0, overflow: {} }
+    buckets.set(minute, b)
+    schedule(minute)
+  }
+  let rec = b.recs.get(key.id)
+  if (rec !== undefined) return rec
+  if (b.count >= MAX_KEYS) {
+    // CMP-014: further keys of this minute go to the kind's overflow record
+    rec = b.overflow[key.kind]
+    if (rec === undefined) rec = b.overflow[key.kind] = newRec(key.kind, overflowFields(key.kind))
+    return rec
+  }
+  rec = newRec(key.kind, key.fields)
+  b.recs.set(key.id, rec)
+  b.count++
+  return rec
+}
+
+/** Count one call of `key` that took `ms` milliseconds (CMP-010…015). */
+function record (key, ms, error) {
+  if (!state.on || key === null || key === undefined) return
+  const t = Date.now()
+  const minute = t - (t % MINUTE)
+  let rec = key.rec
+  if (key.minute !== minute || key.epoch !== epoch) {
+    rec = recFor(key, minute)
+    key.rec = rec
+    key.minute = minute
+    key.epoch = epoch
+  }
+  rec.calls++
+  if (error) rec.errors++
+  if (ms > 0) rec.sum += ms
+  else ms = 0
+  rec.hist[bucketOf(ms)]++
+}
+
+// ------------------------------------------------------------------------------ sending
+
+function encode (rec) {
+  const o = { kind: rec.kind }
+  for (const f of FIELDS[rec.kind]) o[f] = rec.fields[f]
+  o.calls = rec.calls
+  o.errors = rec.errors
+  o.duration_sum_ms = Math.round(rec.sum * 1000) / 1000
+  let n = BUCKETS
+  while (n > 0 && rec.hist[n - 1] === 0) n-- // CMP-015: trailing zero buckets omitted
+  o.hist = Array.from(rec.hist.subarray(0, n))
+  return o
+}
+
+/** CMP-021/022: the bucket as one or more `service:calls` messages of at most 256 KiB. */
+function sendBucket (b) {
+  const all = Array.from(b.recs.values())
+  for (const k of Object.keys(b.overflow)) all.push(b.overflow[k])
+  if (all.length === 0 || !send) return
+  let calls = []
+  let bytes = ENVELOPE_BYTES
+  const out = () => {
+    if (calls.length === 0) return
+    try {
+      send({ v: 1, minute: b.minute, calls })
+    } catch (_) {}
+    calls = []
+    bytes = ENVELOPE_BYTES
+  }
+  for (const rec of all) {
+    if (rec.calls === 0) continue
+    const o = encode(rec)
+    const size = Buffer.byteLength(JSON.stringify(o)) + 1
+    if (calls.length && bytes + size > limits.maxBytes) out()
+    calls.push(o)
+    bytes += size
+  }
+  out()
+}
+
+/** Send and drop the finished minutes (all minutes when `all`, CMP-020 shutdown flush). */
+function flush (all) {
+  const t = Date.now()
+  const current = t - (t % MINUTE)
+  for (const [minute, b] of Array.from(buckets)) {
+    if (!all && minute >= current) continue
+    buckets.delete(minute)
+    sendBucket(b)
+  }
+  if (all) epoch++
+  if (buckets.size === 0) clearTimer()
+  else if (timer === null) schedule(Math.min.apply(null, Array.from(buckets.keys())))
+}
+
+function clearTimer () {
+  if (timer !== null) clearTimeout(timer)
+  timer = null
+  timerMinute = -1
+}
+
+/** CMP-020: shortly after `minute` ends, with a random delay of 0–5 s. */
+function schedule (minute) {
+  if (timer !== null && timerMinute <= minute) return
+  clearTimer()
+  const delay = Math.max(0, minute + MINUTE - Date.now()) + Math.floor(Math.random() * MAX_DELAY_MS)
+  timerMinute = minute
+  timer = setTimeout(() => {
+    timer = null
+    timerMinute = -1
+    flush(false)
+  }, delay)
+  if (timer.unref) timer.unref()
+}
+
+function onExit () {
+  try {
+    flush(true)
+  } catch (_) {}
+}
+
+// ------------------------------------------------------------------------------ switch
+
+/**
+ * Switch the call map on or off (CMP-001: at once). `sender(data)` sends one message's data. On
+ * switch-off what was recorded is sent now.
+ */
+function setEnabled (on, sender) {
+  if (sender !== undefined) send = sender
+  if (on) {
+    state.on = true
+    if (!exitHooked) {
+      exitHooked = true
+      process.on('exit', onExit)
+    }
+    return
+  }
+  if (state.on) flush(true)
+  state.on = false
+}
+
+/** Stop and drop everything (destroy()); what was recorded is sent first. */
+function stop () {
+  if (state.on) flush(true)
+  state.on = false
+  send = null
+  buckets.clear()
+  clearTimer()
+  if (exitHooked) {
+    exitHooked = false
+    process.removeListener('exit', onExit)
+  }
+}
+
+/** CMP-001: PMX_IO_SERVICE_MAP as a boolean, or undefined (unset or not recognised). */
+function envValue (env) {
+  const raw = (env || process.env).PMX_IO_SERVICE_MAP
+  if (typeof raw !== 'string') return undefined
+  const v = raw.trim().toLowerCase()
+  if (v === '0' || v === 'false' || v === 'off') return false
+  if (v === '1' || v === 'true' || v === 'on') return true
+  return undefined
+}
+
+/** CMP-001: { value, source } — prodman layer > init({ serviceMap }) > env > default true. */
+function resolve (layer, appValue, env) {
+  if (layer && typeof layer.service_map === 'boolean') return { value: layer.service_map, source: 'prodman' }
+  if (typeof appValue === 'boolean') return { value: appValue, source: 'config' }
+  const e = envValue(env)
+  if (e !== undefined) return { value: e, source: 'env' }
+  return { value: true, source: 'default' }
+}
+
+module.exports = {
+  state,
+  now,
+  record,
+  bucketOf,
+  httpOutKey,
+  originKey,
+  urlKey,
+  httpInKey,
+  httpInKeyOf,
+  dbKey,
+  dbKeyFromTags,
+  flush,
+  setEnabled,
+  stop,
+  resolve,
+  envValue,
+  limits,
+  MAX_KEYS,
+  MAX_BYTES
+}

package/lib/esm-hooks.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) 2026 Mike Warriner. All rights reserved. Proprietary — see LICENSE.
 
-// Module customization hooks (80 NIO-085, NIO-210), registered by preload.mjs only when tracing is
-// enabled at spawn: `module.registerHooks` (in-thread, Node ≥ 22.15 / ≥ 23.5) or `module.register`
-// (off-thread, Node ≥ 18.19 / ≥ 20.6). For an ES-module file of a target library the `load` hook
+// Module customization hooks (80 NIO-085, NIO-210), registered by preload.mjs only when tracing or
+// the call map (83 CMP-003) is enabled at spawn: `module.registerHooks` (in-thread, Node ≥ 22.15 /
+// ≥ 23.5) or `module.register` (off-thread, Node ≥ 18.19 / ≥ 20.6). For an ES-module file of a target library the `load` hook
 // returns a wrapper module instead:
 //
 //   import * as ns from '<url>?pmx-io-orig'

package/lib/inbound.js

@@ -5,7 +5,9 @@
 // the framework exception reports (NIO-223). One process-wide interception (hooks.js) calls the
 // active consumers; a per-request state object travels on the request and the response.
 //
-// The state: { protocol, req, res, span, store, route, routeFn, error, info, start, done }.
+// The call map (83 CMP-011, consumer `callmap`) counts every request through the same state.
+//
+// The state: { protocol, req, res, span, store, route, routeFn, error, info, key, t0, done }.
 // Framework integrations find it with stateOf(req|res) and set `routeFn` (read when the
 // response starts, NIO-221) and `error`/`info` (NIO-223).
 
@@ -14,7 +16,7 @@ const context = require('./tracing/context')
 
 const STATE = Symbol.for('@pmx/io:request-state')
 
-const consumers = { metrics: null, tracing: null, errors: null }
+const consumers = { metrics: null, tracing: null, errors: null, callmap: null }
 let installedWriteHead = false
 
 function stateOf (obj) {
@@ -29,7 +31,7 @@ function attach (obj, st) {
 }
 
 function anyConsumer () {
-  return Boolean(consumers.metrics || consumers.tracing || consumers.errors)
+  return Boolean(consumers.metrics || consumers.tracing || consumers.errors || consumers.callmap)
 }
 
 /** Read the framework route when the response starts (NIO-221). */
@@ -121,6 +123,11 @@ function finish (st, aborted) {
       consumers.tracing.endServer(st, status, aborted)
     } catch (_) {}
   }
+  const cm = consumers.callmap
+  if (cm !== null && st.key) {
+    // CMP-011: an error is a status ≥ 500 or an exception that ended the request
+    cm.record(st.key, cm.now() - st.t0, status >= 500 || Boolean(st.error))
+  }
 }
 
 /** The process-wide request handler (hooks.js). Returns the store to run listeners in. */
@@ -131,11 +138,18 @@ function onRequest (protocol, req, res) {
       m.request(protocol, req, res)
     } catch (_) {}
   }
-  if (!consumers.tracing && !consumers.errors) return undefined
+  const cm = consumers.callmap
+  if (!consumers.tracing && !consumers.errors && cm === null) return undefined
   if (!res || typeof res.once !== 'function') return undefined
   const prev = req[STATE]
   if (prev && !prev.done) return prev.store // the same request seen twice (nested servers)
-  const st = { protocol, req, res, span: null, store: undefined, route: undefined, routeFn: null, error: null, info: null, done: false }
+  let key = null
+  if (cm !== null) {
+    try {
+      key = cm.httpInKey(req.socket)
+    } catch (_) {}
+  }
+  const st = { protocol, req, res, span: null, store: undefined, route: undefined, routeFn: null, error: null, info: null, key, t0: key !== null ? cm.now() : 0, done: false }
   attach(req, st)
   attach(res, st)
   if (consumers.tracing) {

package/lib/itg/common.js

@@ -4,15 +4,18 @@
 // Common rules of the database and broker integrations (82 §1, §2, §4; the Node counterpart of
 // pmx-io's _msg.py / _db.py helpers): switches, CLIENT/PRODUCER/CONSUMER/receive span creation
 // and parenting, error marking, promise/callback completion, header carriers, links for batches,
-// iterator-style consumer spans and the exit flush of open iterator spans. The per-library modules
+// iterator-style consumer spans and the exit flush of open iterator spans, and the call map's
+// records of database operations (83 CMP-003, CMP-012). The per-library modules
 // (lib/itg/<library>.js) only map library calls onto these helpers.
 //
 // Everything here is defensive: a failure in pmx code is logged under `axm:tracing` and never
-// reaches the app (ITG-003). Loaded only when an instrumented library is loaded with tracing on.
+// reaches the app (ITG-003). Loaded only when an instrumented library is loaded with tracing or the
+// call map on.
 
 const ctx = require('../tracing/context')
 const w3c = require('../tracing/w3c')
 const debug = require('../debug')('axm:tracing')
+const callmap = require('../callmap')
 
 const MODULES = Symbol.for('@pmx/io:modules')
 const ERROR_MAX = 500
@@ -45,6 +48,86 @@ function msgTracer () {
   return t && t.messaging ? t : null
 }
 
+// ---------------------------------------------------------------------------------------------
+// call map (83 CMP-003, CMP-012)
+
+const mapState = callmap.state
+
+/** True while the call map is on (a database wrapper then records every operation). */
+function mapOn () {
+  return mapState.on
+}
+
+const NO_ATTRS = Object.freeze({})
+
+/**
+ * One database operation for the call map, used in place of its span (or of no span: tracing
+ * off, its switch off, or no parent span, ITG-010): the span's methods are forwarded, an ERROR
+ * status marks the call failed (CMP-012: the operation raised or rejected) and end() records it.
+ */
+class Call {
+  constructor (span, key) {
+    this.span = span
+    this.key = key
+    this.t0 = callmap.now()
+    this.failed = false
+    this.ended = false
+  }
+
+  get attributes () {
+    return this.span ? this.span.attributes : NO_ATTRS
+  }
+
+  setAttribute (k, v) {
+    if (this.span) this.span.setAttribute(k, v)
+    return this
+  }
+
+  setStatus (code, message) {
+    if (code === 'ERROR') this.failed = true
+    if (this.span) this.span.setStatus(code, message)
+    return this
+  }
+
+  updateName (name) {
+    if (this.span) this.span.updateName(name)
+    return this
+  }
+
+  end () {
+    if (this.ended) return
+    this.ended = true
+    try {
+      callmap.record(this.key, callmap.now() - this.t0, this.failed)
+    } catch (_) {}
+    if (this.span) this.span.end()
+  }
+}
+
+/** The span to finish for an operation: `span` itself with the call map off, else a Call (or null). */
+function dbCall (span, key) {
+  if (!mapState.on || key === null || key === undefined) return span
+  return new Call(span, key)
+}
+
+const KEYS = new WeakMap()
+
+/** The call map key of an operation on `owner` (a connection or client), cached on it; null when off. */
+function dbKeyOf (owner, tagsOf) {
+  if (!mapState.on) return null
+  const obj = owner !== null && (typeof owner === 'object' || typeof owner === 'function')
+  let k = obj ? KEYS.get(owner) : undefined
+  if (k !== undefined) return k
+  try {
+    k = callmap.dbKeyFromTags(tagsOf(owner))
+  } catch (err) {
+    debug('call map key failed: %s', err && err.message)
+    return null
+  }
+  if (obj) KEYS.set(owner, k)
+  return k
+}
+
 /** The current span (a span of this process or, in bridge mode, of the app's SDK), or undefined. */
 function currentSpan () {
   const s = ctx.current()
@@ -614,6 +697,10 @@ function versionOf (dir) {
 }
 
 module.exports = {
+  mapOn,
+  dbCall,
+  dbKeyOf,
+  Call,
   tracer,
   dbTracer,
   msgTracer,