dd-trace 5.24.0 → 5.25.0

package/LICENSE-3rdparty.csv

@@ -29,6 +29,7 @@ require,retry,MIT,Copyright 2011 Tim Koschützki Felix Geisendörfer
 require,rfdc,MIT,Copyright 2019 David Mark Clements
 require,semver,ISC,Copyright Isaac Z. Schlueter and Contributors
 require,shell-quote,mit,Copyright (c) 2013 James Halliday
+dev,@apollo/server,MIT,Copyright (c) 2016-2020 Apollo Graph, Inc. (Formerly Meteor Development Group, Inc.)
 dev,@types/node,MIT,Copyright Authors
 dev,autocannon,MIT,Copyright 2016 Matteo Collina
 dev,aws-sdk,Apache 2.0,Copyright 2012-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.

package/index.d.ts

@@ -137,6 +137,11 @@ interface Tracer extends opentracing.Tracer {
   TracerProvider: tracer.opentelemetry.TracerProvider;
 
   dogstatsd: tracer.DogStatsD;
+
+  /**
+   * LLM Observability SDK
+   */
+  llmobs: tracer.llmobs.LLMObs;
 }
 
 // left out of the namespace, so it
@@ -752,6 +757,11 @@ declare namespace tracer {
        */
       maxDepth?: number
     }
+    
+    /**
+     * Configuration enabling LLM Observability. Enablement is superceded by the DD_LLMOBS_ENABLED environment variable.
+     */
+    llmobs?: llmobs.LLMObsEnableOptions
   }
 
   /**
@@ -2198,6 +2208,331 @@ declare namespace tracer {
      */
     telemetryVerbosity?: string
   }
