From 50e692daed13ed546a116e0921d639e41c0a3080 Mon Sep 17 00:00:00 2001
From: Vignesh Shanmugam <vignesh.shanmugam22@gmail.com>
Date: Tue, 18 Aug 2020 14:44:34 +0200
Subject: [PATCH] feat(rum): allow creating blocking spans from agent api
 (#875)

---
 docs/agent-api.asciidoc                  | 18 +++++++++++++++---
 docs/custom-transactions.asciidoc        |  2 +-
 docs/transaction-api.asciidoc            |  2 +-
 packages/rum/src/apm-base.js             |  4 ++--
 packages/rum/test/specs/apm-base.spec.js | 19 +++++++++++++++++++
 5 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc
index e8730222d..c545bdf5d 100644
--- a/docs/agent-api.asciidoc
+++ b/docs/agent-api.asciidoc
@@ -141,7 +141,7 @@ NOTE: The payload will be dropped if one of the filters return a falsy value.
 
 [source,js]
 ----
-apm.startTransaction(name, type, options)
+const transaction = apm.startTransaction(name, type, options)
 ----
 
 
@@ -185,10 +185,10 @@ NOTE: This method returns `undefined` if apm is disabled or if <<active,active>>
 
 [source,js]
 ----
-var span = apm.startSpan(name, type)
+const span = apm.startSpan(name, type, options)
 ----
 
-Starts and returns a new span on the current transaction.
+Starts and returns a new span associated with the current active transaction.
 
 Arguments:
 
@@ -196,6 +196,18 @@ Arguments:
 
 * `type` - The type of the span (string). Defaults to `custom`
 
+* `options` - The following options are supported:
+
+** `blocking` - Blocks the associated transaction from ending till this span is ended. Blocked spans
+    automatically creates an internal task. Defaults to false
+
+** `parentId` - Parent id associated with the new span. Defaults to current transaction id
+
+** `sync` - Denotes if the span is synchronous or asynchronous. Defaults to null
+
+
+Blocked spans allow users to control the early closing of <<custom-managed-transactions, managed transactions>> in few cases when the app contains lots of async activity which cannot be tracked by the agent.
+
 NOTE: This method returns `undefined` if apm is disabled or if <<active,active>> flag is set to `false` in the config.
 
 
diff --git a/docs/custom-transactions.asciidoc b/docs/custom-transactions.asciidoc
index 57b9f237d..e26dde906 100644
--- a/docs/custom-transactions.asciidoc
+++ b/docs/custom-transactions.asciidoc
@@ -46,7 +46,7 @@ const span = transaction.startSpan('async-task', 'app', { blocking: true })
 setTimeout(() => {
   span.end()
   /**
-   * This would also end the managed transaction once all the blocking tasks are completed and
+   * This would also end the managed transaction once all the blocking spans are completed and
    * transaction would also contain other timing information and spans similar to auto
    * instrumented transactions like `page-load` and `route-change`.
    */
diff --git a/docs/transaction-api.asciidoc b/docs/transaction-api.asciidoc
index 9a2a60a2a..ca3a81c8a 100644
--- a/docs/transaction-api.asciidoc
+++ b/docs/transaction-api.asciidoc
@@ -65,7 +65,7 @@ Arguments:
 * `options` - The following options are supported:
 
 ** `blocking` - Blocks the associated transaction from ending till this span is ended. Blocked spans
-    automatically internally creates a task. Defaults to false
+    automatically creates an internal task. Defaults to false
 
 ** `parentId` - Parent id associated with the new span. Defaults to current transaction id
 
diff --git a/packages/rum/src/apm-base.js b/packages/rum/src/apm-base.js
index 8c9f39457..18b40dc5d 100644
--- a/packages/rum/src/apm-base.js
+++ b/packages/rum/src/apm-base.js
@@ -250,12 +250,12 @@ export default class ApmBase {
     }
   }
 
-  startSpan(name, type) {
+  startSpan(name, type, options) {
     if (this.isEnabled()) {
       var transactionService = this.serviceFactory.getService(
         'TransactionService'
       )
-      return transactionService.startSpan(name, type)
+      return transactionService.startSpan(name, type, options)
     }
   }
 
diff --git a/packages/rum/test/specs/apm-base.spec.js b/packages/rum/test/specs/apm-base.spec.js
index 129cced1b..13805a9bd 100644
--- a/packages/rum/test/specs/apm-base.spec.js
+++ b/packages/rum/test/specs/apm-base.spec.js
@@ -326,6 +326,25 @@ describe('ApmBase', function() {
     expect(configService.get('context.tags')).toEqual(labels)
   })
 
+  it('should allow creating blocked spans on current transaction', () => {
+    apmBase.init({
+      serviceName,
+      serverUrl,
+      instrument: false
+    })
+    const tr = apmBase.startTransaction('blocking-transaction', 'custom', {
+      managed: true
+    })
+    const span1 = apmBase.startSpan('span1')
+    const span2 = apmBase.startSpan('span2', 'custom', { blocking: true })
+
+    expect(tr._activeTasks.size).toBe(1)
+    span1.end()
+    expect(tr.ended).toBe(false)
+    span2.end()
+    expect(tr.ended).toBe(true)
+  })
+
   it('should fetch central config', done => {
     const apmServer = serviceFactory.getService('ApmServer')
     const configService = serviceFactory.getService('ConfigService')