Skip to content
A stats collection and distributed tracing framework
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Switch to use Node 11 CircleCI docker environment (#44) Apr 15, 2019
.github Add @johnbryan to code owners (#60) Apr 24, 2019
examples/initial_load Rename globals prefix from `ocw` to `oc` (#56) Apr 15, 2019
packages Update per-package READMEs (#59) Apr 24, 2019
.gitignore Instructions for OC Web example in Kubernetes (#37) Apr 5, 2019
AUTHORS first commit Nov 9, 2017
CHANGELOG.md Update readme, add contributing guide & changelog (#43) Apr 15, 2019
CONTRIBUTING.md
LICENSE first commit Nov 9, 2017
README.md Add sample rate option and update README for it (#58) Apr 22, 2019
lerna.json Update lerna.json file to match devDependencies Jan 7, 2019
package-lock.json Upgrade lerna (`npm audit fix`) (#61) Apr 25, 2019
package.json Upgrade lerna (`npm audit fix`) (#61) Apr 25, 2019
renovate.json Add renovate config (#39) Apr 12, 2019

README.md

OpenCensus - A stats collection and distributed tracing framework

Gitter chat circleci codecov Known Vulnerabilities Apache License

OpenCensus Web is an implementation of OpenCensus, a toolkit for collecting application performance and behavior monitoring data. This library currently generates traces for the initial page load of a site in the browser. It supports sending the trace sampling decision and trace ID from the web server to the browser client to enable latency debugging across the stack.

The library is in alpha stage and the API is subject to change.

Please join gitter for help or feedback on this project.

Usage

NOTE: These usage instructions will likely change as the project matures. The goal is to make this easier to use over time!

See the examples/initial_load folder for a full example of how to use OpenCensus Web in an application. Below are the steps that are currently needed to use it.

1. Deploy the OpenCensus agent to collect traces

The OpenCensus Web library currently only exports traces via the OpenCensus Agent, which can then export them to a variety of tracing backends such as Zipkin, Jaeger, Stackdriver, DataDog, Honeycomb, and AWS X-Ray. See this example's README for steps to run the agent locally or in the cloud.

When you run the agent in the cloud you will need to expose it to your application via the internet. You may also to proxy the agent behind the authentication or CSRF protection layer of your application to to only allow traces to be written by authenticated end users.

2. Use the OpenCensus Web library code in your application

To include the OpenCensus Web library code, clone this repo and the build the JS bundles:

git clone https://github.com/census-instrumentation/opencensus-web
cd packages/opencensus-web-all
npm run build:prod

Then you copy the script ./dist/initial-load-all.js as a static asset of your application, and include it in a <script> tag, e.g. <script src="/static/initial-load-all.js"></script> assuming you were serving it from the /static folder of your site.

Once the OpenCensus Web packages are released to NPM, you will also be able to include them in your JavaScript build pipeline as an imported dependency.

In order to indicate the trace sampling rate and endpoint of the OpenCensus Agent so that traces can be written, you will need to include a snippet of JavaScript that sets the ocAgent and ocSampleRate global variables, for instance:

<script>
  ocAgent = 'https://example.com/my-opencensus-agent-endpoint';
  // Sample all requests for trace, which is useful when testing.
  // By default this is set to sample 1/10000 requests.
  ocSampleRate = 1.0; 
</script>

3. Optional: Send a trace parent and sampling decision from your server

OpenCensus Web also supports connecting the server side spans for the initial HTML load with the client side span for the load from the browser's timing API. This works by having the server send its parent trace context (trace ID, span ID and trace sampling decision) to the client.

Because the browser does not send a trace context header for the initial page navigation, the server needs to fake a trace context header in a middleware and then send that trace context header back to the client as a global traceparent variable. The traceparent variable should be in the trace context W3C draft format.

To see a full example of how the middleware to generate a trace context header and send it back to the client, see the server.go file and the index.html template in the examples/initial_load folder.

Packages

The OpenCensus web library is composed of the following packages:

Useful links

Versioning

This library follows Semantic Versioning.

GA: Libraries defined at a GA quality level are stable, and will not introduce backwards-incompatible changes in any minor or patch releases. We will address issues and requests with the highest priority. If we were to make a backwards-incompatible changes on an API, we will first mark the existing API as deprecated and keep it for 18 months before removing it.

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we're working towards their release candidate. We will address issues and requests with a higher priority. There may be backwards incompatible changes in a minor version release, though not in a patch release. If an element is part of an API that is only meant to be used by exporters or other opencensus libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18 months before removing it, if possible.

Alpha: Libraries defined at an Alpha quality level can be unstable and could cause crashes or data loss. Alpha software may not contain all of the features that are planned for the final version. The API is subject to change.

License

Apache 2.0 - See LICENSE for more information.

You can’t perform that action at this time.