feat(core): start tracer with span attributes (#514)

* feat(core): start tracer with span attributes

* feat(core): rename TracerBase attributes to defaultAttributes

* fix(core): tracer base config can be empty

* docs(CHANGELOG): document defaultAttributes

Author: Peter Marton

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+- Add `defaultAttributes` config to `Tracer.start(config)`
 - Add Cumulative (`DoubleCumulative`, `Int64Cumulative`) APIs.
 
  **This release has a breaking change. Please test your code accordingly after upgrading.**

packages/opencensus-core/src/trace/config/types.ts

@@ -18,6 +18,7 @@ import {Logger} from '../../common/types';
 import {Exporter} from '../../exporters/types';
 import {Stats} from '../../stats/types';
 import {PluginNames} from '../instrumentation/types';
+import {Attributes} from '../model/types';
 import {Propagation} from '../propagation/types';
 
 /** Interface configuration for a buffer. */
@@ -32,6 +33,8 @@ export interface BufferConfig {
 
 /** Defines tracer configuration parameters */
 export interface TracerConfig {
+  /** A set of default attributes each in the format [KEY]:[VALUE] */
+  defaultAttributes?: Attributes;
   /** Determines the sampling rate. Ranges from 0.0 to 1.0 */
   samplingRate?: number;
   /** A logger object  */

packages/opencensus-core/src/trace/model/tracer-base.ts

@@ -124,6 +124,13 @@ export class CoreTracerBase implements types.TracerBase {
       if (sampleDecision) {
         const rootSpan =
             new RootSpan(this, name, kind, traceId, parentSpanId, traceState);
+        // Add default attributes
+        const defaultAttributes = this.config && this.config.defaultAttributes;
+        if (defaultAttributes) {
+          Object.keys(defaultAttributes).forEach((key) => {
+            rootSpan.addAttribute(key, defaultAttributes[key]);
+          });
+        }
         rootSpan.start();
         return fn(rootSpan);
       }
@@ -208,7 +215,16 @@ export class CoreTracerBase implements types.TracerBase {
           'no current trace found - must start a new root span first');
       return new NoRecordSpan();
     }
-    return options.childOf.startChildSpan(options.name, options.kind);
+    const span = options.childOf.startChildSpan(options.name, options.kind);
+
+    // Add default attributes
+    const defaultAttributes = this.config && this.config.defaultAttributes;
+    if (defaultAttributes) {
+      Object.keys(defaultAttributes).forEach((key) => {
+        span.addAttribute(key, defaultAttributes[key]);
+      });
+    }
+    return span;
   }
 
   /** Determine whether to sample request or not. */

packages/opencensus-core/test/test-tracer-base.ts

@@ -375,6 +375,33 @@ describe('Tracer Base', () => {
     });
   });
 
+  /** Should add tracer attributes to every span created by tracer */
+  describe('startRootSpan() and startChildSpan() with attributes', () => {
+    let tracerConfig: TracerConfig;
+    let tracer: types.TracerBase;
+    let span: types.Span;
+    let rootSpanLocal: types.Span;
+    before(() => {
+      tracer = new CoreTracerBase();
+      tracerConfig = {
+        ...defaultConfig,
+        defaultAttributes:
+            {cluster_name: 'test-cluster', asg_name: 'test-asg'}
+      };
+      tracer.start(tracerConfig);
+      tracer.startRootSpan(options, (rootSpan) => {
+        rootSpanLocal = rootSpan;
+        span = tracer.startChildSpan(
+            {name: 'spanName', kind: types.SpanKind.CLIENT, childOf: rootSpan});
+      });
+    });
+    it('should add add attributes to spans', () => {
+      assert.deepStrictEqual(
+          rootSpanLocal.attributes, tracerConfig.defaultAttributes);
+      assert.deepStrictEqual(span.attributes, tracerConfig.defaultAttributes);
+    });
+  });
+
   /** Should run eventListeners when the rootSpan ends */
   describe('onEndSpan()', () => {
     it('should run eventListeners when the rootSpan ends', () => {

packages/opencensus-nodejs/README.md

@@ -73,15 +73,16 @@ Tracing has many options available to choose from. At `tracing.start()`, you can
 
 | Options | Type | Description |
 | ------- | ---- | ----------- |
-| [`bufferSize`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L25) | `number` | The number of traces to be collected before exporting to a backend |
-| [`bufferTimeout`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L27) | `number` | Maximum time to wait before exporting to a backend |
-| [`logger`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L29) | `Logger` | A logger object |
-| [`logLevel`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L47) | `number` | Level of logger - 0: disable, 1: error, 2: warn, 3: info, 4: debug |
-| [`samplingRate`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L35) | `number` | Determines the span's sampling rate. Ranges from 0.0 to 1.0 |
-| [`propagation`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L41) | `Propagation` | A propagation instance to use |
-| [`maximumLabelValueSize`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L52) | `number` | The maximum number of characters reported on a label value |
-| [`plugin`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L68) | `PluginNames` | A list of trace instrumentations plugins to load |
-| [`exporter`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L70) | `Exporter` | An exporter object |
+| [`defaultAttributes`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L37) | `Attributes` | Default attributes added to every span created by the tracer |
+| [`bufferSize`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L27) | `number` | The number of traces to be collected before exporting to a backend |
+| [`bufferTimeout`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L29) | `number` | Maximum time to wait before exporting to a backend |
+| [`logger`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L31) | `Logger` | A logger object |
+| [`logLevel`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L51) | `number` | Level of logger - 0: disable, 1: error, 2: warn, 3: info, 4: debug |
+| [`samplingRate`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L39) | `number` | Determines the span's sampling rate. Ranges from 0.0 to 1.0 |
+| [`propagation`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L43) | `Propagation` | A propagation instance to use |
+| [`maximumLabelValueSize`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L56) | `number` | The maximum number of characters reported on a label value |
+| [`plugins`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#72) | `PluginNames` | A list of trace instrumentations plugins to load |
+| [`exporter`](https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/trace/config/types.ts#L74) | `Exporter` | An exporter object |
 
 ## Plugins