feat: Added reduced type for partial granularity traces. (#3540)

Author: bizob2828

lib/spans/span-event-aggregator.js

@@ -22,6 +22,7 @@ class SpanEventAggregator extends EventAggregator {
 
     super(opts, agent)
     this.inProcessSpans = agent.config.distributed_tracing.in_process_spans.enabled
+    this.partialGranularityMode = agent.config.distributed_tracing?.sampler?.partial_granularity?.enabled === false ? null : agent.config.distributed_tracing?.sampler?.partial_granularity?.type
   }
 
   _toPayloadSync() {
@@ -75,7 +76,7 @@ class SpanEventAggregator extends EventAggregator {
 
       return false
     }
-    const span = SpanEvent.fromSegment({ segment, transaction, parentId, isRoot, inProcessSpans: this.inProcessSpans })
+    const span = SpanEvent.fromSegment({ segment, transaction, parentId, isRoot, inProcessSpans: this.inProcessSpans, partialGranularityMode: this.partialGranularityMode })
 
     if (span) {
       this.add(span, transaction.priority)

lib/spans/span-event.js

@@ -12,6 +12,36 @@ const { DESTINATIONS } = require('../config/attribute-filter')
 const { addSpanKind, isEntryPointSpan, reparentSpan, shouldCreateSpan, HTTP_LIBRARY, REGEXS, SPAN_KIND, CATEGORIES } = require('./helpers')
 const EMPTY_USER_ATTRS = Object.freeze(Object.create(null))
 const SERVER_ADDRESS = 'server.address'
+/**
+ * This keeps a static list of attributes that are used by
+ * one or more entity relationship rules to synthesize an entity relationship.
+ * Note: These attributes also have corresponding TraceSegment attributes
+ * as this list is checked before a span is made.  The ones that are TraceSegment
+ * attributes are noted in the comments. Any new span attributes being added must
+ * be checked to ensure those are what is getting assigned to the TraceSegment as well.
+ */
+const SPAN_ENTITY_RELATIONSHIP_ATTRIBUTES = [
+  'cloud.account.id',
+  'cloud.platform',
+  'cloud.region',
+  'cloud.resource_id',
+  'database_name', // gets mapped to `db.instance`
+  'db.instance',
+  'product', // gets mapped to `db.system`
+  'db.system',
+  'http.url',
+  'url', // gets mapped to `http.url`
+  'messaging.destination.name',
+  'messaging.system',
+  'peer.hostname',
+  'host', // gets mapped to `server.address`
+  'hostname', // gets mapped to `server.address`
+  'server.address',
+  'port', // gets mapped to `server.port`
+  'port_path_or_id', // gets mapped to `server.port`
+  'server.port',
+  'span.kind',
+]
 
 /**
  * All the intrinsic attributes for span events, regardless of kind.
@@ -31,6 +61,7 @@ class SpanIntrinsics {
     this.timestamp = null
     this.duration = null
     this['nr.entryPoint'] = null
+    this['nr.pg'] = null
     this['span.kind'] = null
     this.trustedParentId = null
     this.tracingVendors = null
@@ -67,6 +98,39 @@ class SpanEvent {
     return this.intrinsics
   }
 
+  addIntrinsics({ segment, spanContext, transaction, parentId, isRoot, inProcessSpans, entryPoint }) {
+    for (const [key, value] of Object.entries(spanContext.intrinsicAttributes)) {
+      this.addIntrinsicAttribute(key, value)
+    }
+
+    this.addIntrinsicAttribute('traceId', transaction.traceId)
+    this.addIntrinsicAttribute('transactionId', transaction.id)
+    this.addIntrinsicAttribute('sampled', transaction.sampled)
+    this.addIntrinsicAttribute('priority', transaction.priority)
+    this.addIntrinsicAttribute('name', segment.name)
+    this.addIntrinsicAttribute('guid', segment.id)
+    this.addIntrinsicAttribute('parentId', reparentSpan({ inProcessSpans, isRoot, segment, transaction, parentId }))
+
+    if (isRoot) {
+      this.addIntrinsicAttribute('trustedParentId', transaction.traceContext.trustedParentId)
+      if (transaction.traceContext.tracingVendors) {
+        this.addIntrinsicAttribute('tracingVendors', transaction.traceContext.tracingVendors)
+      }
+    }
+
+    // Only set this if it will be `true`. Must be `null` otherwise.
+    if (entryPoint) {
+      this.addIntrinsicAttribute('nr.entryPoint', true)
+      if (transaction.isPartialTrace) {
+        this.addIntrinsicAttribute('nr.pg', true)
+      }
+    }
+
+    // Timestamp in milliseconds, duration in seconds. Yay consistency!
+    this.addIntrinsicAttribute('timestamp', segment.timer.start)
+    this.addIntrinsicAttribute('duration', segment.timer.getDurationInMillis() / 1000)
+  }
+
   addIntrinsicAttribute(key, value) {
     this.intrinsics[key] = value
   }
@@ -83,6 +147,66 @@ class SpanEvent {
     return HttpSpanEvent
   }
 
+  static isExitSpan(segment) {
+    return REGEXS.CLIENT.EXTERNAL.test(segment.name) || REGEXS.CLIENT.DATASTORE.test(segment.name) || REGEXS.PRODUCER.test(segment.name)
+  }
+
+  static isLlmSpan(segment) {
+    return segment.name.startsWith('Llm/')
+  }
+
+  /**
+   * Filters attributes for partial trace span events based on a given mode.
+   * The rules are as such:
+   *  - If not a partial trace, return all attributes.
+   *  - If an entry point span, return all attributes.
+   *  - If an LLM span, return all attributes.
+   *  - If not an exit span, return no attributes.
+   *  - If mode is 'reduced' and there are entity relationship attributes, return all attributes.
+   *  - Otherwise, return no attributes.
+   *
+   *  @param {object} params to function
+   *  @param {TraceSegment} params.segment segment to filter attributes from
+   *  @param {SpanContext} params.spanContext span context to filter attributes from
+   *  @param {boolean} params.entryPoint whether the span is an entry point
+   *  @param {string} params.partialGranularityMode mode of partial trace ('reduced', 'essential', 'compact')
+   *  @param {boolean} params.isPartialTrace whether the trace is a partial trace
+   *  @returns {object} { attributes, customAttributes, dropSpan: boolean }
+   */
+  static filterPartialTraceAttributes({ segment, spanContext, entryPoint, partialGranularityMode, isPartialTrace }) {
+    const attributes = segment.attributes.get(DESTINATIONS.SPAN_EVENT)
+    const customAttributes = spanContext.customAttributes.get(DESTINATIONS.SPAN_EVENT)
+    if (!isPartialTrace || entryPoint || SpanEvent.isLlmSpan(segment)) {
+      return { attributes, customAttributes, dropSpan: false }
+    }
+
+    if (!SpanEvent.isExitSpan(segment)) {
+      return { dropSpan: true }
+    }
+
+    const attrKeys = Object.keys(attributes)
+    const entityRelationshipAttrs = SPAN_ENTITY_RELATIONSHIP_ATTRIBUTES.filter((item) => attrKeys.includes(item))
+    if (partialGranularityMode === 'reduced') {
+      if (entityRelationshipAttrs.length > 0) {
+        return { attributes, customAttributes, dropSpan: false }
+      }
+    }
+
+    return { dropSpan: true }
+  }
+
+  static createSpan({ segment, attributes, customAttributes }) {
+    let span = null
+    if (HttpSpanEvent.testSegment(segment)) {
+      span = new HttpSpanEvent(attributes, customAttributes)
+    } else if (DatastoreSpanEvent.testSegment(segment)) {
+      span = new DatastoreSpanEvent(attributes, customAttributes)
+    } else {
+      span = new SpanEvent(attributes, customAttributes)
+    }
+    return span
+  }
+
   /**
    * Constructs a `SpanEvent` from the given segment.
    *
@@ -95,9 +219,10 @@ class SpanEvent {
    * @param {?string} [params.parentId] ID of the segment's parent.
    * @param {boolean} [params.isRoot] if segment is root segment; defaults to `false`
    * @param {boolean} params.inProcessSpans if the segment is in-process, create span
+   * @param {string} params.partialGranularityMode mode of partial trace ('reduced', 'essential', 'compact')
    * @returns {SpanEvent} The constructed event.
    */
-  static fromSegment({ segment, transaction, parentId = null, isRoot = false, inProcessSpans }) {
+  static fromSegment({ segment, transaction, parentId = null, isRoot = false, inProcessSpans, partialGranularityMode }) {
     const entryPoint = isEntryPointSpan({ segment, transaction })
     if (!inProcessSpans && !shouldCreateSpan({ entryPoint, segment, transaction })) {
       return null
@@ -116,46 +241,14 @@ class SpanEvent {
       }
     }
 
-    const attributes = segment.attributes.get(DESTINATIONS.SPAN_EVENT)
-
-    const customAttributes = spanContext.customAttributes.get(DESTINATIONS.SPAN_EVENT)
-
-    let span = null
-    if (HttpSpanEvent.testSegment(segment)) {
-      span = new HttpSpanEvent(attributes, customAttributes)
-    } else if (DatastoreSpanEvent.testSegment(segment)) {
-      span = new DatastoreSpanEvent(attributes, customAttributes)
-    } else {
-      span = new SpanEvent(attributes, customAttributes)
-    }
-
-    for (const [key, value] of Object.entries(spanContext.intrinsicAttributes)) {
-      span.intrinsics[key] = value
-    }
-
-    span.intrinsics.traceId = transaction.traceId
-    span.intrinsics.guid = segment.id
-    span.intrinsics.parentId = reparentSpan({ inProcessSpans, isRoot, segment, transaction, parentId })
-    span.intrinsics.transactionId = transaction.id
-    span.intrinsics.sampled = transaction.sampled
-    span.intrinsics.priority = transaction.priority
-    span.intrinsics.name = segment.name
-
-    if (isRoot) {
-      span.intrinsics.trustedParentId = transaction.traceContext.trustedParentId
-      if (transaction.traceContext.tracingVendors) {
-        span.intrinsics.tracingVendors = transaction.traceContext.tracingVendors
-      }
-    }
-
-    // Only set this if it will be `true`. Must be `null` otherwise.
-    if (entryPoint) {
-      span.intrinsics['nr.entryPoint'] = true
+    const { attributes, customAttributes, dropSpan } = SpanEvent.filterPartialTraceAttributes({ spanContext, entryPoint, segment, partialGranularityMode, isPartialTrace: transaction.isPartialTrace })
+    // If attributes were stripped out due to partial trace filtering, do not create span.
+    if (dropSpan) {
+      return null
     }
 
-    // Timestamp in milliseconds, duration in seconds. Yay consistency!
-    span.intrinsics.timestamp = segment.timer.start
-    span.intrinsics.duration = segment.timer.getDurationInMillis() / 1000
+    const span = SpanEvent.createSpan({ segment, attributes, customAttributes })
+    span.addIntrinsics({ segment, spanContext, transaction, parentId, isRoot, inProcessSpans, entryPoint })
 
     addSpanKind({ segment, span })
     return span
@@ -196,9 +289,9 @@ class HttpSpanEvent extends SpanEvent {
   constructor(attributes, customAttributes) {
     super(attributes, customAttributes)
 
-    this.intrinsics.category = CATEGORIES.HTTP
-    this.intrinsics.component = attributes.library || HTTP_LIBRARY
-    this.intrinsics['span.kind'] = SPAN_KIND.CLIENT
+    this.addIntrinsicAttribute('category', CATEGORIES.HTTP)
+    this.addIntrinsicAttribute('component', attributes.library || HTTP_LIBRARY)
+    this.addIntrinsicAttribute('span.kind', SPAN_KIND.CLIENT)
 
     if (attributes.library) {
       attributes.library = null
@@ -236,11 +329,11 @@ class DatastoreSpanEvent extends SpanEvent {
   constructor(attributes, customAttributes) {
     super(attributes, customAttributes)
 
-    this.intrinsics.category = CATEGORIES.DATASTORE
-    this.intrinsics['span.kind'] = SPAN_KIND.CLIENT
+    this.addIntrinsicAttribute('category', CATEGORIES.DATASTORE)
+    this.addIntrinsicAttribute('span.kind', SPAN_KIND.CLIENT)
 
     if (attributes.product) {
-      this.intrinsics.component = attributes.product
+      this.addIntrinsicAttribute('component', attributes.product)
       this.addAttribute('db.system', attributes.product)
       attributes.product = null
     }