OpenCensus - A stats collection and distributed tracing framework
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.
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.
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
ocSampleRate global variables,
<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 should be in the
trace context W3C draft format.
The OpenCensus web library is composed of the following packages:
- @opencensus/web-types. This has automatically copied types from the @opencensus/core package of [OpenCensus Node][opencensus-node]. The types are copied because the
@opencensus/corepackage has Node-specific dependencies that make it hard to depend on from browser-specific code.
- @opencensus/web-core. This has the core span and tracer implementation for web browsers. Currently the tracer assumes there is only one current root span for a given browser tab.
- @opencensus/web-exporter-ocagent. This handles exporting spans to the OpenCensus Agent
- @opencensus/web-instrumentation-perf. This is code to convert the initial load resource waterfall timings from the browser Navigation Timing API and Resource Timing API into the spans for a trace of the overall initial load for a page.
- @opencensus/web-propagation-tracecontext. This provides utilities to serialize and deserialize a
traceparenttrace context header in the W3C draft trace context format
- @opencensus/web-all. This depends on all the other OpenCensus Web libraries and provides top-level functions for instrumenting the initial page load and exporting its spans to the OpenCensus Agent. It also provides WebPack builds for JS bundles that can be used in
- For more information on OpenCensus, visit: https://opencensus.io/
- For help or feedback on this project, join us on gitter
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.
Apache 2.0 - See LICENSE for more information.