newrelic 13.2.0 → 13.3.0

package/lib/subscribers/openai/chat.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const OpenAISubscriber = require('./base')
+const { AI } = require('../../metrics/names')
+const { OPENAI } = AI
+const {
+  addLlmMeta,
+  recordChatCompletionMessages,
+  instrumentStream,
+} = require('./utils')
+const semver = require('semver')
+const MIN_STREAM_VERSION = '4.12.2'
+
+class OpenAIChatCompletions extends OpenAISubscriber {
+  constructor({ agent, logger, channelName = 'nr_completionsCreate' }) {
+    super({ agent, logger, channelName })
+  }
+
+  handler(data, ctx) {
+    const { arguments: args, moduleVersion } = data
+    const [request] = args
+    if (request.stream && semver.lt(moduleVersion, MIN_STREAM_VERSION)) {
+      this.logger.warn(`Instrumenting chat completion streams is only supported with openai version ${MIN_STREAM_VERSION}+.`)
+      return ctx
+    }
+
+    const segment = this.agent.tracer.createSegment({
+      name: OPENAI.COMPLETION,
+      parent: ctx.segment,
+      transaction: ctx.transaction
+    })
+    const newCtx = ctx.enterSegment({ segment })
+    return newCtx
+  }
+
+  asyncEnd(data) {
+    const ctx = this.agent.tracer.getContext()
+    if (!ctx?.segment || !ctx?.transaction) {
+      return
+    }
+    const { result: response, arguments: args, error: err } = data
+    const [request] = args
+
+    if (request.stream) {
+      instrumentStream({
+        agent: this.agent,
+        logger: this.logger,
+        request,
+        headers: ctx.extras?.headers,
+        response,
+        segment: ctx.segment,
+        transaction: ctx.transaction,
+        err
+      })
+    } else {
+      recordChatCompletionMessages({
+        agent: this.agent,
+        logger: this.logger,
+        segment: ctx.segment,
+        transaction: ctx.transaction,
+        request,
+        response,
+        headers: ctx.extras?.headers,
+        err
+      })
+    }
+
+    addLlmMeta({
+      agent: this.agent,
+      transaction: ctx.transaction,
+      version: data.moduleVersion,
+    })
+  }
+}
+
+module.exports = OpenAIChatCompletions

package/lib/subscribers/openai/client.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const OpenAISubscriber = require('./base')
+class OpenAIClientSubscriber extends OpenAISubscriber {
+  constructor({ agent, logger }) {
+    super({ agent, logger, channelName: 'nr_makeRequest' })
+  }
+
+  handler(data, ctx) {
+    const { self } = data
+    ctx.extras = { apiKey: self.apiKey }
+    return ctx
+  }
+
+  asyncEnd(data) {
+    const { result } = data
+    const ctx = this.agent.tracer.getContext()
+    if (ctx?.segment) {
+      const headers = result?.response?.headers
+        ? Object.fromEntries(result.response.headers)
+        : { ...result?.headers }
+      ctx.extras = { headers }
+    }
+  }
+}
+
+module.exports = OpenAIClientSubscriber

package/lib/subscribers/openai/config.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+module.exports = {
+  openai: [
+    {
+      path: './openai/chat.js',
+      instrumentations: [
+        {
+          channelName: 'nr_completionsCreate',
+          module: { name: 'openai', versionRange: '>=4.0.0', filePath: 'resources/chat/completions.js' },
+          functionQuery: {
+            className: 'Completions',
+            methodName: 'create',
+            kind: 'Async'
+          }
+        },
+        {
+          channelName: 'nr_completionsCreate',
+          module: { name: 'openai', versionRange: '>=4.0.0', filePath: 'resources/chat/completions/completions.js' },
+          functionQuery: {
+            className: 'Completions',
+            methodName: 'create',
+            kind: 'Async'
+          }
+        }
+      ]
+    },
+    {
+      path: './openai/chat-responses.js',
+      instrumentations: [
+        {
+          channelName: 'nr_responses',
+          module: { name: 'openai', versionRange: '>=4.87.0', filePath: 'resources/responses/responses.js' },
+          functionQuery: {
+            className: 'Responses',
+            methodName: 'create',
+            kind: 'Async'
+          }
+        }
+      ]
+    },
+    {
+      path: './openai/client.js',
+      instrumentations: [
+        {
+          channelName: 'nr_makeRequest',
+          module: { name: 'openai', versionRange: '>=4.0.0', filePath: 'core.js' },
+          functionQuery: {
+            className: 'APIClient',
+            methodName: 'makeRequest',
+            kind: 'Async'
+          }
+        },
+        {
+          channelName: 'nr_makeRequest',
+          module: { name: 'openai', versionRange: '>=4.0.0', filePath: 'client.js' },
+          functionQuery: {
+            className: 'OpenAI',
+            methodName: 'makeRequest',
+            kind: 'Async'
+          }
+        }
+      ]
+    },
+    {
+      path: './openai/embeddings.js',
+      instrumentations: [
+        {
+          channelName: 'nr_embeddingsCreate',
+          module: { name: 'openai', versionRange: '>=4.0.0', filePath: 'resources/embeddings.js' },
+          functionQuery: {
+            className: 'Embeddings',
+            methodName: 'create',
+            kind: 'Async'
+          }
+        }
+      ]
+    }
+  ]
+}

