feat(rum): allow creating blocking spans from agent api (elastic#875)

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,17 +185,29 @@ 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:
 
 * `name` - The name of the span (string). Defaults to `Unknown`
 
 * `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.
 
 

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`.
    */

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
 

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)
     }
   }
 

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')