+
+  export namespace llmobs {
+    export interface LLMObs {
+
+      /**
+       * Whether or not LLM Observability is enabled.
+       */
+      enabled: boolean,
+
+      /**
+       * Enable LLM Observability tracing.
+       */
+      enable (options: LLMObsEnableOptions): void,
+
+      /**
+       * Disable LLM Observability tracing.
+       */
+      disable (): void,
+      
+      /**
+       * Instruments a function by automatically creating a span activated on its
+       * scope.
+       *
+       * The span will automatically be finished when one of these conditions is
+       * met:
+       *
+       * * The function returns a promise, in which case the span will finish when
+       * the promise is resolved or rejected.
+       * * The function takes a callback as its second parameter, in which case the
+       * span will finish when that callback is called.
+       * * The function doesn't accept a callback and doesn't return a promise, in
+       * which case the span will finish at the end of the function execution.
+       * @param fn The function to instrument.
+       * @param options Optional LLM Observability span options.
+       * @returns The return value of the function.
+       */
+      trace<T> (options: LLMObsNamedSpanOptions, fn: (span: tracer.Span, done: (error?: Error) => void) => T): T
+
+      /**
+       * Wrap a function to automatically create a span activated on its
+       * scope when it's called.
+       *
+       * The span will automatically be finished when one of these conditions is
+       * met:
+       *
+       * * The function returns a promise, in which case the span will finish when
+       * the promise is resolved or rejected.
+       * * The function takes a callback as its last parameter, in which case the
+       * span will finish when that callback is called.
+       * * The function doesn't accept a callback and doesn't return a promise, in
+       * which case the span will finish at the end of the function execution.
+       * @param fn The function to instrument.
+       * @param options Optional LLM Observability span options.
+       * @returns A new function that wraps the provided function with span creation.
+       */
+      wrap<T = (...args: any[]) => any> (options: LLMObsNamelessSpanOptions, fn: T): T
+
+      /**
+       * Decorate a function in a javascript runtime that supports function decorators.
+       * Note that this is **not** supported in the Node.js runtime, but is in TypeScript.
+       * 
+       * In TypeScript, this decorator is only supported in contexts where general TypeScript
+       * function decorators are supported.
+       * 
+       * @param options Optional LLM Observability span options.
+       */
+      decorate (options: llmobs.LLMObsNamelessSpanOptions): any
+
+      /**
+       * Returns a representation of a span to export its span and trace IDs.
+       * If no span is provided, the current LLMObs-type span will be used.
+       * @param span Optional span to export.
+       * @returns An object containing the span and trace IDs.
+       */
+      exportSpan (span?: tracer.Span): llmobs.ExportedLLMObsSpan
+
+
+      /**
+       * Sets inputs, outputs, tags, metadata, and metrics as provided for a given LLM Observability span.
+       * Note that with the exception of tags, this method will override any existing values for the provided fields.
+       * 
+       * For example:
+       * ```javascript
+       * llmobs.trace({ kind: 'llm', name: 'myLLM', modelName: 'gpt-4o', modelProvider: 'openai' }, () => {
+       *  llmobs.annotate({
+       *    inputData: [{ content: 'system prompt, role: 'system' }, { content: 'user prompt', role: 'user' }],
+       *    outputData: { content: 'response', role: 'ai' },
+       *    metadata: { temperature: 0.7 },
+       *    tags: { host: 'localhost' },
+       *    metrics: { inputTokens: 10, outputTokens: 20, totalTokens: 30 }
+       *  })
+       * })
+       * ```
+       * 
+       * @param span The span to annotate (defaults to the current LLM Observability span if not provided)
+       * @param options An object containing the inputs, outputs, tags, metadata, and metrics to set on the span.
+       */
+      annotate (options: llmobs.AnnotationOptions): void
+      annotate (span: tracer.Span | undefined, options: llmobs.AnnotationOptions): void
+
+      /**
+       * Submits a custom evalutation metric for a given span ID and trace ID.
+       * @param spanContext The span context of the span to submit the evaluation metric for.
+       * @param options An object containing the label, metric type, value, and tags of the evaluation metric.
+       */
+      submitEvaluation (spanContext: llmobs.ExportedLLMObsSpan, options: llmobs.EvaluationOptions): void
+
+      /**
+       * Flushes any remaining spans and evaluation metrics to LLM Observability.
+       */
+      flush (): void
+    }
+
+    interface EvaluationOptions {
+      /**
+       * The name of the evalutation metric
+       */
+      label: string,
+
+      /**
+       * The type of evaluation metric, one of 'categorical' or 'score'
+       */
+      metricType: 'categorical' | 'score',
+
+      /**
+       * The value of the evaluation metric.
+       * Must be string for 'categorical' metrics and number for 'score' metrics.
+       */
+      value: string | number,
+
+      /**
+       * An object of string key-value pairs to tag the evaluation metric with.
+       */
+      tags?: { [key: string]: any },
+
+      /**
+       * The name of the ML application
+       */
+      mlApp?: string,
+
+      /**
+       * The timestamp in milliseconds when the evaluation metric result was generated.
+       */
+      timestampMs?: number
+    }
+
+    interface Document {
+      /**
+       * Document text
+       */
+      text?: string,
+
+      /**
+       * Document name
+       */
+      name?: string,
+
+      /**
+       * Document ID
+       */
+      id?: string,
+
+      /**
+       * Score of the document retrieval as a source of ground truth
+       */
+      score?: number
+    }
+
+    /**
+     * Represents a single LLM chat model message
+     */
+    interface Message {
+      /**
+       * Content of the message.
+       */
+      content: string,
+
+      /**
+       * Role of the message (ie system, user, ai)
+       */
+      role?: string,
+
+      /**
+       * Tool calls of the message
+       */
+      toolCalls?: ToolCall[],
+    }
+
+    /**
+     * Represents a single tool call for an LLM chat model message
+     */
+    interface ToolCall {
+      /**
+       * Name of the tool
+       */
+      name?: string,
+
+      /**
+       * Arguments passed to the tool
+       */
+      arguments?: { [key: string]: any },
+
+      /**
+       * The tool ID
+       */
+      toolId?: string,
+
+      /**
+       * The tool type
+       */
+      type?: string
+    }
+
+    /**
+     * Annotation options for LLM Observability spans.
+     */
+    interface AnnotationOptions {
+      /**
+       * A single input string, object, or a list of objects based on the span kind:
+       * 1. LLM spans: accepts a string, or an object of the form {content: "...", role: "..."}, or a list of objects with the same signature.
+       * 2. Embedding spans: accepts a string, list of strings, or an object of the form {text: "...", ...}, or a list of objects with the same signature.
+       * 3. Other: any JSON serializable type
+       */
+      inputData?: string | Message | Message[] | Document | Document[] | { [key: string]: any },
+
+      /**
+       * A single output string, object, or a list of objects based on the span kind:
+       * 1. LLM spans: accepts a string, or an object of the form {content: "...", role: "..."}, or a list of objects with the same signature.
+       * 2. Retrieval spans: An object containing any of the key value pairs {name: str, id: str, text: str, source: number} or a list of dictionaries with the same signature.
+       * 3. Other: any JSON serializable type
+       */
+      outputData?: string | Message | Message[] | Document | Document[] | { [key: string]: any },
+
+      /**
+       * Object of JSON serializable key-value metadata pairs relevant to the input/output operation described by the LLM Observability span.
+       */
+      metadata?: { [key: string]: any },
+
+      /**
+       * Object of JSON seraliazable key-value metrics (number) pairs, such as `{input,output,total}Tokens`
+       */
+      metrics?: { [key: string]: number },
+
+      /**
+       * Object of JSON serializable key-value tag pairs to set or update on the LLM Observability span regarding the span's context.
+       */
+      tags?: { [key: string]: any }
+    }
+
+    /**
+     * An object containing the span ID and trace ID of interest
+     */
+    interface ExportedLLMObsSpan {
+      /**
+       * Trace ID associated with the span of interest
+       */
+      traceId: string,
+
+      /**
+       * Span ID associated with the span of interest
+       */
+      spanId: string,
+    }
+
+    interface LLMObsSpanOptions extends SpanOptions {
+      /**
+       * LLM Observability span kind. One of `agent`, `workflow`, `task`, `tool`, `retrieval`, `embedding`, or `llm`.
+       */
+      kind: llmobs.spanKind,
+  
+      /**
+       * The ID of the underlying user session. Required for tracking sessions.
+       */
+      sessionId?: string,
+
+      /**
+       * The name of the ML application that the agent is orchestrating. 
+       * If not provided, the default value will be set to mlApp provided during initalization, or `DD_LLMOBS_ML_APP`.
+       */
+      mlApp?: string,
+
+      /**
+       * The name of the invoked LLM or embedding model. Only used on `llm` and `embedding` spans.
+       */
+      modelName?: string,
+
+      /**
+       * The name of the invoked LLM or embedding model provider. Only used on `llm` and `embedding` spans.
+       * If not provided for LLM or embedding spans, a default value of 'custom' will be set.
+       */
+      modelProvider?: string,
+    }
+
+    interface LLMObsNamedSpanOptions extends LLMObsSpanOptions {
+      /**
+       * The name of the traced operation. This is a required option.
+       */
+      name: string,
+    }
+
+    interface LLMObsNamelessSpanOptions extends LLMObsSpanOptions {
+      /**
+       * The name of the traced operation.
+       */
+      name?: string,
+    }
+
+    /**
+     * Options for enabling LLM Observability tracing.
+     */
+    interface LLMObsEnableOptions {
+      /**
+       * The name of your ML application.
+       */
+      mlApp?: string,
+
+      /**
+       * Set to `true` to disbale sending data that requires a Datadog Agent.
+       */
+      agentlessEnabled?: boolean,
+    }
+
+    /** @hidden */
+    type spanKind = 'agent' | 'workflow' | 'task' | 'tool' | 'retrieval' | 'embedding' | 'llm'
+  }
 }
 
 /**

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "dd-trace",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "description": "Datadog APM tracing client for JavaScript",
   "main": "index.js",
   "typings": "index.d.ts",
   "scripts": {
+    "env": "bash ./plugin-env",
     "preinstall": "node scripts/preinstall.js",
     "bench": "node benchmark",
     "bench:profiler": "node benchmark/profiler",
@@ -12,8 +13,8 @@
     "bench:e2e:ci-visibility": "node benchmark/e2e-ci/benchmark-run.js",
     "type:doc": "cd docs && yarn && yarn build",
     "type:test": "cd docs && yarn && yarn test",
-    "lint": "node scripts/check_licenses.js && eslint . && yarn audit --groups dependencies",
-    "lint-fix": "node scripts/check_licenses.js && eslint . --fix && yarn audit --groups dependencies",
+    "lint": "node scripts/check_licenses.js && eslint . && yarn audit",
+    "lint-fix": "node scripts/check_licenses.js && eslint . --fix && yarn audit",
     "services": "node ./scripts/install_plugin_modules && node packages/dd-trace/test/setup/services",
     "test": "SERVICES=* yarn services && mocha --expose-gc 'packages/dd-trace/test/setup/node.js' 'packages/*/test/**/*.spec.js'",
     "test:appsec": "mocha -r \"packages/dd-trace/test/setup/mocha.js\" --exclude \"packages/dd-trace/test/appsec/**/*.plugin.spec.js\" \"packages/dd-trace/test/appsec/**/*.spec.js\"",
