chord: merge commit

Author: silva-fabio

examples/README.md …ples/automatic_instrumentation/README.mdexamples/README.md renamed to examples/automatic_instrumentation/README.md examples/README.md renamed to examples/automatic_instrumentation/README.md

@@ -0,0 +1,91 @@
+# OpenCensus Node.js Automatic Tracing
+
+
+Note: This code was tested on the following Node versions:
+- v6.10.0 (for console exporter only)
+- v9.8.0 (for Stackdriver and Zipkin exporters)
+
+___
+
+In this example we'll build a simple http server that can return `Hello World`. We're also going to instrument it using OpenCensus, to be able to collect traces and send them to different services.
+
+## OpenCensus Setup
+
+1. Clone the OpenCensus Node repository < https://github.com/census-instrumentation/opencensus-node.git>
+```bash
+git clone https://github.com/census-instrumentation/opencensus-node.git
+```
+
+2. Switch to branch `dev` with:
+```bash
+git checkout dev
+```
+
+3. Navigate to the OpenCensus Node project folder and install the dependencies with:
+```bash
+cd opencensus-node
+npm install
+```
+
+4. Compile the TypeScript code into JavaScript with:
+```
+node_modules/.bin/tsc
+```
+
+___
+
+## Instrumented Application Setup
+
+1. Navigate to the `automatic_tracing` folder with:
+```
+cd examples/automatic_tracing
+```
+
+2. Create a folder named `node_modules` and make a symlink inside of it, running the following command:
+```
+cd node_modules
+ln -s <opencensus-node-dir>/build/src opencensus-nodejs
+```
+
+### Using Stackdriver Exporter
+
+To use Stackdriver as your exporter, make sure you have enabled [Stackdriver Tracing](https://cloud.google.com/trace/docs/quickstart) on Google Cloud Platform. Enable your [Application Default Credentials](https://cloud.google.com/docs/authentication/getting-started) for authentication with:
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=path/to/your/credential.json
+```
+
+Open the `stackdriver.js` file and, in the `.addStackdriver()` method, pass your Project ID as follows:
+```javascript
+var tracing = require('opencensus-nodejs').addStackdriver('your-project-id').start();
+```
+
+### Using Zipkin Exporter
+
+To use Zipkin as your exporter, first, download from any of the three available options on [Quickstart](https://zipkin.io/pages/quickstart.html): through Docker, on Java or manually compiling the source code. Tests were executed running Zipkin with Java, through the following commands on terminal:
+```bash
+    wget -O zipkin.jar 'https://search.maven.org/remote_content?g=io.zipkin.java&a=zipkin-server&v=LATEST&c=exec'
+    java -jar zipkin.jar
+```
+
+Open the `zipkin.js` file and , in the `.addZipkin()` method, pass your *URL* and *service name* as follows:
+```javascript
+var tracing = require('opencensus-nodejs').addZipkin('http://localhost:9411/api/v2/spans', 'service_name');
+```
+
+___
+
+## Running the Instrumented Application
+
+It is possible to run the application both with or without debugging information. To run with debugging information use:
+```bash
+DEBUG=opencensus node server.js
+```
+
+To run without debugging information, simply use:
+```bash
+node server.js
+```
+
+Go to `http://localhost:8080` to make a request or use a REST Application to do so.
+
+Now, just go to the service used to send the traces and see the requests you just made.

examples/automatic_tracing/README.md

@@ -0,0 +1,25 @@
+/** 
+ * Copyright 2018 Google Inc. All Rights Reserved. 
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); 
+ * you may not use this file except in compliance with the License. 
+ * You may obtain a copy of the License at 
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0 
+ * 
+ * Unless required by applicable law or agreed to in writing, software 
+ * distributed under the License is distributed on an "AS IS" BASIS, 
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+ * See the License for the specific language governing permissions and 
+ * limitations under the License. 
+ */
+
+var fs = require('fs');
+var tracing = require('opencensus-nodejs').addStackdriver('your-project-id').start();
+
+var http = require('http');
+http.createServer(function (req, res) {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.write('Hello World!');
+    res.end();
+}).listen(8080);

examples/automatic_tracing/stackdriver.js

@@ -0,0 +1,26 @@
+/** 
+ * Copyright 2018 Google Inc. All Rights Reserved. 
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); 
+ * you may not use this file except in compliance with the License. 
+ * You may obtain a copy of the License at 
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0 
+ * 
+ * Unless required by applicable law or agreed to in writing, software 
+ * distributed under the License is distributed on an "AS IS" BASIS, 
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+ * See the License for the specific language governing permissions and 
+ * limitations under the License. 
+ */
+
+var fs = require('fs');
+var tracing = require('opencensus-nodejs').addZipkin('http://localhost:9411/api/v2/spans', 'service_name');
+tracing.start();
+
+var http = require('http');
+http.createServer(function (req, res) {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.write('Hello World!');
+    res.end();
+}).listen(8080);

examples/automatic_tracing/zipkin.js

@@ -0,0 +1,90 @@
+# OpenCensus Node.js Custom Tracing
+
+
+Note: This code was tested on the following Node versions:
+- v6.10.0 (for console exporter only)
+- v9.8.0 (for Stackdriver and Zipkin exporters)
+
+___
+
+In these example we're going to build custom spans for `GET` requests and file writing operations and send them to different services.
+
+## OpenCensus Setup
+
+1. Clone the OpenCensus Node repository < https://github.com/census-instrumentation/opencensus-node.git>
+```bash
+git clone https://github.com/census-instrumentation/opencensus-node.git
+```
+
+2. Switch to branch `dev` with:
+```bash
+git checkout dev
+```
+
+3. Navigate to the OpenCensus Node project folder and install the dependencies with:
+```bash
+cd opencensus-node
+npm install
+```
+
+4. Compile the TypeScript code into JavaScript with:
+```
+node_modules/.bin/tsc
+```
+
+___
+
+## Instrumented Application Setup
+
+1. Navigate to the `automatic_tracing` folder with:
+```
+cd examples/automatic_tracing
+```
+
+2. Create a folder named `node_modules` and make a symlink inside of it, running the following command:
+```
+cd node_modules
+ln -s <opencensus-node-dir>/build/src opencensus-nodejs
+```
+
+
+### Using Stackdriver Exporter
+
+To use Stackdriver as your exporter, make sure you have enabled [Stackdriver Tracing](https://cloud.google.com/trace/docs/quickstart) on Google Cloud Platform. Enable your [Application Default Credentials](https://cloud.google.com/docs/authentication/getting-started) for authentication with:
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=path/to/your/credential.json
+```
+
+Open the `stackdriver.js` file and, in the `.addStackdriver()` method, pass your Project ID as follows:
+```javascript
+var tracing = require('opencensus-nodejs').addStackdriver('your-project-id').start();
+```
+
+### Using Zipkin Exporter
+
+To use Zipkin as your exporter, first, download from any of the three available options on [Quickstart](https://zipkin.io/pages/quickstart.html): through Docker, on Java or manually compiling the source code. Tests were executed running Zipkin with Java, through the following commands on terminal:
+```bash
+    wget -O zipkin.jar 'https://search.maven.org/remote_content?g=io.zipkin.java&a=zipkin-server&v=LATEST&c=exec'
+    java -jar zipkin.jar
+```
+
+Open the `zipkin.js` file and , in the `.addZipkin()` method, pass your *URL* and *service name* as follows:
+```javascript
+var tracing = require('opencensus-nodejs').addZipkin('http://localhost:9411/api/v2/spans', 'service_name');
+```
+
+___
+
+## Running the Instrumented Application
+
+It is possible to run the application both with or without debugging information. To run with debugging information use:
+```bash
+DEBUG=opencensus node server.js
+```
+
+To run without debugging information, simply use:
+```bash
+node server.js
+```
+
+Go to the service used to send the traces and see the spans for the operations you just made.

examples/custom_tracing/README.md

@@ -0,0 +1,53 @@
+/** 
+ * Copyright 2018 Google Inc. All Rights Reserved. 
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); 
+ * you may not use this file except in compliance with the License. 
+ * You may obtain a copy of the License at 
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0 
+ * 
+ * Unless required by applicable law or agreed to in writing, software 
+ * distributed under the License is distributed on an "AS IS" BASIS, 
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+ * See the License for the specific language governing permissions and 
+ * limitations under the License. 
+ */
+
+var opencensus = require('opencensus-nodejs');
+var http = require('http');
+var fs = require('fs');
+
+// Register trace exporters to export the collected data.
+var tracing = require('opencensus-nodejs').addStackdriver('your-project-id').start();
+var tracer = tracing.Tracer;
+
+var options = {
+    name: 'fs.writeFileSync'
+};
+
+// Create root span for GET request
+tracer.startRootSpan(options, (span) => {
+    http.get('http://httpbin.org/image/jpeg', function (response) {
+
+        var data = [];
+
+        response.on('data', (chunk) => {
+            data.push(chunk);
+        });
+
+        response.on('end', () => {
+            var filename = 'file';
+            // Create a child span for file writing operation
+            var childSpan = tracer.startSpan(filename);
+            var buffer = Buffer.concat(data);
+            fs.writeFileSync(filename + '.jpeg', buffer, 'utf-8');
+            
+            // Finish both root span and child span, since the operations 
+            // has ended.
+            childSpan.end();
+            span.end();
+        });
+        console.log('No more data in response.');
+    });
+});

examples/custom_tracing/stackdriver.js

@@ -0,0 +1,54 @@
+/** 
+ * Copyright 2018 Google Inc. All Rights Reserved. 
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); 
+ * you may not use this file except in compliance with the License. 
+ * You may obtain a copy of the License at 
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0 
+ * 
+ * Unless required by applicable law or agreed to in writing, software 
+ * distributed under the License is distributed on an "AS IS" BASIS, 
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
+ * See the License for the specific language governing permissions and 
+ * limitations under the License. 
+ */
+
+var opencensus = require('opencensus-nodejs');
+var http = require('http');
+var fs = require('fs');
+
+// Register trace exporters to export the collected data.
+var tracing = opencensus.addZipkin('http://localhost:9411/api/v2/spans', 'service_name').start();
+var tracer = tracing.Tracer;
+
+var options = {
+    name: 'fs.writeFileSync'
+};
+
+// Create root span for GET request
+tracer.startRootSpan(options, (span) => {
+    http.get('http://httpbin.org/image/jpeg', function (response) {
+
+        var data = [];
+
+        response.on('data', (chunk) => {
+            data.push(chunk);
+        });
+
+        response.on('end', () => {
+            var filename = 'file';
+            // Create a child span for file writing operation
+            var childSpan = tracer.startSpan(filename);
+            var buffer = Buffer.concat(data);
+            fs.writeFileSync(filename + '.jpeg', buffer, 'utf-8');
+            
+            // Finish both root span and child span, since the operations 
+            // has ended.
+            childSpan.end();
+            span.end();
+        });
+        console.log('No more data in response.');
+    });
+});
+