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

Author: cjr125

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(
@@ -202,6 +210,7 @@ class TransactionService {
 
   startTransaction(name, type, options) {
     const perfOptions = this.createOptions(options)
+
     let tr
     /**
      * Flag that decides whether we have to fire the `onstart`
@@ -483,6 +492,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/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