@@ -30,6 +31,10 @@
     "test:core:ci": "npm run test:core -- --coverage --nyc-arg=--include=\"packages/datadog-core/src/**/*.js\"",
     "test:lambda": "mocha -r \"packages/dd-trace/test/setup/mocha.js\" \"packages/dd-trace/test/lambda/**/*.spec.js\"",
     "test:lambda:ci": "nyc --no-clean --include \"packages/dd-trace/src/lambda/**/*.js\" -- npm run test:lambda",
+    "test:llmobs:sdk": "mocha -r \"packages/dd-trace/test/setup/mocha.js\" --exclude \"packages/dd-trace/test/llmobs/plugins/**/*.spec.js\" \"packages/dd-trace/test/llmobs/**/*.spec.js\" ",
+    "test:llmobs:sdk:ci": "nyc --no-clean --include \"packages/dd-trace/src/llmobs/**/*.js\" -- npm run test:llmobs:sdk",
+    "test:llmobs:plugins": "mocha -r \"packages/dd-trace/test/setup/mocha.js\" \"packages/dd-trace/test/llmobs/plugins/**/*.spec.js\"",
+    "test:llmobs:plugins:ci": "yarn services && nyc --no-clean --include \"packages/dd-trace/src/llmobs/**/*.js\" -- npm run test:llmobs:plugins",
     "test:plugins": "mocha -r \"packages/dd-trace/test/setup/mocha.js\" \"packages/datadog-instrumentations/test/@($(echo $PLUGINS)).spec.js\" \"packages/datadog-plugin-@($(echo $PLUGINS))/test/**/*.spec.js\"",
     "test:plugins:ci": "yarn services && nyc --no-clean --include \"packages/datadog-instrumentations/src/@($(echo $PLUGINS)).js\" --include \"packages/datadog-instrumentations/src/@($(echo $PLUGINS))/**/*.js\" --include \"packages/datadog-plugin-@($(echo $PLUGINS))/src/**/*.js\" -- npm run test:plugins",
     "test:plugins:upstream": "node ./packages/dd-trace/test/plugins/suite.js",