package/lib/subscribers/openai/embeddings.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const OpenAISubscriber = require('./base')
+const { AI } = require('../../metrics/names')
+const { OPENAI } = AI
+const {
+  addLlmMeta,
+  recordEmbeddingMessage
+} = require('./utils')
+
+class OpenAIEmbeddings extends OpenAISubscriber {
+  constructor({ agent, logger }) {
+    super({ agent, logger, channelName: 'nr_embeddingsCreate' })
+  }
+
+  handler(data, ctx) {
+    const segment = this.agent.tracer.createSegment({
+      name: OPENAI.EMBEDDING,
+      parent: ctx.segment,
+      transaction: ctx.transaction
+    })
+    const newCtx = ctx.enterSegment({ segment })
+    return newCtx
+  }
+
+  asyncEnd(data) {
+    const ctx = this.agent.tracer.getContext()
+    if (!ctx?.segment || !ctx?.transaction) {
+      return
+    }
+    const { arguments: args, error: err } = data
+    const { result: response } = data
+    const [request] = args
+    const agent = this.agent
+    const { segment, transaction } = ctx
+    recordEmbeddingMessage({
+      agent,
+      logger: this.logger,
+      segment,
+      transaction,
+      request,
+      response,
+      headers: ctx.extras?.headers,
+      err
+    })
+    addLlmMeta({ agent, transaction, version: data.moduleVersion })
+  }
+}
+
+module.exports = OpenAIEmbeddings

package/lib/subscribers/openai/utils.js

