newrelic 13.2.1 → 13.3.0

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
+}

package/lib/transaction/index.js

@@ -16,8 +16,11 @@ const Timer = require('../timer')
 const Trace = require('./trace')
 const synthetics = require('../synthetics')
 const urltils = require('../util/urltils')
+const cat = require('../util/cat')
 const TraceContext = require('./tracecontext').TraceContext
 const Logs = require('./logs')
+const headerAttributes = require('../header-attributes')
+const headerProcessing = require('../header-processing')
 const DT_ACCEPT_PAYLOAD_EXCEPTION_METRIC = 'DistributedTrace/AcceptPayload/Exception'
 const DT_ACCEPT_PAYLOAD_PARSE_EXCEPTION_METRIC = 'DistributedTrace/AcceptPayload/ParseException'
 const REQUEST_PARAMS_PATH = 'request.parameters.'
@@ -119,7 +122,6 @@ function Transaction(agent, traceId) {
   this.syntheticsData = null
   this.syntheticsInfoData = null
   this.url = null
-  this.parsedUrl = null
   this.verb = null
   this.baseSegment = null
   this.type = TYPES.WEB
@@ -317,8 +319,9 @@ Transaction.prototype.setPartialName = function setPartialName(name) {
  *  boolean flag in `ignore`.
  */
 Transaction.prototype._partialNameFromUri = _partialNameFromUri
-function _partialNameFromUri(requestUrl, status) {
-  const scrubbedUrl = urltils.scrub(requestUrl)
+function _partialNameFromUri() {
+  const scrubbedUrl = this.url
+  const status = this.statusCode
 
   // 0. If there is a name in the name-state stack, use it.
   let partialName = this._partialName
@@ -386,21 +389,69 @@ Transaction.prototype.isIgnored = function getIgnore() {
 }
 
 /**
- * Derives the transaction's name from the given URL and status code.
+ * Finalize a web transaction. This includes naming the transaction, collecting
+ * response headers, and ending the transaction and its base segment.
+ *
+ * @param {object} params The parameters for finalizing the transaction.
+ * @param {number} params.statusCode The response status code.
+ * @param {string} [params.statusMessage] The response status message.
+ * @param {object} [params.headers] The response headers.
+ * @param {Boolean} params.end Whether to end the transaction and baseSegment.
+ */
+Transaction.prototype.finalizeWeb = function finalizeWeb({ statusCode, statusMessage, headers, end }) {
+  // Naming must happen before the segment and transaction are ended
+  // because metrics recording depends on naming's side effects.
+  this.finalizeNameFromWeb(statusCode)
+  if (statusCode != null) {
+    const responseCode = String(statusCode)
+
+    if (/^\d+$/.test(responseCode)) {
+      this.trace.attributes.addAttribute(
+        DESTS.TRANS_COMMON,
+        'http.statusCode',
+        responseCode
+      )
+
+      this.baseSegment.addSpanAttribute('http.statusCode', responseCode)
+    }
+  }
+
+  if (statusMessage !== undefined) {
+    this.trace.attributes.addAttribute(
+      DESTS.TRANS_COMMON,
+      'http.statusText',
+      statusMessage
+    )
+
+    this.baseSegment.addSpanAttribute('http.statusText', statusMessage)
+  }
+
+  if (headers) {
+    headerAttributes.collectResponseHeaders(headers, this)
+  }
+
+  if (end) {
+    // And we are done! End the segment and transaction.
+    this.baseSegment.end()
+    this.end()
+  }
+}
+
+/**
+ * Derives the transaction's name from `transaction.url` and status code.
  *
  * The transaction's name will be set after this as well as its ignored status
  * based on the derived name.
  *
- * @param {string} requestURL - The URL to derive the request's name and status from.
  * @param {number} statusCode - The response status code.
  */
-Transaction.prototype.finalizeNameFromUri = finalizeNameFromUri
+Transaction.prototype.finalizeNameFromWeb = finalizeNameFromWeb
 
-function finalizeNameFromUri(requestURL, statusCode) {
+function finalizeNameFromWeb(statusCode) {
   if (logger.traceEnabled()) {
     logger.trace(
       {
-        requestURL,
+        requestURL: this.url,
         statusCode,
         transactionId: this.id,
         transactionName: this.name
@@ -409,10 +460,6 @@ function finalizeNameFromUri(requestURL, statusCode) {
     )
   }
 
-  if (!this.agent.config.url_obfuscation.enabled) {
-    this.url = urltils.scrub(requestURL)
-  }
-
   this.statusCode = statusCode
   this.name = this.getFullName()
 
@@ -426,7 +473,16 @@ function finalizeNameFromUri(requestURL, statusCode) {
     this.ignore = this.forceIgnore
   }
 
-  this.baseSegment && this._markAsWeb(requestURL)
+  const obfuscatedUrl = urltils.obfuscatePath(this.agent.config, this.url)
+  this.url = obfuscatedUrl
+  // URL is sent as an agent attribute with transaction events
+  this.trace.attributes.addAttribute(
+    DESTS.TRANS_EVENT | DESTS.ERROR_EVENT,
+    'request.uri',
+    obfuscatedUrl
+  )
+
+  this?.baseSegment?.markAsWeb(this, obfuscatedUrl)
 
   this._copyNameToActiveSpan(this.name)
 
@@ -471,37 +527,6 @@ Transaction.prototype._copyNameToActiveSpan = function _copyNameToActiveSpan(nam
   spanContext.addIntrinsicAttribute('transaction.name', name)
 }
 
-/**
- * Copies final base segment parameters to trace attributes before reapplying
- * them to the segment.
- *
- * Handles adding query parameters to `request.parameter.*` attributes
- *
- * @param {string} rawURL The URL, as it came in, for parameter extraction.
- */
-Transaction.prototype._markAsWeb = function _markAsWeb(rawURL) {
-  // Because we are assured we have the URL here, lets grab query params.
-  const params = urltils.parseParameters(rawURL)
-  for (const key in params) {
-    if (props.hasOwn(params, key)) {
-      this.trace.attributes.addAttribute(DESTS.NONE, REQUEST_PARAMS_PATH + key, params[key])
-
-      const segment = this.agent.tracer.getSegment()
-
-      if (!segment) {
-        logger.trace(
-          'Active segment not available, not adding request.parameters span attribute for %s',
-          key
-        )
-      } else {
-        segment.attributes.addAttribute(DESTS.NONE, REQUEST_PARAMS_PATH + key, params[key])
-      }
-    }
-  }
-
-  this.baseSegment.markAsWeb(this)
-}
-
 /**
  * Sets the transaction's name and determines if it will be ignored.
  *
@@ -514,7 +539,7 @@ Transaction.prototype.finalizeName = function finalizeName(name) {
   // If no name is given, and this is a web transaction with a url, then
   // finalize the name using the stored url.
   if (name == null && this.isWeb() && this.url) {
-    return this.finalizeNameFromUri(this.url, this.statusCode)
+    return this.finalizeNameFromWeb(this.statusCode)
   }
 
   // this may seem out of place but certain API methods
@@ -566,7 +591,7 @@ Transaction.prototype.finalizeName = function finalizeName(name) {
  */
 Transaction.prototype.getName = function getName() {
   if (this.isWeb() && this.url) {
-    const finalName = this._partialNameFromUri(this.url, this.statusCode)
+    const finalName = this._partialNameFromUri()
     if (finalName.ignore) {
       this.ignore = true
     }
@@ -1427,18 +1452,16 @@ Transaction.prototype.addRequestParameters = addRequestParameters
  * @param {Object<string, string>} requestParameters of the request object
  */
 function addRequestParameters(requestParameters) {
-  for (const key in requestParameters) {
-    if (props.hasOwn(requestParameters, key)) {
-      this.trace.attributes.addAttribute(
-        DESTS.NONE,
-        REQUEST_PARAMS_PATH + key,
-        requestParameters[key]
-      )
+  for (const [key, value] of Object.entries(requestParameters)) {
+    this.trace.attributes.addAttribute(
+      DESTS.NONE,
+      REQUEST_PARAMS_PATH + key,
+      value
+    )
 
-      const segment = this.baseSegment
+    const segment = this.baseSegment
 
-      segment.attributes.addAttribute(DESTS.NONE, REQUEST_PARAMS_PATH + key, requestParameters[key])
-    }
+    segment.attributes.addAttribute(DESTS.NONE, REQUEST_PARAMS_PATH + key, value)
   }
 }
 
@@ -1453,4 +1476,82 @@ Transaction.prototype.incrementCounters = function incrementCounters() {
   this.agent.incrementCounters()
 }
 
+/**
+ * Initializes a web transaction with request information:
+ *  Assigns type(web), verb, url, port attributes on transaction.
+ *  Collects request headers as attributes on the transaction.
+ *  Applies user naming rules to the transaction.
+ *  Calculates queue time if possible.
+ *  Assigns synthetics information if present.
+ *  Adds distributed trace or cat headers if present.
+ *
+ * @param {object} params - Parameters to initialize the web transaction.
+ * @param {string} params.absoluteUrl - Full URL of the request.
+ * @param {string} params.method - HTTP method of the request.
+ * @param {number} params.port - Port of the request.
+ * @param {object} [params.headers] - HTTP headers of the request.
+ * @param {string} [params.transport] - Transport type that delivered the request.
+ */
+Transaction.prototype.initializeWeb = function initializeWeb({ absoluteUrl, method, port, headers = {}, transport }) {
+  this.type = TYPES.WEB
+  headerAttributes.collectRequestHeaders(headers, this)
+
+  if (method != null) {
+    this.trace.attributes.addAttribute(DESTS.TRANS_COMMON, 'request.method', method)
+    this.baseSegment.addSpanAttribute('request.method', method)
+    this.verb = method
+  }
+
+  this.port = port
+
+  // the error tracer needs a URL for tracing, even though naming overwrites
+  try {
+    const parsedUrl = new URL(absoluteUrl)
+    const data = urltils.scrubAndParseParameters(parsedUrl)
+    this.url = data.path
+    this.addRequestParameters(data.parameters)
+  } catch (err) {
+    logger.debug('Could not parse URL %s: %s', absoluteUrl, err.message)
+    this.url = '/unknown'
+  }
+
+  // need to set any config-driven names early for RUM
+  logger.trace({ url: this.url, transaction: this.id },
+    'Appplying user naming rules for RUM.')
+
+  this.applyUserNamingRules(this.url)
+
+  const queueTimeStamp = headerProcessing.getQueueTime(logger, headers)
+  if (queueTimeStamp) {
+    this.queueTime = Date.now() - queueTimeStamp
+  }
+
+  synthetics.assignHeadersToTransaction(this.agent.config, this, headers)
+  this.addDtCatHeaders({ headers, transport })
+}
+
+/**
+ * Handles accepting upstream DT headers(traceparent/tracestate or newrelic) if present and DT is enabled.
+ * If CAT is enabled, handles accepting CAT headers and assigns to transaction.
+ *
+ * @param {object} params - Parameters for adding DT or CAT headers.
+ * @param {object} params.headers - HTTP headers of the request(must be lower-cased, by default http instrumentation has headers lower case, other libraries must pass this in lowercased).
+ * @param {string} [params.transport] - Transport type that delivered the request.
+ */
+Transaction.prototype.addDtCatHeaders = function addDtCatHeaders({ headers, transport }) {
+  if (this.agent.config.distributed_tracing.enabled) {
+    // Node http request headers are automatically lowercase
+    // need to pass in lower case for other instrumentation
+    this.acceptDistributedTraceHeaders(transport, headers)
+  } else if (this.agent.config.cross_application_tracer.enabled) {
+    const { id, transactionId } = cat.extractCatHeaders(headers)
+    const { externalId, externalTransaction } = cat.parseCatData(
+      id,
+      transactionId,
+      this.agent.config.encoding_key
+    )
+    cat.assignCatToTransaction(externalId, externalTransaction, this)
+  }
+}
+
 module.exports = Transaction

package/lib/transaction/trace/segment.js

@@ -133,13 +133,14 @@ TraceSegment.prototype.setNameFromTransaction = function setNameFromTransaction(
 /**
  * Once a transaction is named, the web segment also needs to be updated to
  * match it (which implies this method must be called subsequent to
- * transaction.finalizeNameFromUri). To properly name apdex metrics during metric
+ * transaction.finalizeNameFromWeb). To properly name apdex metrics during metric
  * recording, it's also necessary to copy the transaction's partial name. And
  * finally, marking the trace segment as being a web segment copies the
  * segment's parameters onto the transaction.
  * @param {Transaction} transaction The transaction to which this segment will be bound.
+ * @param obfuscatedUrl
  */
-TraceSegment.prototype.markAsWeb = function markAsWeb(transaction) {
+TraceSegment.prototype.markAsWeb = function markAsWeb(transaction, obfuscatedUrl) {
   this.setNameFromTransaction(transaction)
 
   const traceAttrs = transaction.trace.attributes.get(DESTINATIONS.TRANS_TRACE)
@@ -148,6 +149,8 @@ TraceSegment.prototype.markAsWeb = function markAsWeb(transaction) {
       this.addAttribute(key, traceAttrs[key])
     }
   })
+
+  this.addSpanAttribute('request.uri', obfuscatedUrl)
 }
 
 /**