@@ -76,11 +81,11 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@datadog/native-appsec": "8.1.1",
+    "@datadog/native-appsec": "8.2.1",
     "@datadog/native-iast-rewriter": "2.5.0",
-    "@datadog/native-iast-taint-tracking": "3.1.0",
-    "@datadog/native-metrics": "^2.0.0",
-    "@datadog/pprof": "5.3.0",
+    "@datadog/native-iast-taint-tracking": "3.2.0",
+    "@datadog/native-metrics": "^3.0.1",
+    "@datadog/pprof": "5.4.1",
     "@datadog/sketches-js": "^2.1.0",
     "@opentelemetry/api": ">=1.0.0 <1.9.0",
     "@opentelemetry/core": "^1.14.0",
@@ -108,6 +113,7 @@
     "tlhunter-sorted-set": "^0.1.0"
   },
   "devDependencies": {
+    "@apollo/server": "^4.11.0",
     "@types/node": "^16.18.103",
     "autocannon": "^4.5.2",
     "aws-sdk": "^2.1446.0",

package/packages/datadog-code-origin/index.js

@@ -5,15 +5,15 @@ const { getUserLandFrames } = require('../dd-trace/src/plugins/util/stacktrace')
 const limit = Number(process.env._DD_CODE_ORIGIN_MAX_USER_FRAMES) || 8
 
 module.exports = {
-  entryTag,
-  exitTag
+  entryTags,
+  exitTags
 }
 
-function entryTag (topOfStackFunc) {
+function entryTags (topOfStackFunc) {
   return tag('entry', topOfStackFunc)
 }
 
-function exitTag (topOfStackFunc) {
+function exitTags (topOfStackFunc) {
   return tag('exit', topOfStackFunc)
 }
 

package/packages/datadog-core/src/utils/src/parse-tags.js

@@ -0,0 +1,33 @@
+'use strict'
+
+const digitRegex = /^\d+$/
+
+/**
+ * Converts a flat object of tags into a nested object. For example:
+ *   { 'a.b.c': 'value' } -> { a: { b: { c: 'value' } } }
+ * Also supports array-keys. For example:
+ *   { 'a.0.b': 'value' } -> { a: [{ b: 'value' }] }
+ *
+ * @param {Object} tags - Key/value pairs of tags
+ * @returns Object - Parsed tags
+ */
+module.exports = tags => {
+  const parsedTags = {}
+  for (const [tag, value] of Object.entries(tags)) {
+    const keys = tag.split('.')
+    let current = parsedTags
+    let depth = 0
+    for (const key of keys) {
+      if (!current[key]) {
+        if (depth === keys.length - 1) {
+          current[key] = value
+          break
+        }
+        current[key] = keys[depth + 1]?.match(digitRegex) ? [] : {}
+      }
+      current = current[key]
+      depth++
+    }
+  }
+  return parsedTags
+}

package/packages/datadog-esbuild/index.js

@@ -96,7 +96,9 @@ module.exports.setup = function (build) {
 
       let pathToPackageJson
       try {
-        pathToPackageJson = require.resolve(`${extracted.pkg}/package.json`, { paths: [args.resolveDir] })
+        // we can't use require.resolve('pkg/package.json') as ESM modules don't make the file available
+        pathToPackageJson = require.resolve(`${extracted.pkg}`, { paths: [args.resolveDir] })
+        pathToPackageJson = extractPackageAndModulePath(pathToPackageJson).pkgJson
       } catch (err) {
         if (err.code === 'MODULE_NOT_FOUND') {
           if (!internal) {
@@ -111,7 +113,7 @@ module.exports.setup = function (build) {
         }
       }
 
-      const packageJson = require(pathToPackageJson)
+      const packageJson = JSON.parse(fs.readFileSync(pathToPackageJson).toString())
 
       if (DEBUG) console.log(`RESOLVE: ${args.path}@${packageJson.version}`)
 

package/packages/datadog-instrumentations/src/amqplib.js

@@ -25,6 +25,70 @@ addHook({ name: 'amqplib', file: 'lib/defs.js', versions: [MIN_VERSION] }, defs
   return defs
 })
 
+addHook({ name: 'amqplib', file: 'lib/channel_model.js', versions: [MIN_VERSION] }, x => {
+  shimmer.wrap(x.Channel.prototype, 'get', getMessage => function (queue, options) {
+    return getMessage.apply(this, arguments).then(message => {
+      if (message === null) {
+        return message
+      }
+      startCh.publish({ method: 'basic.get', message, fields: message.fields, queue })
+      // finish right away
+      finishCh.publish()
+      return message
+    })
+  })
+  shimmer.wrap(x.Channel.prototype, 'consume', consume => function (queue, callback, options) {
+    if (!startCh.hasSubscribers) {
+      return consume.apply(this, arguments)
+    }
+    arguments[1] = (message, ...args) => {
+      if (message === null) {
+        return callback(message, ...args)
+      }
+      startCh.publish({ method: 'basic.deliver', message, fields: message.fields, queue })
+      const result = callback(message, ...args)
+      finishCh.publish()
+      return result
+    }
+    return consume.apply(this, arguments)
+  })
+  return x
+})
+
+addHook({ name: 'amqplib', file: 'lib/callback_model.js', versions: [MIN_VERSION] }, channel => {
+  shimmer.wrap(channel.Channel.prototype, 'get', getMessage => function (queue, options, callback) {
+    if (!startCh.hasSubscribers) {
+      return getMessage.apply(this, arguments)
+    }
+    arguments[2] = (error, message, ...args) => {
+      if (error !== null || message === null) {
+        return callback(error, message, ...args)
+      }
+      startCh.publish({ method: 'basic.get', message, fields: message.fields, queue })
+      const result = callback(error, message, ...args)
+      finishCh.publish()
+      return result
+    }
+    return getMessage.apply(this, arguments)
+  })
+  shimmer.wrap(channel.Channel.prototype, 'consume', consume => function (queue, callback) {
+    if (!startCh.hasSubscribers) {
+      return consume.apply(this, arguments)
+    }
+    arguments[1] = (message, ...args) => {
+      if (message === null) {
+        return callback(message, ...args)
+      }
+      startCh.publish({ method: 'basic.deliver', message, fields: message.fields, queue })
+      const result = callback(message, ...args)
+      finishCh.publish()
+      return result
+    }
+    return consume.apply(this, arguments)
+  })
+  return channel
+})
+
 addHook({ name: 'amqplib', file: 'lib/channel.js', versions: [MIN_VERSION] }, channel => {
   shimmer.wrap(channel.Channel.prototype, 'sendImmediately', sendImmediately => function (method, fields) {
     return instrument(sendImmediately, this, arguments, methods[method], fields)
@@ -33,15 +97,11 @@ addHook({ name: 'amqplib', file: 'lib/channel.js', versions: [MIN_VERSION] }, ch
   shimmer.wrap(channel.Channel.prototype, 'sendMessage', sendMessage => function (fields) {
     return instrument(sendMessage, this, arguments, 'basic.publish', fields, arguments[2])
   })
-
-  shimmer.wrap(channel.BaseChannel.prototype, 'dispatchMessage', dispatchMessage => function (fields, message) {
-    return instrument(dispatchMessage, this, arguments, 'basic.deliver', fields, message)
-  })
   return channel
 })
 
 function instrument (send, channel, args, method, fields, message) {
-  if (!startCh.hasSubscribers) {
+  if (!startCh.hasSubscribers || method === 'basic.get') {
     return send.apply(channel, args)
   }