@@ -0,0 +1,349 @@
+/*
+ * Copyright 2023 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const {
+  LlmChatCompletionMessage,
+  LlmChatCompletionSummary,
+  LlmEmbedding,
+  LlmErrorMessage
+} = require('../../llm-events/openai')
+const { extractLlmContext } = require('../../util/llm-utils')
+
+const { AI } = require('../../metrics/names')
+const { OPENAI } = AI
+const { DESTINATIONS } = require('../../config/attribute-filter')
+let TRACKING_METRIC = OPENAI.TRACKING_PREFIX
+
+/**
+ * Parses the response from OpenAI and extracts the message content and role.
+ *
+ * @param {object} response The OpenAI SDK response object
+ * @returns {{ content: string, role: string }} the message object with fields `content` and `role`
+ */
+function getMessageFromResponse(response) {
+  let content
+  let role
+  if (response?.object === 'response') {
+    content = response?.output?.[0]?.content?.[0]?.text
+    role = response?.output?.[0]?.role
+  } else {
+    content = response?.choices?.[0]?.message?.content
+    role = response?.choices?.[0]?.message?.role
+  }
+
+  return { content, role }
+}
+
+/**
+ * Parses all messages from the OpenAI request object.
+ *
+ * @param {object} request The OpenAI SDK request object
+ * @param logger
+ * @returns {Array<object>} an array of message objects with fields `content` and `role`
+ */
+function getMessagesFromRequest(request, logger) {
+  // There are a few different ways to pass messages to OpenAI SDK.
+  //
+  // For langchain and `chat.completions.create`, messages are passed
+  // as an array of objects with `content` and `role` properties
+  // to the `messages` field of the request.
+  //
+  // For `responses.create`, messages are passed as an array of objects
+  // with `content` and `role` properties OR as a single string (implied
+  // to be a user message) to the `input` field of the request.
+  let messages = []
+
+  if (Array.isArray(request?.input)) {
+    // Handle array of input messages
+    messages = request.input.filter((msg) => msg?.content && msg?.role)
+  } else if (typeof request?.input === 'string') {
+    // Handle single string input as a user message
+    messages = [{ content: request.input, role: 'user' }]
+  } else if (Array.isArray(request?.messages)) {
+    // Handle array of messages
+    messages = request.messages.filter((msg) => msg?.content && msg?.role)
+  } else {
+    logger.warn('No valid messages found in OpenAI request object.')
+  }
+
+  return messages
+}
+
+/**
+ * Enqueues a LLM event to the custom event aggregator
+ *
+ * @param {object} params input params
+ * @param {Agent} params.agent NR agent instance
+ * @param {string} params.type LLM event type
+ * @param {object} params.msg LLM event
+ */
+function recordEvent({ agent, type, msg }) {
+  const llmContext = extractLlmContext(agent)
+
+  agent.customEventAggregator.add([
+    { type, timestamp: Date.now() },
+    Object.assign({}, msg, llmContext)
+  ])
+}
+
+/**
+ * Increments the tracking metric and sets the llm attribute on transactions
+ *
+ * @param {object} params input params
+ * @param {Agent} params.agent NR agent instance
+ * @param {Transaction} params.transaction active transaction
+ * @param params.version
+ */
+function addLlmMeta({ agent, transaction, version }) {
+  TRACKING_METRIC = `${TRACKING_METRIC}/${version}`
+  agent.metrics.getOrCreateMetric(TRACKING_METRIC).incrementCallCount()
+  transaction.trace.attributes.addAttribute(DESTINATIONS.TRANS_EVENT, 'llm', true)
+}
+
+/**
+ * Generates LlmChatCompletionSummary for a chat completion creation.
+ * Also iterates over both input messages and the first response message
+ * and creates LlmChatCompletionMessage.
+ *
+ * Also assigns relevant ids by response id for LlmFeedbackEvent creation
+ *
+ * @param {object} params input params
+ * @param {Agent} params.agent NR agent instance
+ * @param {TraceSegment} params.segment active segment from chat completion
+ * @param {object} params.request chat completion params
+ * @param {object} params.response chat completion response
+ * @param {boolean} [params.err] err if it exists
+ * @param {Transaction} params.transaction active transaction
+ * @param params.headers
+ * @param params.logger
+ */
+function recordChatCompletionMessages({
+  agent,
+  headers,
+  logger,
+  segment,
+  request,
+  response,
+  err,
+  transaction
+}) {
+  if (shouldSkipInstrumentation(agent.config, logger) === true) {
+    logger.debug('skipping sending of ai data')
+    return
+  }
+
+  if (!response) {
+    // If we get an error, it is possible that `response = null`.
+    // In that case, we define it to be an empty object.
+    response = {}
+  }
+
+  response.headers = headers
+  // explicitly end segment to consistent duration
+  // for both LLM events and the segment
+  segment.end()
+  const completionSummary = new LlmChatCompletionSummary({
+    agent,
+    segment,
+    transaction,
+    request,
+    response,
+    withError: err != null
+  })
+
+  // Note: langchain still expects a message event even
+  // when the response is empty, so we will not filter
+  // the response message.
+  const messages = [
+    ...getMessagesFromRequest(request, logger),
+    getMessageFromResponse(response)
+  ]
+
+  messages.forEach((message, index) => {
+    const completionMsg = new LlmChatCompletionMessage({
+      agent,
+      segment,
+      transaction,
+      request,
+      response,
+      index,
+      completionId: completionSummary.id,
+      message
+    })
+
+    recordEvent({ agent, type: 'LlmChatCompletionMessage', msg: completionMsg })
+  })
+
+  recordEvent({ agent, type: 'LlmChatCompletionSummary', msg: completionSummary })
+
+  if (err) {
+    const llmError = new LlmErrorMessage({ cause: err, summary: completionSummary, response })
+    agent.errors.add(transaction, err, llmError)
+  }
+
+  delete response.headers
+}
+
+/**
+ * Checks if we should skip instrumentation.
+ * Currently, it checks if `ai_monitoring.enabled` is true
+ * and the package version >= 4.0.0
+ *
+ * @param {object} config agent config
+ * @param logger
+ * @returns {boolean} flag if instrumentation should be skipped
+ */
+function shouldSkipInstrumentation(config, logger) {
+  if (config?.ai_monitoring?.enabled !== true) {
+    logger.debug('config.ai_monitoring.enabled is set to false.')
+    return true
+  }
+}
+
+/**
+ * `chat.completions.create` can return a stream once promise resolves.
+ * This wraps the iterator which is a generator function.
+ * We will call the original iterator, intercept chunks and yield
+ * to the original. On complete, we will construct the new message object
+ * with what we have seen in the stream and create the chat completion
+ * messages.
+ * @param {object} params input params
+ * @param {Agent} params.agent NR agent instance
+ * @param {Shim} params.shim the current shim instance
+ * @param {object} params.request chat completion params
+ * @param {object} params.response chat completion response
+ * @param {TraceSegment} params.segment active segment from chat completion
+ * @param {Transaction} params.transaction active transaction
+ * @param {Error} params.err error if it exists
+ * @param params.headers
+ * @param params.logger
+ */
+function instrumentStream({ agent, headers, logger, request, response, segment, transaction, err = null }) {
+  if (!agent.config.ai_monitoring.streaming.enabled) {
+    logger.warn(
+      '`ai_monitoring.streaming.enabled` is set to `false`, stream will not be instrumented.'
+    )
+    agent.metrics.getOrCreateMetric(AI.STREAMING_DISABLED).incrementCallCount()
+    return
+  }
+
+  if (err) {
+    // If there is an error already e.g. APIConnectionError,
+    // the iterator will not be called, so we have to
+    // record the chat completion messages with the error now.
+    segment.touch()
+    recordChatCompletionMessages({
+      agent,
+      headers,
+      logger,
+      segment,
+      transaction,
+      request,
+      response,
+      err
+    })
+    return
+  }
+
+  const orig = response.iterator
+  response.iterator = async function * wrappedIterator() {
+    let content = ''
+    let role = ''
+    let chunk
+    try {
+      const iterator = orig.apply(this, arguments)
+
+      for await (chunk of iterator) {
+        if (chunk.choices?.[0]?.delta?.role) {
+          role = chunk.choices[0].delta.role
+        }
+
+        content += chunk.choices?.[0]?.delta?.content ?? ''
+        yield chunk
+      }
+    } catch (streamErr) {
+      err = streamErr
+      throw err
+    } finally {
+      if (chunk?.choices) {
+        chunk.choices[0].message = { role, content }
+      } else if (chunk?.response) {
+        chunk = chunk.response
+      }
+
+      // update segment duration since we want to extend the time it took to
+      // handle the stream
+      segment.touch()
+
+      recordChatCompletionMessages({
+        agent,
+        headers,
+        logger,
+        segment,
+        transaction,
+        request,
+        response: chunk,
+        err
+      })
+    }
+  }
+}
+
+function recordEmbeddingMessage({
+  agent,
+  logger,
+  request,
+  headers,
+  response,
+  segment,
+  transaction,
+  err
+}) {
+  if (!response) {
+    // If we get an error, it is possible that `response = null`.
+    // In that case, we define it to be an empty object.
+    response = {}
+  }
+
+  segment.end()
+  if (shouldSkipInstrumentation(agent.config, logger) === true) {
+    // We need this check inside the wrapper because it is possible for monitoring
+    // to be disabled at the account level. In such a case, the value is set
+    // after the instrumentation has been initialized.
+    logger.debug('skipping sending of ai data')
+    return
+  }
+
+  response.headers = headers
+  // explicitly end segment to get consistent duration
+  // for both LLM events and the segment
+
+  const embedding = new LlmEmbedding({
+    agent,
+    segment,
+    transaction,
+    request,
+    response,
+    withError: err != null
+  })
+
+  recordEvent({ agent, type: 'LlmEmbedding', msg: embedding })
+
+  if (err) {
+    const llmError = new LlmErrorMessage({ cause: err, embedding, response })
+    agent.errors.add(transaction, err, llmError)
+  }
+
+  // cleanup keys on response before returning to user code
+  delete response.headers
+}
+
+module.exports = {
+  addLlmMeta,
+  instrumentStream,
+  recordChatCompletionMessages,
+  recordEmbeddingMessage
+}