Support for Prisma client library (#5605)

Next to the prisma instrumentation this is also improving the way
externals is able to install additional dependencies in our test setup.
The dependency version may now be pinned to the main dependency
version to align these by specifying the main dependency as `dep`.

---------

Co-authored-by: Thomas Hunter II <tlhunter@datadog.com>
Co-authored-by: Crystal Magloire <crys.magloire@gmail.com>
Co-authored-by: Ruben Bridgewater <ruben.bridgewater@datadoghq.com>
Co-authored-by: Roch Devost <roch.devost@datadoghq.com>

Author: 5 people

.github/workflows/apm-integrations.yml

@@ -825,6 +825,21 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: ./.github/actions/plugins/test
+  prisma:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:9.5
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+    env:
+      PLUGINS: prisma
+      SERVICES: prisma
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: ./.github/actions/plugins/test
 
   protobufjs:
     runs-on: ubuntu-latest

docs/API.md

@@ -90,6 +90,7 @@ tracer.use('pg', {
 <h5 id="pg"></h5>
 <h5 id="pg-tags"></h5>
 <h5 id="pg-config"></h5>
+<h5 id="prisma"></h5>
 <h5 id="protobufjs"></h5>
 <h5 id="redis"></h5>
 <h5 id="redis-tags"></h5>
@@ -147,6 +148,7 @@ tracer.use('pg', {
 * [oracledb](./interfaces/export_.plugins.oracledb.html)
 * [pino](./interfaces/export_.plugins.pino.html)
 * [pg](./interfaces/export_.plugins.pg.html)
+* [primsa](./interfaces/export_.plugins.prisma.html)
 * [promise](./interfaces/export_.plugins.promise.html)
 * [promise-js](./interfaces/export_.plugins.promise_js.html)
 * [protobufjs](./interfaces/export_.plugins.protobufjs.html)

docs/add-redirects.sh

@@ -55,6 +55,7 @@ declare -a plugins=(
   "oracledb"
   "pino"
   "pg"
+  "prisma"
   "promise"
   "promise_js"
   "protobufjs"

docs/test.ts

@@ -388,6 +388,7 @@ tracer.use('playwright');
 tracer.use('pg');
 tracer.use('pg', { service: params => `${params.host}-${params.database}` });
 tracer.use('pino');
+tracer.use('prisma');
 tracer.use('protobufjs');
 tracer.use('redis');
 tracer.use('redis', redisOptions);

index.d.ts

@@ -212,6 +212,7 @@ interface Plugins {
   "playwright": tracer.plugins.playwright;
   "pg": tracer.plugins.pg;
   "pino": tracer.plugins.pino;
+  "prisma": tracer.plugins.prisma;
   "protobufjs": tracer.plugins.protobufjs;
   "redis": tracer.plugins.redis;
   "restify": tracer.plugins.restify;
@@ -1271,6 +1272,15 @@ declare namespace tracer {
       meta?: boolean;
     }
 
+    /** @hidden */
+    interface Prisma extends Instrumentation {}
+
+    /** @hidden */
+    interface PrismaClient extends Prisma {}
+
+    /** @hidden */
+    interface PrismaEngine extends Prisma {}
+
     /**
      * This plugin automatically instruments the
      * [aerospike](https://github.com/aerospike/aerospike-client-nodejs) for module versions >= v3.16.2.
@@ -1934,6 +1944,23 @@ declare namespace tracer {
      * on the tracer.
      */
     interface pino extends Integration {}
+
+    /**
+     * This plugin automatically instruments the
+     * [@prisma/client](https://www.prisma.io/docs/orm/prisma-client) module.
+     */
+    interface prisma extends PrismaClient, PrismaEngine {
+      /**
+       * Configuration for prisma client.
+       */
+      client?: PrismaClient | boolean,
+
+      /**
+       * Configuration for Prisma engine.
+       */
+      engine?: PrismaEngine | boolean
+    }
+
     /**
      * This plugin automatically patches the [protobufjs](https://protobufjs.github.io/protobuf.js/)
      * to collect protobuf message schemas when Datastreams Monitoring is enabled.

packages/datadog-instrumentations/src/helpers/hooks.js

@@ -24,6 +24,7 @@ module.exports = {
   '@node-redis/client': () => require('../redis'),
   '@opensearch-project/opensearch': () => require('../opensearch'),
   '@opentelemetry/sdk-trace-node': () => require('../otel-sdk-trace'),
+  '@prisma/client': () => require('../prisma'),
   '@redis/client': () => require('../redis'),
   '@smithy/smithy-client': () => require('../aws-sdk'),
   '@vitest/runner': { esmFirst: true, fn: () => require('../vitest') },

packages/datadog-instrumentations/src/prisma.js

@@ -0,0 +1,116 @@
+'use strict'
+
+const {
+  channel,
+  addHook
+} = require('./helpers/instrument')
+
+const prismaEngineStart = channel('apm:prisma:engine:start')
+const tracingChannel = require('dc-polyfill').tracingChannel
+const clientCH = tracingChannel('apm:prisma:client')
+
+const allowedClientSpanOperations = new Set([
+  'operation',
+  'serialize',
+  'transaction'
+])
+
+class TracingHelper {
+  dbConfig = null
+  isEnabled () {
+    return true
+  }
+
+  // needs a sampled tracecontext to generate engine spans
+  getTraceParent (context) {
+    return '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01' // valid sampled traceparent
+  }
+
+  dispatchEngineSpans (spans) {
+    for (const span of spans) {
+      if (span.parentId === null) {
+        prismaEngineStart.publish({ engineSpan: span, allEngineSpans: spans, dbConfig: this.dbConfig })
+      }
+    }
+  }
+
+  getActiveContext () {}
+
+  runInChildSpan (options, callback) {
+    if (typeof options === 'string') {
+      options = {
+        name: options
+      }
+    }
+
+    if (allowedClientSpanOperations.has(options.name)) {
+      const ctx = {
+        resourceName: options.name,
+        attributes: options.attributes || {}
+      }
+
+      if (options.name !== 'serialize') {
+        return clientCH.tracePromise(callback, ctx, this, ...arguments)
+      }
+
+      return clientCH.traceSync(callback, ctx, this, ...arguments)
+    }
+    return callback()
+  }
+
+  setDbString (dbConfig) {
+    this.dbConfig = dbConfig
+  }
+}
+
+addHook({ name: '@prisma/client', versions: ['>=6.1.0'] }, (prisma, version) => {
+  const tracingHelper = new TracingHelper()
+
+  /*
+    * This is a custom PrismaClient that extends the original PrismaClient
+    * This allows us to grab additional information from the PrismaClient such as DB connection strings
+  */
+  class PrismaClient extends prisma.PrismaClient {
+    constructor (...args) {
+      super(...args)
+
+      const datasources = this._engine?.config.inlineDatasources?.db.url?.value
+      if (datasources) {
+        const result = parseDBString(datasources)
+        tracingHelper.setDbString(result)
+      }
+    }
+  }
+
+  prisma.PrismaClient = PrismaClient
+  /*
+    * This is taking advantage of the built in tracing support from Prisma.
+    * The below variable is setting a global tracing helper that Prisma uses
+    * to enable OpenTelemetry.
+  */
+  // https://github.com/prisma/prisma/blob/478293bbfce91e41ceff02f2a0b03bb8acbca03e/packages/instrumentation/src/PrismaInstrumentation.ts#L42
+  const versions = version.split('.')
+  if (versions[0] === '6' && versions[1] < 4) {
+    global.PRISMA_INSTRUMENTATION = {
+      helper: tracingHelper
+    }
+  } else {
+    global[`V${versions[0]}_PRISMA_INSTRUMENTATION`] = {
+      helper: tracingHelper
+    }
+  }
+
+  return prisma
+})
+
+function parseDBString (dbString) {
+  const url = new URL(dbString)
+  const dbConfig = {
+    user: url.username,
+    password: url.password,
+    host: url.hostname,
+    port: url.port,
+    database: url.pathname.slice(1) // Remove leading slash
+  }
+  return dbConfig
+}

packages/datadog-plugin-next/test/next.config.js

@@ -18,10 +18,10 @@ if (satisfies(VERSION, '<11')) {
   }
 }
 
-// In older versions of Next.js (11.0.1 and before), the webpack config doesn't support 'node' prefixes by default
+// In older versions of Next.js (11.X and before), the webpack config doesn't support 'node' prefixes by default
 // So, any "node" prefixes are replaced for these older versions by this webpack plugin
 // Additionally, webpack was having problems with our use of 'worker_threads', so we don't resolve it
-if (satisfies(VERSION, '<11.1.0')) {
+if (satisfies(VERSION, '<=11')) {
   config.webpack = (config, { webpack }) => {
     config.plugins.push(
       new webpack.NormalModuleReplacementPlugin(/^node:/, resource => {
@@ -35,7 +35,8 @@ if (satisfies(VERSION, '<11.1.0')) {
     config.resolve.fallback = {
       ...config.resolve.fallback,
       worker_threads: false,
-      perf_hooks: false
+      perf_hooks: false,
+      'util/types': false
     }
 
     return config

packages/datadog-plugin-prisma/src/client.js

@@ -0,0 +1,62 @@
+'use strict'
+const DatabasePlugin = require('../../dd-trace/src/plugins/database')
+class PrismaClientPlugin extends DatabasePlugin {
+  static get id () { return 'prisma' }
+  static get operation () { return 'client' }
+  static get system () { return 'prisma' }
+  static get prefix () {
+    return 'tracing:apm:prisma:client'
+  }
+
+  bindStart (ctx) {
+    const service = this.serviceName({ pluginConfig: this.config })
+    const resource = formatResourceName(ctx.resourceName, ctx.attributes)
+
+    const options = { service, resource }
+
+    if (ctx.resourceName === 'operation') {
+      options.meta = {
+        prisma: {
+          method: ctx.attributes.method,
+          model: ctx.attributes.model,
+          type: 'client'
+        }
+      }
+    }
+    const operationName = this.operationName({ operation: this.operation })
+    this.startSpan(operationName, options, ctx)
+
+    return ctx.currentStore
+  }
+
+  end (ctx) {
+    // Only synchronous operations would have `result` on `end`.
+    if (Object.hasOwn(ctx, 'result')) {
+      this.finish(ctx)
+    }
+  }
+
+  bindAsyncStart (ctx) {
+    return this.bindFinish(ctx)
+  }
+
+  asyncStart (ctx) {
+    this.finish(ctx)
+  }
+
+  error (error) {
+    this.addError(error)
+  }
+}
+
+function formatResourceName (resource, attributes) {
+  if (attributes?.name) {
+    return `${attributes.name}`.trim()
+  }
+  if (attributes?.model && attributes.method) {
+    return `${attributes.model}.${attributes.method}`.trim()
+  }
+  return resource
+}
+
+module.exports = PrismaClientPlugin

packages/datadog-plugin-prisma/src/engine.js

@@ -0,0 +1,81 @@
+'use strict'
+
+const DatabasePlugin = require('../../dd-trace/src/plugins/database')
+const { CLIENT_PORT_KEY } = require('../../dd-trace/src/constants')
+
+const databaseDriverMapper = {
+  postgresql: {
+    type: 'sql',
+    'db.type': 'postgres'
+  },
+  mysql: {
+    type: 'sql',
+    'db.type': 'mysql'
+  },
+  mongodb: {
+    type: 'mongodb',
+    'db.type': 'mongodb'
+  },
+  sqlite: {
+    type: 'sql',
+    'db.type': 'sqlite'
+  }
+}
+
+class PrismaEngine extends DatabasePlugin {
+  static get id () { return 'prisma' }
+  static get operation () { return 'engine' }
+  static get system () { return 'prisma' }
+
+  start (ctx) {
+    const { engineSpan, allEngineSpans, childOf, dbConfig } = ctx
+    const service = this.serviceName({ pluginConfig: this.config, system: this.system })
+    const spanName = engineSpan.name.slice(14) // remove 'prisma:engine:' prefix
+    const options = {
+      childOf,
+      resource: spanName,
+      service,
+      kind: engineSpan.kind,
+      meta: {
+        prisma: {
+          name: spanName,
+          type: 'engine'
+        }
+      }
+    }
+
+    if (spanName === 'db_query') {
+      const query = engineSpan.attributes['db.query.text']
+      const originalStatement = this.maybeTruncate(query)
+      const type = databaseDriverMapper[engineSpan.attributes['db.system']]?.type
+      const dbType = databaseDriverMapper[engineSpan.attributes['db.system']]?.['db.type']
+
+      options.resource = originalStatement
+      options.type = type || engineSpan.attributes['db.system']
+      options.meta['db.type'] = dbType || engineSpan.attributes['db.system']
+      options.meta['db.instance'] = dbConfig?.database
+      options.meta['db.name'] = dbConfig?.user
+      options.meta['out.host'] = dbConfig?.host
+      options.meta[CLIENT_PORT_KEY] = dbConfig?.port
+    }
+
+    const activeSpan = this.startSpan(this.operationName({ operation: this.operation }), options)
+    activeSpan._startTime = hrTimeToUnixTimeMs(engineSpan.startTime)
+    for (const span of allEngineSpans) {
+      if (span.parentId === engineSpan.id) {
+        const startCtx = { engineSpan: span, allEngineSpans, childOf: activeSpan, dbConfig }
+        this.start(startCtx)
+      }
+    }
+    const unixEndTime = hrTimeToUnixTimeMs(engineSpan.endTime)
+    activeSpan.finish(unixEndTime)
+  }
+}
+
+// Opentelemetry time format is defined here
+// https://github.com/open-telemetry/opentelemetry-js/blob/cbc912d/api/src/common/Time.ts#L19-L30.
+function hrTimeToUnixTimeMs ([seconds, nanoseconds]) {
+  return seconds * 1000 + nanoseconds / 1e6
+}
+
+module.exports = PrismaEngine