Update documentation (#152)

* Update documentation

* Change

* Fix docs

examples/initial_load/README.md

@@ -32,7 +32,7 @@ exporters:
 Then in the same folder as your `config.yaml` run the agent with this command:
 
 ```bash
-go run github.com/census-instrumentation/opencensus-service/cmd/ocagent
+GO111MODULE=on go run github.com/census-instrumentation/opencensus-service/cmd/ocagent
 ```
 
 ### Step 2: Run the local webpack server
@@ -105,7 +105,7 @@ following the
 [OpenCensus Agent](https://github.com/census-instrumentation/opencensus-service#opencensus-agent)
 docs.
 
-### 5. Build the demo application container
+### 4. Build the demo application container
 
 First build the OpenCensus Web scripts that will be deployed with the
 application:
@@ -123,7 +123,7 @@ docker build . -t gcr.io/$PROJECT_ID/oc-web-initial-load:latest
 gcloud docker -- push gcr.io/$PROJECT_ID/oc-web-initial-load:latest
 ```
 
-### 4. Deploy the demo application
+### 5. Deploy the demo application
 
 Run the command `kubectl get svc oc-agent-service` to check if the 
 `EXTERNAL-IP` column has been filled in. If it is still pending, then wait a bit

examples/user_interaction/README.md

@@ -1,28 +1,41 @@
 # OpenCensus Web example server for user interaction tracing
 
 This example server renders a simple hello page and writes both the server-side
-and client side spans for the initial page load to the [OpenCensus agent](https://github.com/census-instrumentation/opencensus-service).
+and client side spans for the initial page load and user interactions to the 
+[OpenCensus agent][opencensus-agent].
 
-Also, add a button in order to test user interactions, this button triggers network requests to the provided node server when it is clicked.
-These requests sleep the server for a while and calculate prime numbers until 100000. After this, the frontend calculates PI.
-The idea of these calls is to trace the click on the button and see calculations in server and client side.
+The main purpose of this example is to show the user interaction tracing.
+For that, a `React JS` client is instrumented with the npm `@opencensus/web-instrumentation-zone` package to 
+start tracing the user interactions. Additionally, a `Node JS` server is instrumented with 
+`@opencensus/nodejs` library to send spans by default to [Zipkin][zipkin]
+
+The app has two buttons with the same click handler but one button has the `data-ocweb-id` 
+attribute to show this naming aproach, and the other button has an `id` to show the CSS 
+selector naming approach. When one button is clicked, a new interaction is started, it first tracks 
+a `Promise` which will run a `setTimeout` of 1000 ms, once this is done, an HTTP 
+request is sent to the server which sleeps for 2 seconds and then sends the response. 
+Once the request has finished, another HTTP request is done to do some calculations in the server 
+side, then the client will calculate PI to show a long span.
+After all of those tasks, the interaction finishes and is sent to the OC Agent.
+
+Additionally, the client provides some route transitions to show the *Navigation* naming approach.
 
 ## Running locally
 
 ### Step 1: Install and run the OpenCensus agent
 
-To run this example in local development mode, you will need to run the [OpenCensus
-agent](https://github.com/census-instrumentation/opencensus-service).
+To run this example in local development mode, you will need to run the [OpenCensus agent][opencensus-agent].
 
-First set your `GOPATH` environment variable and then install the agent by
-running:
+First set your `GOPATH` environment variable and then install the agent by running:
 
 ```bash
 go get -d github.com/census-instrumentation/opencensus-service
 ```
 
 Then create a `config.yaml` file following the
-[Configuration](https://github.com/census-instrumentation/opencensus-service#config) instructions for the agent. You will need to have the `opencensus` receiver set up on the default port of `55678`, and you will need at least one exporter so you can see the traces that are generated. For example, your config file could look like this:
+[Configuration][opencensus-servie-config] instructions for the agent. You will need to have the 
+`opencensus` receiver set up on the default port of `55678`, and you will need at least one exporter 
+so you can see the traces that are generated. For example, your config file could look like this:
 
 ```yaml
 receivers:
@@ -36,12 +49,12 @@ exporters:
 Then in the same folder as your `config.yaml` run the agent with this command:
 
 ```bash
-go run github.com/census-instrumentation/opencensus-service/cmd/ocagent
+GO111MODULE=on go run github.com/census-instrumentation/opencensus-service/cmd/ocagent
 ```
 
 ### Step 2: Run the client (React application)
 
-Then within your the `client` folder install all dependencies and run locally the application.
+Then within the `client` folder install all dependencies and run locally the application.
 
 ```bash
 cd client/
@@ -51,19 +64,27 @@ npm start
 
 That will start the react application on `localhost:3000`.
 
-### Step 3: Run this example server
+### Step 3: Run the server
 
-Now you can run this example server with the following commands from within your
+Now you can run the example server with the following commands from within your
 `opencensus-web` folder:
 
 ```bash
-cd examples/user_interaction/server/
+cd server/
 node server.js
 ```
 
 Now visit http://localhost:3000/ in your browser to see the hello
-world page render. If you look in the browser developer tools network tab, you
-should see an XHR that writes trace spans to the OpenCensus agent. Then go to
-the trace viewer for the exporter you set up and view the trace of your initial
-page load. It will be named `Nav./index.html` (or just `Nav./` if you left off
-the actual `index.html` part when you visited the URL).
+world page render. If you click on the button or navigate to another page
+in the browser developer tools network tab, you should see an XHR that writes 
+trace spans to the OpenCensus agent. 
+
+Then go to the trace viewer for the exporter you set up and view the trace of your initial
+page load plus the different user interaction traces. Notice they will be named as 
+*Trace user interaction*, *button#trace_interaction click* or *Navigation /second_page*
+for this example. Then, in every trace you will see several spans associated to the interaction.
+
+
+[opencensus-agent]: (https://github.com/census-instrumentation/opencensus-service)
+[zipkin]: (https://opencensus.io/codelabs/zipkin/)
+[opencensus-servie-config]: (https://github.com/census-instrumentation/opencensus-service#config)

examples/user_interaction/client/README.md

@@ -12,11 +12,6 @@ Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
 The page will reload if you make edits.<br>
 You will also see any lint errors in the console.
 
-### `npm test`
-
-Launches the test runner in the interactive watch mode.<br>
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
-
 ### `npm run build`
 
 Builds the app for production to the `build` folder.<br>

examples/user_interaction/client/package.json

@@ -20,9 +20,7 @@
   },
   "scripts": {
     "start": "react-scripts start",
-    "build": "react-scripts build",
-    "test": "react-scripts test",
-    "eject": "react-scripts eject"
+    "build": "react-scripts build"
   },
   "eslintConfig": {
     "extends": "react-app"

examples/user_interaction/client/public/index.html

@@ -6,10 +6,7 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="theme-color" content="#000000" />
-  <!--
-      manifest.json provides metadata used when your web app is installed on a
-      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
-    -->
+
   <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
   <!-- Load bootstrap to see a resource load span -->
   <link href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.1/css/bootstrap.min.css" rel="stylesheet"
@@ -32,6 +29,9 @@ <h1>OpenCensus Web User Interaction Tracing!</h1>
     naming approach.
   </p>
   <div id="root"></div>
+  <script src="http://localhost:8080/tracing-all-with-zone.js"
+  async>
+  </script>
 </body>
 
 </html>

examples/user_interaction/client/src/App.js

@@ -108,9 +108,11 @@ class App extends React.Component {
       <div>
         <p>This example makes some calculations like calculate Pi using the series from
         and calculate the amount of prime numbers in between 1 and 100000. These
-        calculations are done using slow methods in order to measure the traces.</p>
+        calculations are done using slow methods in order to show long spans.</p>
 
-        <button id='trace_interaction' data-ocweb-id='Trace user interaction' onClick={this.handleClick}>Trace user interaction</button>
+        <button data-ocweb-id='Trace user interaction' onClick={this.handleClick}>Trace user interaction</button>
+        <br></br><br></br>
+        <button id='trace_interaction' onClick={this.handleClick}>Trace user interaction 2</button>
 
         <p>The value of Pi is: <code>{this.state.pi.value}</code> and it took
         <code> {this.state.pi.time} ms </code> to compute this.</p>

examples/user_interaction/client/src/index.js

@@ -41,7 +41,7 @@ const routing = (
 
 ReactDOM.render(routing, document.getElementById('root'));
 
-window.ocAgent = 'http://localhost:55678';
+window.ocAgent = 'http://104.196.170.62';
 // For the purpose of this example, send trace header to all hosts.
 window.ocTraceHeaderHostRegex = /.*/;
 window.ocSampleRate = 1.0; // Sample at 100% for test only. Default is 1/10000.

examples/user_interaction/server/package.json

@@ -24,6 +24,7 @@
     "@opencensus/exporter-zipkin": "^0.0.14",
     "@opencensus/nodejs": "^0.0.14",
     "@opencensus/propagation-tracecontext": "^0.0.14",
+    "fs": "*",
     "http": "*",
     "sleep": "^6.1.0"
   },

examples/user_interaction/server/server.js

@@ -28,6 +28,7 @@ const tracer = setupTracerAndExporters();
 const http = require('http');
 const url = require('url');
 const sleep = require('sleep');
+let fs = require('fs');
 
 /** Starts a HTTP server that receives requests on sample server port. */
 function startServer(port) {
@@ -95,22 +96,50 @@ function handleRequest(request, response) {
       sleep.sleep(2);
       result = { time: Date.now() - time, value: "" };
       console.log("Finished.")
+      request.on('end', () => {
+        span.end();
+        response.statusCode = code;
+        response.end(JSON.stringify(result));
+      });
     } else if (url.parse(request.url).pathname === '/prime_numbers') {
       console.log("Calculate prime numbers...")
       const time = Date.now();
       const prime_numbers = JSON.stringify(calculatePrimeNumbers());
       result = { time: Date.now() - time, value: prime_numbers };
       console.log("Finished.")
-    } else {
+      request.on('end', () => {
+        span.end();
+        response.statusCode = code;
+        response.end(JSON.stringify(result));
+      });
+    } else if (url.parse(request.url).pathname === '/'){
+      fs.readFile('../client/build/index.html', null, function (error, data) {
+        if (error) {
+            response.writeHead(404);
+            response.write('Whoops! File not found!');
+        } else {
+            response.write(data);
+        }
+        response.end();
+      }); 
       result = { time: 0, value: "unknown url" };
       code = 404;
+      return;
+    } else if(url.parse(request.url).pathname.startsWith('/static')){
+      console.log(request.url)
+      fs.readFile('../client/build/' + url.parse(request.url).pathname, null, function (error, data) {
+        if (error) {
+            response.writeHead(404);
+            response.write('Whoops! File not found!');
+        } else {
+            response.write(data);
+        }
+        response.end();
+      }); 
+      result = { time: 0, value: "unknown url" };
+      code = 404;
+      return
     }
-
-    request.on('end', () => {
-      span.end();
-      response.statusCode = code;
-      response.end(JSON.stringify(result));
-    });
   } catch (err) {
     console.log(err);
     span.end();

packages/opencensus-web-core/README.md

@@ -3,7 +3,7 @@
 
 *For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
 
-This package combines contains the core trace model used by OpenCensus Web. This
+This package contains the core trace model used by OpenCensus Web. This
 trace model is based on the same TypeScript interfaces that
 [OpenCensus Node](https://github.com/census-instrumentation/opencensus-node)
 uses.
@@ -13,8 +13,10 @@ The library is in alpha stage and the API is subject to change.
 ## Usage
 
 Currently the primary intended usage of OpenCensus Web is to collect
-spans from the resource timing waterfall of an initial page load. See the 
-[OpenCensus Web readme][oc-web-readme-url] for details.
+spans from the resource timing waterfall of an initial page load
+and trace on-page user interactions with a series of features like automatic tracing 
+for *clicks* and *route transitions*, *custom spans*, and browser [Performance API][performance-api] data.
+See the [OpenCensus Web readme][oc-web-readme-url] for details.
 
 In the future we would like to make it easy to generate custom spans that will
 be conveniently exported to the [OpenCensus Agent][opencensus-service-url]. This
@@ -35,7 +37,5 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [gitter-url]: https://gitter.im/census-instrumentation/lobby
 [oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
 [license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-core/LICENSE
-[long-tasks-url]: https://w3c.github.io/longtasks/
-[resource-timing-buffer-url]: https://www.w3.org/TR/resource-timing-2/#dom-performance-setresourcetimingbuffersize
-[resource-timing-url]: https://www.w3.org/TR/resource-timing-2/
 [opencensus-service-url]: https://github.com/census-instrumentation/opencensus-service
+[performance-api]: (https://developer.mozilla.org/en-US/docs/Web/API/Performance)

packages/opencensus-web-exporter-ocagent/README.md

@@ -20,8 +20,10 @@ expects traces to be sent in, see this
 ## Usage
 
 Currently the primary intended usage of OpenCensus Web is to collect
-spans from the resource timing waterfall of an initial page load. See the 
-[OpenCensus Web readme][oc-web-readme-url] for details.
+spans from the resource timing waterfall of an initial page load
+and trace on-page user interactions with a series of features like automatic tracing 
+for *clicks* and *route transitions*, *custom spans*, and browser [Performance API][performance-api] data.
+See the [OpenCensus Web readme][oc-web-readme-url] for details.
 
 In the future we would like to make it easy to generate custom spans that will
 be conveniently exported to the [OpenCensus Agent][opencensus-service-url]. This
@@ -46,3 +48,4 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [opencensus-service-url]: https://github.com/census-instrumentation/opencensus-service
 [oc-agent-http-url]: https://github.com/census-instrumentation/opencensus-service/blob/master/receiver/README.md#writing-with-httpjson
 [trace-openapi-url]: https://github.com/census-instrumentation/opencensus-proto/blob/master/gen-openapi/opencensus/proto/agent/trace/v1/trace_service.swagger.json
+[performance-api]: (https://developer.mozilla.org/en-US/docs/Web/API/Performance)

packages/opencensus-web-initial-load/README.md

@@ -7,18 +7,35 @@ This package contains the logic for the initial load page tracing.
 
 The library is in alpha stage and the API is subject to change.
 
-## Usage
+## Overview
 
-Currently the primary intended usage of OpenCensus Web is to collect
-spans from the resource timing waterfall of an initial page load. See the 
-[OpenCensus Web readme][oc-web-readme-url] for details.
+This package is currently exporting the trace associated to the initial load trace which
+generates a root span for the user navigation experience until the browser `load` event fires.
+This root span, will have several child spans corresponding to the loaded resources such as
+CSS or JS scripts. These spans are generated via the browser's [Navigation Timing][navigation-timing-url] and 
+[Resource Timing][resource-timing-url] APIs. Also, the [Long Tasks][long-tasks-url] browser API is 
+used to generate spans named as *long js task* for event loops taking more than 50 ms.
 
-This package is currently exporting the trace associated to the initial load trace.
 Additionally, the sampling decision for OpenCensus Web is done here and a global
-initial load span context is stored to be passed around. This allows other packages to
+*initial load span context* is stored to be passed around OC Web. This allows other packages to
 use the same sampling decision or relate their data to the initial load trace. This is the
 case for a `@opencensus/web-instrumentation-zone`.
 
+## Usage
+
+Currently the primary intended usage of OpenCensus Web is to collect
+spans from the resource timing waterfall of an initial page load
+and trace on-page user interactions with a series of features like automatic tracing 
+for *clicks* and *route transitions*, *custom spans*, and browser [Performance API][performance-api] data.
+See the [OpenCensus Web readme][oc-web-readme-url] for details.
+
+In the future we would like to make it easy to generate custom spans that will
+be conveniently exported to the [OpenCensus Agent][opencensus-service-url]. This
+package provides the exporter needed to hook up those custom generated spans to
+be sent to the agent and ultimately then to a trace storage backend. Although
+it's not fully wired up and supported yet, you're welcome to poke around the
+source code and try to use it!
+
 ## Useful links
 - For more information on OpenCensus, visit: <https://opencensus.io/>
 - For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
@@ -32,3 +49,8 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [gitter-url]: https://gitter.im/census-instrumentation/lobby
 [oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
 [license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-propagation-tracecontext/LICENSE
+[opencensus-service-url]: https://github.com/census-instrumentation/opencensus-service
+[performance-api]: https://developer.mozilla.org/en-US/docs/Web/API/Performance
+[navigation-timing-url]: https://www.w3.org/TR/navigation-timing-2/
+[long-tasks-url]: https://w3c.github.io/longtasks/
+[resource-timing-url]: https://www.w3.org/TR/resource-timing-2/