Merge branch 'master' into warn-on-already-required

.circleci/config.yml

@@ -73,6 +73,7 @@ cache_2: &cache_2
     - packages/opentelemetry-plugin-mysql/node_modules
     - packages/opentelemetry-exporter-collector/node_modules
     - packages/opentelemetry-plugin-xml-http-request/node_modules
+    - packages/opentelemetry-exporter-stackdriver-trace/node_modules
 
 node_unit_tests: &node_unit_tests
   steps:

README.md

@@ -108,6 +108,7 @@ OpenTelemetry is vendor-agnostic and can upload data to any backend with various
 #### Trace Exporters
 - [@opentelemetry/exporter-jaeger](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-jaeger)
 - [@opentelemetry/exporter-zipkin](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-zipkin)
+- [@opentelemetry/exporter-stackdriver-trace](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-stackdriver-trace)
 - [@opentelemetry/exporter-collector](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-collector)
 
 #### Metric Exporters

examples/basic-tracer-node/multi_exporter.js

@@ -17,10 +17,9 @@ const collectorExporter = new CollectorExporter({serviceName: 'basic-service'});
 registry.addSpanProcessor(new BatchSpanProcessor(zipkinExporter, {
   bufferSize: 10 // This is added for example, default size is 100.
 }));
-
-// It is recommended to use SimpleSpanProcessor in case of Jaeger exporter as
-// it's internal client already handles the spans with batching logic.
-registry.addSpanProcessor(new SimpleSpanProcessor(jaegerExporter));
+tracer.addSpanProcessor(new BatchSpanProcessor(jaegerExporter), {
+  bufferSize: 10
+});
 
 registry.addSpanProcessor(new SimpleSpanProcessor(collectorExporter));
 

examples/stackdriver-trace/.gitignore

@@ -0,0 +1 @@
+service_account_key.json

examples/stackdriver-trace/README.md

@@ -0,0 +1,37 @@
+# Overview
+
+This example shows how to use [@opentelemetry/tracing](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing) to instrument a simple Node.js application - e.g. a batch job - and export spans either to [Stackdriver Trace](https://cloud.google.com/trace/).
+
+## Installation
+
+```sh
+$ # from this directory
+$ npm install
+```
+
+## Authenticate
+
+If you are running in a GCP environment, the exporter will automatically authenticate as the service account of your environment. Please make sure that it has permission to access stackdriver trace.
+
+If you are not running in a GCP environment you will need to create a service account and save the service account key json in the root of this example named `service_account_key.json`. For more information, visit <https://cloud.google.com/docs/authentication/>.
+
+## Run the Application
+
+```sh
+$ # from this directory
+$ npm start
+```
+
+## View traces
+
+https://console.cloud.google.com/traces/list?project=your-project-id
+
+<p align="center"><img src="images/trace.png?raw=true"/></p>
+
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on tracing, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing>
+
+## LICENSE
+
+Apache License 2.0

examples/stackdriver-trace/index.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/core');
+const { BasicTracer, SimpleSpanProcessor } = require('@opentelemetry/tracing');
+const { CanonicalCode } = require('@opentelemetry/types');
+const { StackdriverTraceExporter } = require('@opentelemetry/exporter-stackdriver-trace');
+
+// Initialize an exporter
+const exporter = new StackdriverTraceExporter({
+  serviceName: 'basic-service',
+  logger: new opentelemetry.ConsoleLogger()
+});
+
+const tracer = new BasicTracer();
+
+// Configure span processor to send spans to the provided exporter
+tracer.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+// Initialize the OpenTelemetry APIs to use the BasicTracer bindings
+opentelemetry.initGlobalTracer(tracer);
+
+// Create a span. A span must be closed.
+const root = opentelemetry.getTracer().startSpan('main');
+const related = opentelemetry.getTracer().startSpan('related', {
+  links: [{ spanContext: root.context() }]
+});
+
+for (let i = 0; i < 10; i++) {
+  doWork(root);
+  doWork(related);
+}
+// Be sure to end the span.
+root.setStatus({
+  code: CanonicalCode.UNKNOWN
+})
+root.end();
+related.end();
+
+// flush and close the connection.
+exporter.shutdown();
+
+function doWork(parent) {
+  // Start another span. In this example, the main method already started a
+  // span, so that'll be the parent span, and this will be a child span.
+  const span = opentelemetry.getTracer().startSpan('doWork', {
+    parent: parent
+  });
+
+  // simulate some random work.
+  const work = Math.floor(Math.random() * 40000000);
+  for (let i = 0; i <= work; i++) { }
+
+  if (work % 2 === 1) {
+    span.setStatus({
+      code: CanonicalCode.UNKNOWN
+    })
+  }
+
+  // Set attributes to the span.
+  span.setAttribute('key', 'value');
+
+  // Annotate our span to capture metadata about our operation
+  span.addEvent('invoking doWork').end();
+}

examples/stackdriver-trace/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "example-stackdriver-trace",
+  "private": true,
+  "version": "0.3.1",
+  "description": "Example of using @opentelemetry/exporter-stackdriver-trace in Node.js",
+  "main": "index.js",
+  "scripts": {
+    "start": "cross-env GOOGLE_APPLICATION_CREDENTIALS=service_account_key.json node ./index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "http",
+    "tracing"
+  ],
+  "engines": {
+    "node": ">=8"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js/issues"
+  },
+  "dependencies": {
+    "@opentelemetry/core": "^0.3.1",
+    "@opentelemetry/exporter-stackdriver-trace": "^0.3.1",
+    "@opentelemetry/tracing": "^0.3.1",
+    "@opentelemetry/types": "^0.3.1"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js#readme",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

getting-started/ts-example/package.json

@@ -5,10 +5,13 @@
   "main": "app.ts",
   "scripts": {
     "start": "ts-node app.ts",
-    "start-tracing": "ts-node -r ./tracing.ts app.ts",
+    "start-tracing": "ts-node -r ./tracing.ts app.ts"
   },
   "author": "OpenTelemetry Authors",
   "license": "Apache-2.0",
+  "devDependencies": {
+    "ts-node": "^8.6.2"
+  },
   "dependencies": {
     "@opentelemetry/core": "^0.3.2",
     "@opentelemetry/exporter-prometheus": "^0.3.2",
@@ -18,7 +21,7 @@
     "@opentelemetry/plugin-http": "^0.3.2",
     "@opentelemetry/tracing": "^0.3.2",
     "@opentelemetry/types": "^0.3.2",
-    "axios": "^0.19.0",
+    "axios": "^0.19.1",
     "express": "^4.17.1"
   }
 }

packages/opentelemetry-exporter-stackdriver-trace/.npmignore

@@ -0,0 +1,4 @@
+/bin
+/coverage
+/doc
+/test