feat: Added compact mode for span links (#3681)

Author: svetlanabrennan

lib/spans/span-event.js

@@ -318,6 +318,14 @@ class SpanEvent {
    *  @returns {SpanEvent|null} the span after applying the rules, or null if dropped
    */
   applyPartialTraceRules({ isEntry, partialTrace }) {
+    // in essential and compact mode - we need to remove the non intrinsic attributes from span links early in this process because there can be an entry span,
+    // llm span exit span or span with no entity relationship attributes can have non intrinsics on it.
+    if (partialTrace.type !== PARTIAL_TYPES.REDUCED) {
+      for (const link of this.spanLinks) {
+        link.removeNonIntrinsicsAttrs()
+      }
+    }
+
     if (isEntry) {
       this.addIntrinsicAttribute('nr.pg', true)
       logger.trace('Span %s is an entry point, keeping span unchanged.', this.intrinsics.name)

lib/spans/span-link.js

@@ -86,6 +86,11 @@ class SpanLink {
       filterNulls(this.agentAttributes.get(DESTINATIONS.TRANS_SEGMENT))
     ]
   }
+
+  removeNonIntrinsicsAttrs() {
+    this.userAttributes = Object.create(null)
+    this.agentAttributes = Object.create(null)
+  }
 }
 
 function filterNulls(inputObj) {

lib/transaction/trace/partial-trace.js

@@ -7,8 +7,7 @@
 
 const logger = require('../../logger').child({ component: 'partial-trace' })
 const { PARTIAL_TRACE } = require('../../metrics/names')
-const { Attributes } = require('#agentlib/attributes.js')
-
+const { SPAN_EVENTS } = require('#agentlib/metrics/names.js')
 /**
  * A PartialTrace manages span processing for partial granularity traces.
  * It handles span reparenting, compaction logic, and finalization of span events.
@@ -58,6 +57,7 @@ class PartialTrace {
    * Runs a span through partial tracing rules.
    * If the span is null, it indicates that the span was dropped,
    * and we must keep track of its id and parentId for potential reparenting.
+   * Also reparents span links from dropped spans.
    *
    * @param {object} params to function
    * @param {string} params.span to apply partial rules to
@@ -66,16 +66,15 @@ class PartialTrace {
   addSpan({ span, isEntry }) {
     const id = span.id
     const parentId = span.parentId
+
+    // capture necessary information for reparenting span links before span is potentially dropped
     const spanLinks = span.spanLinks
+    const exitSpan = span.isExitSpan
+    const hasEntityAttrs = span.hasEntityRelationshipAttrs
+
     span = span.applyPartialTraceRules({ isEntry, partialTrace: this })
     this.createMetrics(!!span)
 
-    if (spanLinks && spanLinks.length > 0) {
-      if (this.type === 'essential') {
-        this.removeNonIntrinsicsAttrs(spanLinks)
-      }
-    }
-
     if (span) {
       // span was not dropped, add to trace until all spans have been processed
       this.spans.push(span)
@@ -88,41 +87,34 @@ class PartialTrace {
 
       // span was dropped but we still need to move its span links to the last kept span
       // spanLinks were captured before the span was dropped
-      if (spanLinks && spanLinks.length > 0) {
-        this.reparentSpanLinks(spanLinks)
-      }
+      this.reparentSpanLinks(this.spans.at(-1), spanLinks)
+    } else if ((this.type === 'compact') && (!exitSpan || !hasEntityAttrs)) {
+      // we still need to reparent links for dropped spans in compact mode that are not exit
+      // span or spans without entity relationship attributes
+      this.reparentSpanLinks(this.spans.at(-1), spanLinks)
     }
   }
 
   /**
-   * Iterates over the span links from a span and removes all non-intrinsic attributes.
-   *
-   * @param {SpanLink[]} spanLinks an array of span links to reparent to last kept span
-   */
-  removeNonIntrinsicsAttrs(spanLinks) {
-    for (const link of spanLinks) {
-      link.userAttributes = new Attributes({ scope: Attributes.SCOPE_SEGMENT })
-      link.agentAttributes = new Attributes({ scope: Attributes.SCOPE_SEGMENT })
-    }
-  }
-
-  /**
-   * Iterates over the span links from a dropped span and reassigns them to the last kept span.
+   * Iterates over the span links from a dropped span and reassigns them to the span to reparent to.
    * The id intrinsic attribute will also be updated to the value of the last kept span id.
    *
-   * @param {SpanLink[]} spanLinks an array of span links to reparent to last kept span
+   * @param {SpanEvent} span the span to reparent span links to
+   * @param {SpanLink[]} spanLinksToReparent an array of span links to reparent to last kept span
    */
-  reparentSpanLinks(spanLinks) {
-    const lastSpan = this.spans.at(-1)
-
+  reparentSpanLinks(span, spanLinksToReparent = []) {
     // The id intrinsics attribute needs to be updated to equal the id of the new span the
     // span links are moving to.
-    for (const link of spanLinks) {
-      link.intrinsics.id = lastSpan.id
-    }
+    for (const link of spanLinksToReparent) {
+      if (span.spanLinks.length === 100) {
+        logger.trace('Span links limit reached. Not moving additional span links.')
+        this.transaction.agent.metrics.getOrCreateMetric(SPAN_EVENTS.LINKS_DROPPED).incrementCallCount()
+        return
+      }
 
-    // move the span links events to the last kept span
-    Array.prototype.push.apply(lastSpan.spanLinks, spanLinks)
+      link.intrinsics.id = span.id
+      span.spanLinks.push(link)
+    }
   }
 
   /**
@@ -195,7 +187,7 @@ class PartialTrace {
   /**
    * Checks if span was the retained exit span for a given entity and it has other spans that talked to the same
    * entity. It will then sort all timestamps for spans that got dropped and calculate the `nr.durations` and assign
-   * `nr.ids` for all dropped spans to same entity.
+   * `nr.ids` for all dropped spans to same entity. It will also reparent the span links from dropped spans to the retained exit span.
    *
    * @param {SpanEvent} span to check if it has to calculate `nr.durations` and `nr.ids`
    */
@@ -221,7 +213,8 @@ class PartialTrace {
       totalDuration: 0,
       currentStart: null,
       currentEnd: null,
-      errorSpan: null
+      errorSpan: null,
+      spanLinks: []
     }
 
     // timestamps must be sorted to accurately calculate overlapping durations
@@ -238,13 +231,17 @@ class PartialTrace {
         } else {
           meta.droppedIds++
         }
+
+        Array.prototype.push.apply(meta.spanLinks, sameEntitySpan.spanLinks)
       }
 
       this.compactionError(meta, sameEntitySpan)
       this.calculateDuration(meta, sameEntitySpan)
     }
 
     this.assignCompactAttrs({ span, meta })
+
+    this.reparentSpanLinks(span, meta.spanLinks)
   }
 
   assignCompactAttrs({ span, meta }) {

test/unit/spans/helpers.js

@@ -0,0 +1,142 @@
+/*
+ * Copyright 2025 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+'use strict'
+
+const SpanLink = require('#agentlib/spans/span-link.js')
+const SpanEvent = require('#agentlib/spans/span-event.js')
+const sinon = require('sinon')
+const assert = require('node:assert')
+
+const TIMESTAMP = 1765285200000 // 2025-12-09T09:00:00.000-04:00
+
+function setupPartialTransaction(tx, partialType) {
+  tx.priority = 42
+  tx.sampled = true
+  tx.partialType = partialType
+  tx.createPartialTrace()
+}
+
+function createSpanLink({ segment, spanId, traceId, linkSpanId, linkTraceId, testAttr }) {
+  const link = new SpanLink({
+    link: {
+      attributes: { test: testAttr },
+      context: { spanId: linkSpanId, traceId: linkTraceId }
+    },
+    spanContext: {
+      spanId,
+      traceId
+    },
+    timestamp: TIMESTAMP
+  })
+  segment.spanLinks.push(link)
+  return link
+}
+
+function addSegment({ spanEventAggregator, tx, segment, parentId = '1', isEntry = false }) {
+  spanEventAggregator.addSegment({ segment, transaction: tx, parentId, isEntry })
+}
+
+function stubEntityRelationship(hasEntity) {
+  return sinon.stub(SpanEvent.prototype, 'hasEntityRelationshipAttrs').get(() => hasEntity)
+}
+
+function createSegment(agent, id, name, parent, tx) {
+  return agent.tracer.createSegment({
+    id,
+    name,
+    parent,
+    transaction: tx
+  })
+}
+
+function setupPartialTrace({ agent, partialType, tx, addRootSpanLink = false, add99SpanLinks = false, addExitSpan = false, numOfChildSegments = 2 }) {
+  setupPartialTransaction(tx, partialType)
+
+  // setup root segment and span links on root if needed
+  const rootSegment = agent.tracer.getSegment()
+
+  if (add99SpanLinks) {
+    for (let i = 0; i < 99; i += 1) {
+      rootSegment.addSpanLink({ fake: 'link' })
+    }
+  }
+
+  if (addRootSpanLink) {
+    createSpanLink({ segment: rootSegment, spanId: rootSegment.id, traceId: 'trace1', linkSpanId: rootSegment.id, linkTraceId: 'trace1', testAttr: 'rootTest' })
+  }
+
+  // setup child 1 segment with span link
+  const child1Name = addExitSpan ? 'MessageBroker/api.example.com/users' : 'child1-segment'
+  const child1Segment = createSegment(agent, 'child1', child1Name, rootSegment, tx)
+  createSpanLink({ segment: child1Segment, spanId: 'span1', traceId: 'trace1', linkSpanId: 'parent1', linkTraceId: 'trace1', testAttr: 'test1' })
+
+  if (numOfChildSegments === 1) {
+    return { rootSegment, child1Segment }
+  }
+
+  // setup child 2 segment with span links if needed
+  const child2Segment = createSegment(agent, 'child2', 'child2-segment', child1Segment, tx)
+  createSpanLink({ segment: child2Segment, spanId: 'span2', traceId: 'trace2', linkSpanId: 'parent2', linkTraceId: 'trace1', testAttr: 'test2' })
+
+  return { rootSegment, child1Segment, child2Segment }
+}
+
+function setupPartialTraceForCompactCompression(agent, tx) {
+  setupPartialTransaction(tx, 'compact')
+
+  const reparentSpanLinkSpy = sinon.spy(tx.partialTrace, 'reparentSpanLinks')
+  const rootSegment = agent.tracer.getSegment()
+
+  // first exit span to a message broker
+  const child1Segment = createSegment(agent, 'child1', 'MessageBroker/api.example.com/users', rootSegment, tx)
+
+  // entry span to another service
+  const child2Segment = createSegment(agent, 'child2', 'child2-segment', child1Segment, tx)
+
+  // second exit span to the same message broker
+  const child3Segment = createSegment(agent, 'child3', 'MessageBroker/api.example.com/users', rootSegment, tx)
+
+  // entry span to another service
+  const child4Segment = createSegment(agent, 'child4', 'child4-segment', child3Segment, tx)
+
+  createSpanLink({ segment: child1Segment, spanId: 'span1', traceId: 'trace1', linkSpanId: 'parent1', linkTraceId: 'trace1', testAttr: 'test1' })
+  createSpanLink({ segment: child3Segment, spanId: 'span1', traceId: 'trace1', linkSpanId: 'parent1', linkTraceId: 'trace1', testAttr: 'test2' })
+
+  return { rootSegment, child1Segment, child2Segment, child3Segment, child4Segment, reparentSpanLinkSpy }
+}
+
+function addSegmentsForCompactCompression({ spanEventAggregator, tx, segments }) {
+  addSegment({ spanEventAggregator, tx, segment: segments.rootSegment, isEntry: true })
+  tx.baseSegment = segments.rootSegment
+
+  // simulate that the segment has entity relationship attrs to keep the span
+  const hasEntityStub = stubEntityRelationship(true)
+
+  addSegment({ spanEventAggregator, tx, segment: segments.child1Segment, parentId: segments.rootSegment.id })
+  addSegment({ spanEventAggregator, tx, segment: segments.child2Segment, parentId: segments.child1Segment.id, isEntry: true })
+  addSegment({ spanEventAggregator, tx, segment: segments.child3Segment, parentId: segments.rootSegment.id })
+  addSegment({ spanEventAggregator, tx, segment: segments.child4Segment, parentId: segments.child3Segment.id, isEntry: true })
+  hasEntityStub.restore()
+}
+
+function assertSpanLinkAttributes(spanLinks) {
+  for (let i = 0; i < spanLinks.length; i += 1) {
+    const link = spanLinks[i]
+    assert.equal(Object.keys(link.userAttributes).length, 0)
+    assert.equal(Object.keys(link.agentAttributes).length, 0)
+  }
+}
+
+module.exports = {
+  setupPartialTrace,
+  stubEntityRelationship,
+  assertSpanLinkAttributes,
+  addSegment,
+  createSegment,
+  createSpanLink,
+  setupPartialTraceForCompactCompression,
+  addSegmentsForCompactCompression
+}