feat: add public API for root span id (googleapis#542)

Make it possible for external users to get a unique identifier for the
root span. This can be used to uniquely identify the top level
incoming http request context for example.

src/trace-api.js

@@ -33,6 +33,7 @@ var TracingPolicy = require('./tracing-policy.js');
 var phantomApiImpl = {
   enhancedDatabaseReportingEnabled: function() { return false; },
   runInRootSpan: function(opts, fn) { return fn(null); },
+  getCurrentContext: function() { return null; },
   createChildSpan: function(opts) { return null; },
   getResponseTraceContext: function(context, traced) { return ''; },
   wrap: function(fn) { return fn; },
@@ -176,6 +177,22 @@ TraceAgent.prototype.runInRootSpan = function(options, fn) {
   });
 };
 
+/**
+ * Returns a unique identifier for the currently active context. This can be
+ * used to uniquely identify the current root span. If there is no current,
+ * context, or if we have lost context, this will return null. The structure and
+ * the length of the returned string should be treated opaquely - the only
+ * guarantee is that the value would unique for every root span.
+ * @returns {string} an id for the current context, or null if there is none
+ */
+TraceAgent.prototype.getCurrentContextId = function() {
+  const rootSpan = cls.getRootContext();
+  if (!rootSpan || rootSpan === nullSpan) {
+    return null;
+  }
+  return rootSpan.trace.traceId;
+};
+
 /**
  * Creates and returns a new ChildSpan object nested within the root span. If
  * there is no current RootSpan object, this function returns null.

test/test-trace-api.js

@@ -48,6 +48,7 @@ function assertAPISurface(traceAPI) {
       assert.strictEqual(typeof root.getTraceContext(), 'string');
     }
   });
+  assert.strictEqual(typeof traceAPI.getCurrentContextId, 'function');
   var child = traceAPI.createChildSpan({ name: 'child' });
   // TODO: Ditto but with child spans
   if (child) {
@@ -169,6 +170,19 @@ describe('Trace Interface', function() {
       });
     });
 
+    it('should return null context id when one does not exist', function() {
+      var traceAPI = createTraceAgent();
+      assert.strictEqual(traceAPI.getCurrentContextId(), null);
+    });
+
+    it('should return the appropriate trace id', function() {
+      var traceAPI = createTraceAgent();
+      traceAPI.runInRootSpan({name: 'root', url: 'root'}, function(rootSpan) {
+        var id = traceAPI.getCurrentContextId();
+        assert.strictEqual(id, rootSpan.trace.traceId);
+      });      
+    });
+
     it('should add labels to spans', function() {
       var traceAPI = createTraceAgent();
       traceAPI.runInRootSpan({name: 'root', url: 'root'}, function(root) {