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.
Here's a sample trace from OpenCensus Web that was exported to
Zipkin. Notice that there is an overall nav./ span for the user
navigation experience until the browser load event fires. There are also
/ spans for the client and server side measurements of the initial HTML load.
The server side spans also indicates how much time was spent parsing and
rendering the template:
These spans are generated via the browser's
Navigation Timing and
Resource Timing APIs. Notice also the long js task
span, which indicates a CPU-bound JavaScript event loop that took more than 50ms
as measured by the Long Tasks browser API.
The OpenCensus Web spans also include detailed annotations for DOM load events
like domInteractive and first-paint, as well as network events like
domainLookupStart and secureConnectionStart. Here is a similar trace
exported to Stckdriver Trace with the annotations
expanded:
These annotations also comine from the Resource Timing API. Note that for resources fetched via CORS, you will need to specify the Timing-Allow-Origin header.
The OpenCensus Web library exports traces via the OpenCensus Agent, which can then export them to a variety of trace backends. See the OpenCensus Agent/Collector exporter docs for details.
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.
The OpenCensus Web library currently only exports traces via the OpenCensus Agent, which can then export them to a trace backend (e.g. Zipkin, Stackdriver). 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.
You can use OpenCensus Web via a <script> tag that makes uses of the
<unpkg.com> CDN that serves files from NPM packages.
The script tag should go before the </body>. You will also need to set the
ocAgent endpoint in a different <script> and may also specify the
trace sample rate via an ocSampleRate global variable as well.
...
<script src="https://unpkg.com/@opencensus/[email protected]/dist/initial-load-all.js"
integrity="sha384-VPY9XX7tiXeLekDPFXkfO2AqNpLTCNOzfXxVghzoVP05PXrG+wtHOW2kOP2ggO9o"
async crossorigin="anonymous">
</script>
<script>
// HTTP endpoint of the OpenCensus Agent you ran and exposed to the internet
// in Step 1 above.
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>
</body>You can also host the initial-load-all.js bundle from your own site. For
docs on how to build the bundle see the
@opencensus/web-all readme.
If you already have a JS build pipeline using e.g. webpack or similar, you can
do npm install @opencensus/web-all, and then set the configuration variables
and trigger the recording and exporting of the initial load spans as follows:
import { exportRootSpanAfterLoadEvent } from '@opencensus/web-all';
window.ocAgent = 'https://example.com/my-opencensus-agent-endpoint';
window.ocSampleRate = 1.0; // Sample at 100% for test only. Default is 1/10000.
// Send the root span and child spans for the initial page load to the
// OpenCensus agent if this request was sampled for trace.
exportRootSpanAfterLoadEvent();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. For example:
...
<script src="https://unpkg.com/@opencensus/[email protected]/dist/initial-load-all.js"
integrity="sha384-VPY9XX7tiXeLekDPFXkfO2AqNpLTCNOzfXxVghzoVP05PXrG+wtHOW2kOP2ggO9o"
async crossorigin="anonymous">
</script>
<script>
ocAgent = 'https://example.com/my-opencensus-agent-endpoint';
// Set the `traceparent` in the server's HTML template code. It should be
// dynamically generated server side to have the server's request trace ID,
// a parent span ID that was set on the server's request span, and the trace
// flags to indicate the server's sampling decision (01 = sampled, 00 = not
// sampled).
traceparent = '00-{{ServerTraceId}}-{{ServerParentSpanId}}-{{ServerTraceFlags}}';
// We don't need to specify `ocSampleRate` since the trace sampling decision
// is coming from the `traceparent` global variable instead.
</script>
</body>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.
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
<script>tags.
- 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.