chord: merge commit

Author: eduardoemery

docs/design/opencensus.nodejs.first.design.pdf

@@ -0,0 +1,138 @@
+# OpenCensus Node.js Example
+
+
+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)
+
+At this momment the automatic instrumetation is only for apps using http and mongo-db.
+
+___
+
+## 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
+cd opencensus-node
+```
+
+2. Switch to branch `dev` with:
+```bash
+git checkout dev
+```
+
+3. Install the dependencies with:
+```bash
+npm install
+```
+
+4. Compile the TypeScript code into JavaScript with:
+```
+node_modules/.bin/tsc
+```
+
+5. In a different folder, clone the example application to be instrumented (EasyNotes Application)
+```bash
+ git clone https://github.com/callicoder/node-easy-notes-app
+```
+
+6. Navigate to the application folder and install the dependencies with:
+```bash
+cd node-easy-notes-app
+npm install
+```
+
+7. Check if the app is running. PS.: a mongodb installation is required
+```bash
+$ node server.js
+Server is listening on port 3000
+Successfully connected to the database
+```
+
+## Add opencensus instrumentation 
+
+To add opencensus instrumetation, follow the steps below:
+
+1. Navigate to the `node_modules` folder inside the EasyNotes application and create a link to OpenCensus Node project folder with:
+```bash
+cd node_modules
+ln -s <your path>/opencensus-node/build/src  opencensus-nodejs
+cd ..
+```
+
+2. Edit server.js and add the following line, as the first line of the file:
+```javascript
+ var tracing = require("opencensus-nodejs").start()
+ ...
+ var express = require('express');
+```
+
+## Running the Instrumented Application
+
+Save the file server.js and run the app with debugging option. 
+
+```bash
+$ DEBUG=opencensus node server.js
+opencensus useAsyncHooks = true +0ms  
+opencensus patching http@9.8.0 module +75ms  
+opencensus patching http.Server.prototype.emit function +7ms  
+....
+Server is listening on port 3000
+Successfully connected to the database
+```
+This options uses a default exporter to console.
+
+To test de api you can use the commands:
+```bash
+#To insert a note:
+curl -X POST http://localhost:3000/notes --data '{"title": "Note 1", "content": "this is the note content"}' -H "Content-Type: application/json"
+
+#To get notes:
+curl http://localhost:3000/notes
+```
+
+## Exporting to Zipkins
+
+1. Download Zipkin choosing one 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
+```
+
+2. Open the `server.js` file in the EasyNotes application and insert this code on top:
+```javascript
+var tracing = require("opencensus-nodejs")
+              .addZipkin("http://localhost:9411/api/v2/spans", "easy-notes")
+              .start()
+```
+
+
+## Exporting to Stackdriver
+
+1. Make sure you enabled Stackdriver Tracing on Google Cloud Platform. More info at <https://cloud.google.com/trace/docs/quickstart>
+
+2. Enable Application Default Credentials for authentication with:
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=path/to/your/credential.json
+```
+More information at <https://cloud.google.com/docs/authentication/getting-started>
+
+3. Open the `server.js` file in the EasyNotes application and insert this code on top:
+```javascript
+var traceMng = require("opencensus-nodejs")
+               .addStackdriver("your-project-id")
+               .start();
+```
+
+
+## Exporting to multiple Exporters
+
+It is possible to instrument with more than one code. To achieve this, simply add more than one Exporter in series.
+
+```javascript
+var tracing = require("opencensus-nodejs")
+              .addZipkin(“http://localhost:9411/api/v2/spans“, "easy-notes")
+              .addStackdriver("your-project")
+              .start()
+```

examples/README.md

@@ -11,6 +11,7 @@
     "compile-strict": "npm run script compile-auto-strict",
     "compile": "npm run script compile-auto compile-auto-strict",
     "clean": "rimraf build/*",
+    "fix": "gts fix",
     "script": "ts-node -P ./scripts ./scripts"
   },
   "keywords": [

packages/opencensus-core/package.json

@@ -18,8 +18,8 @@ import { Span } from './span'
 import { Clock } from '../../internal/clock'
 import * as uuid from 'uuid';
 import { debug } from '../../internal/util'
-import { SpanBaseModel, TraceContext, OnEndSpanEventListener, TraceOptions } from '../types/tracetypes'
-import { Tracer } from './tracer';
+import { SpanBaseModel, TraceOptions, TraceContext, OnEndSpanEventListener } from '../types/tracetypes'
+import { Tracer } from './tracer'
 
 export class RootSpan extends SpanBaseModel implements OnEndSpanEventListener {
 

packages/opencensus-core/src/trace/model/root-span.ts

@@ -61,19 +61,20 @@ export class Span extends SpanBaseModel {
     }
 
     public end(): void {
-        super.end();
-        this.notifyEnd();
-        debug('ending span  %o',
-            {
-                spanId: this.id,
-                traceId: this.traceId,
-                name: this.name,
-                startTime: this.startTime,
-                endTime: this.endTime,
-                duration: this.duration
-            }
-        )
-
+        // if(this.sampler.continue(this.traceId)) {
+            
+            super.end();
+            this.notifyEnd();
+            debug('ending span  %o',
+                {
+                    spanId: this.id,
+                    traceId: this.traceId,
+                    name: this.name,
+                    startTime: this.startTime,
+                    endTime: this.endTime,
+                    duration: this.duration
+                });
+        // }
     }
 
 

packages/opencensus-core/src/trace/model/span.ts

@@ -20,6 +20,7 @@ import { Span } from './span'
 import { debug } from '../../internal/util'
 import { Stackdriver } from '../../exporters/stackdriver/stackdriver'
 import { StackdriverOptions } from '../../exporters/stackdriver/options'
+import { Sampler } from '../config/sampler'
 import { TraceContext, TraceOptions, OnEndSpanEventListener, SpanBaseModel } from '../types/tracetypes';
 import { TracerConfig, defaultConfig } from '../tracing';
 
@@ -36,7 +37,7 @@ export class Tracer implements OnEndSpanEventListener {
     private config: TracerConfig;
 
     //TODO: simple solution - to be rewied in future
-    private eventListeners: OnEndSpanEventListener[] = [];
+    private eventListeners: OnEndSpanEventListener[] = [];   
     //TODO: temp solution 
     private endedTraces: RootSpan[] = [];
 
@@ -72,26 +73,31 @@ export class Tracer implements OnEndSpanEventListener {
     }
 
     public startRootSpan<T>(options: TraceOptions, fn: (root: RootSpan) => T): T {
-        debug('starting root span: %o', options)
         return this.contextManager.runAndReturn((root) => {
             let newRoot = new RootSpan(this, options);
             this.setCurrentRootSpan(newRoot);
-            newRoot.start();
-            return fn(newRoot);
+            if(options.sampler == null){
+                options.sampler = new Sampler(newRoot.traceId);
+                options.sampler.probability(0.6);
+            }
+            newRoot.sampler = options.sampler;
+            if(newRoot.sampler.continue(newRoot.traceId)){
+                newRoot.start();
+                return fn(newRoot);
+            }
+            return fn(null);
         });
     }
 
-    public onEndSpan(root: RootSpan): void {
-        if (!this.currentRootSpan) {
-            return debug('cannot end trace - no active trace found', this.currentRootSpan)
+
+    public onEndSpan(root:RootSpan): void {
+        if (!root) {
+            return debug('cannot end trace - no active trace found')
         }
-        if (this.currentRootSpan != root) {
-            debug('currentRootSpan != root on notifyEnd. Possbile implementation bug.')
-            debug('ROOT SPAN ', root)
-            return debug('CURRENT ROOT SPAN ', this.currentRootSpan)
-            //return debug('currentRootSpan != root on notifyEnd. Possbile implementation bug.')
+        if(this.currentRootSpan != root) {
+             debug('currentRootSpan != root on notifyEnd. Need more investigation.') 
         }
-        this.notifyEndSpan(this.currentRootSpan);
+        this.notifyEndSpan(root);
         //this.clearCurrentTrace();
     }
 
@@ -101,8 +107,8 @@ export class Tracer implements OnEndSpanEventListener {
 
     private notifyEndSpan(root: RootSpan) {
         if (this.active) {
-            //this.buffer.onEndSpan(root);
-            if (this.eventListeners && this.eventListeners.length > 0) {
+            debug ('starting to notify listeners the end of rootspans')
+            if(this.eventListeners&&this.eventListeners.length >0) {
                 this.eventListeners.forEach((listener) => listener.onEndSpan(root))
             }
         } else {

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

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+
+import { debug, randomSpanId } from '../../internal/util'
+
+
+const minNumber = 1e-4;
+const maxNumber = 0xffffffffffffffff;
+
+export class Sampler{
+     traceId:       string;
+     spanId:        string;
+     isRemote:      boolean;
+     idUpperBound:  number;
+
+     /**
+      * 
+      * @param traceId 
+      * @param spanId 
+      * @param isRemote 
+      */
+     constructor(traceId?:string, spanId?:string, isRemote?:boolean){
+         debug('Samplre constructor')
+         if(traceId){ 
+             this.traceId   = traceId;
+         }
+         if(spanId){
+            this.spanId    = spanId;
+         }
+        this.isRemote  = isRemote || false;
+
+     }
+
+     public always(): Sampler{
+         this.idUpperBound = maxNumber;
+         return this;
+     }
+
+     public never(): Sampler{
+         this.idUpperBound = minNumber;
+         return this;
+     }
+
+     public probability(probability:number): Sampler{
+        if(probability < minNumber){
+            return this.never();
+
+        } else if (probability > maxNumber){
+            return this.always();
+
+        }
+
+        this.idUpperBound = probability * maxNumber;
+        return this;
+     }
+
+     public continue (traceId:string):boolean{
+        debug('Samplre continue')
+        let lower_bytes = traceId.substring(16)
+        let lower_long: number
+        debug('SAMPLER CONTINUE lower_bytes :',lower_bytes)
+
+        lower_long = parseInt(lower_bytes, 16);
+
+        debug('SAMPLER CONTINUE lower_long :',lower_long)
+        debug('SAMPLER CONTINUE this.idUpperBound :',this.idUpperBound)
+        debug('SAMPLER CONTINUE diff :',lower_long - this.idUpperBound)
+
+        if(lower_long <= this.idUpperBound){
+            debug('trace sampler TRUE')
+            return true
+        }else{
+            debug('trace sampler FALSE')
+            return false;
+        }
+     }
+
+ }