feat: Add callback option to config to capture context when starting transactions and spans

docs/configuration.asciidoc

@@ -410,3 +410,33 @@ This is useful on scenarios where the APM server is behind a reverse proxy that
 
 NOTE: If APM Server is deployed in an origin different than the page’s origin, you will need to
 <<configuring-cors, configure Cross-Origin Resource Sharing (CORS)>>.
+
+
+[function]
+[[transaction-context-callback]]
+==== `transactionContextCallback`
+
+* *Type:* Function
+* *Default:* `null`
+
+`transactionContextCallback` allows the agent to specify a function to be called when starting automatically instrumented transactions and spans and return
+context to be set as tags. This enables the agent to capture the context when instrumented events are fired from files which do not import the RUM agent library.
+
+The following example illustrates an example which captures the stack trace:
+
+[source,js]
+----
+var options = {
+  transactionContextCallback: () => {
+    let stack
+    try {
+      throw new Error('')
+    }
+    catch (error) {
+      stack = (error as Error).stack || ''
+    }
+    stack = stack.split('\n').map(function (line) { return line.trim(); })
+    return { stack };
+  }
+}
+----

packages/rum-core/src/common/config-service.js

@@ -94,7 +94,8 @@ class Config {
       context: {},
       session: false,
       apmRequest: null,
-      sendCredentials: false
+      sendCredentials: false,
+      transactionContextCallback: null
     }
 
     this.events = new EventHandler()

packages/rum-core/src/performance-monitoring/transaction-service.js

@@ -101,7 +101,15 @@ class TransactionService {
 
   createOptions(options) {
     const config = this._config.config
-    let presetOptions = { transactionSampleRate: config.transactionSampleRate }
+    let presetOptions = { 
+      transactionSampleRate: config.transactionSampleRate
+    }
+    if (config.transactionContextCallback) {
+      presetOptions = {
+        ...presetOptions,
+        transactionContextCallback: config.transactionContextCallback
+      }
+    }
     let perfOptions = extend(presetOptions, options)
     if (perfOptions.managed) {
       perfOptions = extend(
@@ -483,6 +491,13 @@ class TransactionService {
       )
     }
 
+    if (this._config.config.transactionContextCallback) {
+      options = {
+        ...options,
+        tags: this._config.config.transactionContextCallback()
+      }
+    }
+
     const span = tr.startSpan(name, type, options)
     if (__DEV__) {
       this._logger.debug(

packages/rum-core/src/performance-monitoring/transaction.js

@@ -54,6 +54,13 @@ class Transaction extends SpanBase {
 
     this.sampleRate = this.options.transactionSampleRate
     this.sampled = Math.random() <= this.sampleRate
+
+    if (this.options.transactionContextCallback) {
+      this.options = {
+        ...this.options,
+        tags: this.options.transactionContextCallback()
+      }
+    }
   }
 
   addMarks(obj) {

packages/rum-core/test/performance-monitoring/transaction-service.spec.js

@@ -619,6 +619,34 @@ describe('TransactionService', function () {
 
       transaction.end(pageLoadTime + 1000)
     })
+
+    it('should capture tags from dispatch context', done => {
+      config.setConfig({
+        transactionContextCallback: () => {
+          let stack
+          try {
+            throw new Error('')
+          }
+          catch (error) {
+            stack = error.stack || ''
+          }
+          stack = stack.split('\n').map(function (line) { return line.trim(); })
+          return { stack };
+        }
+      })
+      const transactionService = new TransactionService(logger, config)
+
+      const tr1 = transactionService.startTransaction(
+        'transaction1',
+        'transaction'
+      )
+
+      tr1.onEnd = () => {
+        expect(tr1.options.tags.stack).toBeTruthy()
+        done()
+      }
+      tr1.end()
+    })
   })
 
   it('should truncate active spans after transaction ends', () => {

packages/rum/src/index.d.ts

@@ -107,7 +107,8 @@ declare module '@elastic/apm-rum' {
       method: string
       payload?: string
       headers?: Record<string, string>
-    }) => boolean
+    }) => boolean,
+    transactionContextCallback?: (...args: any[]) => any
   }
 
   type Init = (options?: AgentConfigOptions) => ApmBase