newrelic 12.20.0 → 12.21.0

package/NEWS.md

@@ -1,3 +1,24 @@
+### v12.21.0 (2025-06-04)
+
+#### Features
+
+* Added `@google/genai` Gemini AI LLM instrumentation ([#3119](https://github.com/newrelic/node-newrelic/pull/3119)) ([7f28a29](https://github.com/newrelic/node-newrelic/commit/7f28a293fbd623464ed1f3f809de59eaea0ff367))
+* Updated opentelemetry bridge to rely on configuration based transformation rules ([#3125](https://github.com/newrelic/node-newrelic/pull/3125)) ([ad116d2](https://github.com/newrelic/node-newrelic/commit/ad116d2aa49818c2824bca606a22c48abecf9580))
+
+#### Bug fixes
+
+* Refactored getHostnameSafe to accommodate GCP ([#3132](https://github.com/newrelic/node-newrelic/pull/3132)) ([f1eea8d](https://github.com/newrelic/node-newrelic/commit/f1eea8d076586cd0b6c4d671c261deefe5e0f027))
+* Updated openai instrumentation to work with 5.0.0+ ([#3129](https://github.com/newrelic/node-newrelic/pull/3129)) ([09146a9](https://github.com/newrelic/node-newrelic/commit/09146a9d550c0cdbb23ec54325be6f8343db8b78))
+* Updated rules to work with 1.17.0 and 1.24.0 for consumer and producer span kind ([#3128](https://github.com/newrelic/node-newrelic/pull/3128)) ([686c747](https://github.com/newrelic/node-newrelic/commit/686c747cedc2582061608c20402f11912092d5b5))
+
+#### Documentation
+
+* Updated compatibility report ([#3124](https://github.com/newrelic/node-newrelic/pull/3124)) ([c51d45f](https://github.com/newrelic/node-newrelic/commit/c51d45f4fc3c4fd56bdaa80c1028a83c7f4aadd2)) ([#3117](https://github.com/newrelic/node-newrelic/pull/3117)) ([084e599](https://github.com/newrelic/node-newrelic/commit/084e599428ac9c21e6991e27b5c154db2830ce17))
+
+#### Miscellaneous chores
+
+* Added preliminary otel configuration ([#3121](https://github.com/newrelic/node-newrelic/pull/3121)) ([664ee4a](https://github.com/newrelic/node-newrelic/commit/664ee4ae956d9cc6ebc6b68ad79a47948510422f))
+
 ### v12.20.0 (2025-05-27)
 
 #### Features

package/lib/collector/facts.js

@@ -31,11 +31,7 @@ async function facts(agent, callback, { logger = defaultLogger } = {}) {
   systemInfo = systemInfo || Object.create(null)
   environment = environment || []
 
-  let hostname = agent.config.getHostnameSafe()
-  if (agent.config.gcp_cloud_run.use_instance_as_host && process.env.K_SERVICE) {
-    // K_SERVICE is the name of the service in GCP Cloud Run
-    hostname = systemInfo.vendors?.gcp?.id
-  }
+  const hostname = agent.config.getHostnameSafe(systemInfo?.vendors?.gcp?.id)
   const results = {
     utilization: {
       metadata_version: 5,

package/lib/config/default.js

@@ -1673,7 +1673,42 @@ defaultConfig.definition = () => ({
    * **Note**: Disabling a given library may affect the instrumentation of libraries used after
    * the disabled library. Use at your own risk.
    */
-  instrumentation: pkgInstrumentation
+  instrumentation: pkgInstrumentation,
+
+  /**
+   * Governs the various OpenTelemetry based features provided by the
+   * agent.
+   *
+   * NOTICE: this configuration is subject to change while the OTEL
+   * feature set is in development.
+   */
+  opentelemetry_bridge: {
+    /**
+     * Global switch for the whole OpenTelemetry feature. If it is set to
+     * `false`, any other sub-feature, e.g. `traces`, will not be enabled
+     * regardless of that specific sub-feature setting.
+     */
+    enabled: { default: false, formatter: boolean },
+
+    /**
+     * `traces` are instrumentations, e.g. `@fastify/otel`. Enabling `traces`
+     * enables bridging OpenTelemetry instrumentations into the New Relic
+     * agent.
+     */
+    traces: {
+      enabled: { default: false, formatter: boolean }
+    },
+
+    /**
+     * `metrics` governs automatic configuration of the OpenTelemetry
+     * metrics API. When `true`, the agent will automatically configure the
+     * metrics API to send metrics to New Relic and attach them to the
+     * application entity that is instrumented by the New Relic agent.
+     */
+    metrics: {
+      enabled: { default: false, formatter: boolean }
+    }
+  }
 })
 
 /**

package/lib/config/index.js

@@ -972,16 +972,25 @@ Config.prototype.getIPAddresses = function getIPAddresses() {
   return addresses
 }
 
-function getHostnameSafe() {
+/**
+ * Gets the system's host name. If that fails, it just returns ipv4/6
+ * based on the user's process_host.ipv_preference setting.
+ * @param {string} gcpId GCP metadata ID
+ * @returns {string} host name
+ */
+function getHostnameSafe(gcpId = null) {
   let _hostname
   const config = this
   this.getHostnameSafe = function getCachedHostname() {
     return _hostname
   }
   try {
-    if (config.heroku.use_dyno_names) {
-      const dynoName = process.env.DYNO
-      _hostname = dynoName || os.hostname()
+    // Check for any special hostname scenarios.
+    // If not applicable, use the os.hostname()
+    if (config.heroku.use_dyno_names && process.env.DYNO) {
+      _hostname = process.env.DYNO || os.hostname()
+    } else if (config.gcp_cloud_run.use_instance_as_host && process.env.K_SERVICE && gcpId) {
+      _hostname = gcpId
     } else {
       _hostname = os.hostname()
     }

package/lib/feature_flags.js

@@ -10,7 +10,6 @@ exports.prerelease = {
   // internal_test_only is used for testing our feature flag implementation.
   // It is not used to gate any features.
   internal_test_only: false,
-  opentelemetry_bridge: false,
   promise_segments: false,
   reverse_naming_rules: false,
   unresolved_promise_cleanup: true,
@@ -20,26 +19,27 @@ exports.prerelease = {
 
 // flags that are no longer used for released features
 exports.released = [
-  'released',
+  'async_local_context',
+  'await_support',
+  'aws_bedrock_instrumentation',
   'cat',
+  'certificate_bundle',
   'custom_instrumentation',
   'custom_metrics',
+  'dt_format_w3c',
   'express_segments',
+  'fastify_instrumentation',
+  'langchain_instrumentation',
   'native_metrics',
   'new_promise_tracking',
+  'opentelemetry_bridge',
   'protocol_17',
-  'serverless_mode',
+  'released',
   'send_request_uri_attribute',
+  'serverless_mode',
   'synthetics',
-  'dt_format_w3c',
-  'fastify_instrumentation',
-  'await_support',
-  'certificate_bundle',
-  'async_local_context',
   'undici_async_tracking',
   'undici_instrumentation',
-  'aws_bedrock_instrumentation',
-  'langchain_instrumentation'
 ]
 
 // flags that are no longer used for unreleased features

package/lib/instrumentation/@google/genai.js

@@ -0,0 +1,289 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const {
+  LlmChatCompletionMessage,
+  LlmChatCompletionSummary,
+  LlmEmbedding,
+  LlmErrorMessage
+} = require('../../../lib/llm-events/google-genai')
+const { RecorderSpec } = require('../../../lib/shim/specs')
+const { extractLlmContext } = require('../../util/llm-utils')
+
+const { AI } = require('../../../lib/metrics/names')
+const { GEMINI } = AI
+const { DESTINATIONS } = require('../../config/attribute-filter')
+let TRACKING_METRIC = GEMINI.TRACKING_PREFIX
+
+/**
+ * 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
+ */
+function addLlmMeta({ agent, transaction }) {
+  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 {Shim} params.shim the current shim 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
+ */
+function recordChatCompletionMessages({
+  agent,
+  shim,
+  segment,
+  request,
+  response,
+  err,
+  transaction
+}) {
+  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 = {}
+  }
+
+  // Explicitly end segment to provide consistent duration
+  // for both LLM events and the segment
+  segment.end()
+  const completionSummary = new LlmChatCompletionSummary({
+    agent,
+    segment,
+    transaction,
+    request,
+    response,
+    withError: err != null
+  })
+
+  // Only take the first response message and append to input messages
+  // request.contents can be a string or an array of strings
+  // response.candidates is an array of candidates (choices); we only take the first one
+  const inputMessages = Array.isArray(request.contents) ? request.contents : [request.contents]
+  const responseMessage = response?.candidates?.[0]?.content
+  const messages = responseMessage !== undefined ? [...inputMessages, responseMessage] : inputMessages
+  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)
+  }
+}
+
+function instrumentStream ({ agent, shim, request, response, segment, transaction }) {
+  let err
+  let content
+  let modelVersion
+  let finishReason
+  let entireMessage = ''
+  shim.wrap(response, 'next', function wrapNext(shim, originalNext) {
+    return async function wrappedNext(...nextArgs) {
+      let result = {}
+      try {
+        result = await originalNext.apply(response, nextArgs)
+        if (result?.value?.text) {
+          modelVersion = result.value.modelVersion
+          content = result.value.candidates[0].content
+          entireMessage += result.value.text // readonly variable that equates to result.value.candidates[0].content.parts[0].text
+        }
+        if (result?.value?.candidates?.[0]?.finishReason) {
+          finishReason = result.value.candidates[0].finishReason
+        }
+      } catch (streamErr) {
+        err = streamErr
+        throw err
+      } finally {
+        // Update segment duration since we want to extend the
+        // time it took to handle the stream
+        segment.touch()
+
+        // result will be {value: undefined, done: true}
+        // when the stream is done, so we need to create
+        // a mock GenerateContentResponse object with
+        // the entire message
+        //
+        // also need to enter this block if there was an
+        // error, so we can record it
+        if (result?.done || err) {
+          if (content) {
+            content.parts[0].text = entireMessage
+            result.value = {
+              candidates: [
+                { content, finishReason }
+              ],
+              modelVersion
+            }
+          }
+
+          recordChatCompletionMessages({
+            agent: shim.agent,
+            shim,
+            segment,
+            transaction,
+            request,
+            response: result?.value,
+            err
+          })
+        }
+      }
+      return result
+    }
+  })
+}
+
+module.exports = function initialize(agent, googleGenAi, moduleName, shim) {
+  if (agent?.config?.ai_monitoring?.enabled !== true) {
+    shim.logger.debug('config.ai_monitoring.enabled is set to false.')
+    return
+  }
+
+  // Update the tracking metric name with the version of the library
+  // being instrumented. We do not have access to the version when
+  // initially declaring the variable.
+  TRACKING_METRIC = `${TRACKING_METRIC}/${shim.pkgVersion}`
+
+  const models = googleGenAi.Models
+
+  // Instruments chat completion creation
+  // and creates the LLM events
+  shim.record(models.prototype, 'generateContentInternal',
+    function wrapGenerateContent(shim, func, name, args) {
+      const [request] = args
+
+      return new RecorderSpec({
+        name: GEMINI.COMPLETION,
+        promise: true,
+        after({ error: err, result: response, segment, transaction }) {
+          recordChatCompletionMessages({
+            agent,
+            shim,
+            segment,
+            transaction,
+            request,
+            response,
+            err
+          })
+
+          addLlmMeta({ agent, transaction })
+        }
+      })
+    }
+  )
+
+  // Instruments chat completion streaming
+  // and creates the LLM events
+  shim.record(models.prototype, 'generateContentStreamInternal',
+    function wrapGenerateContentStream(shim, func, name, args) {
+      if (!agent.config.ai_monitoring.streaming.enabled) {
+        shim.logger.warn(
+          '`ai_monitoring.streaming.enabled` is set to `false`, stream will not be instrumented.'
+        )
+        agent.metrics.getOrCreateMetric(AI.STREAMING_DISABLED).incrementCallCount()
+        return
+      }
+      const [request] = args
+
+      return new RecorderSpec({
+        name: GEMINI.COMPLETION,
+        promise: true,
+        after({ result: response, segment, transaction }) {
+          instrumentStream({ agent, shim, request, response, segment, transaction })
+          addLlmMeta({ agent, transaction })
+        }
+      })
+    })
+
+  // Instruments embedding creation
+  // and creates LlmEmbedding event
+  shim.record(
+    models.prototype,
+    'embedContent',
+    function wrapEmbedContent(shim, func, name, args) {
+      const [request] = args
+
+      return new RecorderSpec({
+        name: GEMINI.EMBEDDING,
+        promise: true,
+        after({ error: err, result: response, segment, transaction }) {
+          addLlmMeta({ agent, transaction })
+
+          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 = {}
+          }
+
+          // Explicitly end segment to get consistent duration
+          // for both LLM events and the segment
+          segment.end()
+
+          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 })
+            shim.agent.errors.add(transaction, err, llmError)
+          }
+        }
+      })
+    }
+  )
+}

package/lib/instrumentation/openai.js

@@ -25,7 +25,7 @@ let TRACKING_METRIC = OPENAI.TRACKING_PREFIX
 
 /**
  * Checks if we should skip instrumentation.
- * Currently it checks if `ai_monitoring.enabled` is true
+ * Currently, it checks if `ai_monitoring.enabled` is true
  * and the package version >= 4.0.0
  *
  * @param {object} config agent config
@@ -172,14 +172,20 @@ function recordChatCompletionMessages({
   delete response.headers
 }
 
-/*
- * Chat completions create can return a stream once promise resolves
- * This wraps the iterator which is a generator function
+/**
+ * `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
+ * 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
- *
+ * 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
  */
 function instrumentStream({ agent, shim, request, response, segment, transaction }) {
   if (!agent.config.ai_monitoring.streaming.enabled) {
@@ -243,12 +249,13 @@ module.exports = function initialize(agent, openai, moduleName, shim) {
   // initially declaring the variable.
   TRACKING_METRIC = `${TRACKING_METRIC}/${shim.pkgVersion}`
 
-  /**
-   * Instrumentation is only done to get the response headers and attach
-   * to the active segment as openai hides the headers from the functions we are
-   * trying to instrument
-   */
-  shim.wrap(openai.prototype, 'makeRequest', function wrapRequest(shim, makeRequest) {
+  // openai@^5.0.0 uses a different prototype structure
+  const openaiClient = semver.gte(shim.pkgVersion, '5.0.0') ? openai.OpenAI : openai
+
+  // Instrumentation is only done to get the response headers and attach
+  // to the active segment as openai hides the headers from the functions we are
+  // trying to instrument
+  shim.wrap(openaiClient.prototype, 'makeRequest', function wrapRequest(shim, makeRequest) {
     return function wrappedRequest() {
       const apiKey = this.apiKey
       const request = makeRequest.apply(this, arguments)
@@ -266,14 +273,11 @@ module.exports = function initialize(agent, openai, moduleName, shim) {
     }
   })
 
-  /**
-   * Instruments chat completion creation
-   * and creates the LLM events
-   *
-   * **Note**: Currently only for promises. streams will come later
-   */
+  // Instruments chat completion creation
+  // and creates the LLM events
+  // **Note**: Currently only for promises. streams will come later
   shim.record(
-    openai.Chat.Completions.prototype,
+    openaiClient.Chat.Completions.prototype,
     'create',
     function wrapCreate(shim, create, name, args) {
       const [request] = args
@@ -308,12 +312,10 @@ module.exports = function initialize(agent, openai, moduleName, shim) {
     }
   )
 
-  /**
-   * Instruments embedding creation
-   * and creates LlmEmbedding event
-   */
+  // Instruments embedding creation
+  // and creates LlmEmbedding event
   shim.record(
-    openai.Embeddings.prototype,
+    openaiClient.Embeddings.prototype,
     'create',
     function wrapEmbeddingCreate(shim, embeddingCreate, name, args) {
       const [request] = args

package/lib/instrumentations.js

@@ -13,6 +13,7 @@ module.exports = function instrumentations() {
     '@azure/functions': { type: InstrumentationDescriptor.TYPE_GENERIC },
     '@elastic/elasticsearch': { type: InstrumentationDescriptor.TYPE_DATASTORE },
     '@opensearch-project/opensearch': { type: InstrumentationDescriptor.TYPE_DATASTORE },
+    '@google/genai': { type: InstrumentationDescriptor.TYPE_GENERIC },
     '@grpc/grpc-js': { module: './instrumentation/grpc-js' },
     '@hapi/hapi': { type: InstrumentationDescriptor.TYPE_WEB_FRAMEWORK },
     '@hapi/vision': { type: InstrumentationDescriptor.TYPE_WEB_FRAMEWORK },

package/lib/llm-events/error-message.js

@@ -23,9 +23,24 @@ module.exports = class LlmErrorMessage {
    * @param {LlmTool} [params.tool] Details about the tool event if it was a tool event.
    */
   constructor({ response, cause, summary, embedding, vectorsearch, tool } = {}) {
-    this['http.statusCode'] = response?.status ?? cause?.status
+    // For @google/genai only, cause does not have the `error` or `status` fields,
+    // but it does have `message` with the info we need. So, we need to parse
+    // the relevant fields from cause.message to get `status` and `error`.
+    let parsedError
+    const isGeminiVendor = embedding?.vendor === 'gemini' || summary?.vendor === 'gemini'
+    if (isGeminiVendor && cause?.message) {
+      try {
+        // Extract the JSON portion of the cause.message
+        const jsonStartIndex = cause.message.indexOf('{')
+        const jsonString = cause.message.substring(jsonStartIndex)
+        parsedError = JSON.parse(jsonString)?.error
+      } catch {
+        parsedError = undefined
+      }
+    }
+    this['http.statusCode'] = response?.status ?? cause?.status ?? parsedError?.code
     this['error.message'] = cause?.message
-    this['error.code'] = response?.code ?? cause?.error?.code
+    this['error.code'] = response?.code ?? cause?.error?.code ?? parsedError?.code
     this['error.param'] = response?.param ?? cause?.error?.param
     this.completion_id = summary?.id
     this.embedding_id = embedding?.id

package/lib/llm-events/google-genai/chat-completion-message.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const LlmEvent = require('./event')
+const { makeId } = require('../../util/hashes')
+
+module.exports = class LlmChatCompletionMessage extends LlmEvent {
+  constructor({
+    agent,
+    segment,
+    request = {},
+    response = {},
+    index = 0,
+    message,
+    completionId,
+    transaction
+  }) {
+    super({ agent, segment, request, response, transaction })
+    this.id = makeId(36)
+    // message?.role is only defined if the message is
+    // a response and it is always 'model'.
+    // request messages do not have a role
+    this.role = message?.role ?? 'user'
+    this.sequence = index
+    this.completion_id = completionId
+    const responseText = response?.text ?? response?.candidates?.[0]?.content?.parts?.[0]?.text
+    this.is_response = responseText === message?.parts?.[0]?.text
+
+    if (agent.config.ai_monitoring.record_content.enabled === true) {
+      this.content = this.is_response ? message?.parts?.[0]?.text : message
+    }
+
+    const tokenCB = agent.llm?.tokenCountCallback
+
+    if (typeof tokenCB === 'function') {
+      if (this.is_response) {
+        this.token_count = tokenCB(this['response.model'], this.content)
+      } else {
+        this.token_count = tokenCB(request.model, this.content)
+      }
+    }
+  }
+}

package/lib/llm-events/google-genai/chat-completion-summary.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+const LlmEvent = require('./event')
+
+module.exports = class LlmChatCompletionSummary extends LlmEvent {
+  constructor({ agent, segment, request = {}, response = {}, withError = false, transaction }) {
+    super({ agent, segment, request, response, responseAttrs: true, transaction })
+    this.error = withError
+    let requestMessagesLength = 0
+    if (Array.isArray(request?.contents)) {
+      requestMessagesLength = request.contents.length
+    } else if (typeof request?.contents === 'string') {
+      requestMessagesLength = 1
+    }
+    this['response.number_of_messages'] = requestMessagesLength + (response?.candidates?.length || 0)
+    this['response.choices.finish_reason'] = response?.candidates?.[0]?.finishReason
+    this['request.max_tokens'] = request.config?.maxOutputTokens
+    this['request.temperature'] = request.config?.temperature
+  }
+}

package/lib/llm-events/google-genai/embedding.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const LlmEvent = require('./event')
+
+class LlmEmbedding extends LlmEvent {
+  constructor({ agent, segment, request = {}, response = {}, withError = false, transaction }) {
+    super({ agent, segment, request, response, responseAttrs: true, transaction })
+    this.error = withError
+
+    if (agent.config.ai_monitoring.record_content.enabled === true) {
+      this.input = request.contents?.toString()
+    }
+    this.token_count = agent.llm?.tokenCountCallback?.(
+      this['request.model'],
+      request.contents?.toString()
+    )
+  }
+}
+
+module.exports = LlmEmbedding