OpenCensus Web types

For overview and usage info see the main OpenCensus Web readme.

This package provides TypeScript interfaces and enums for the OpenCensus core trace and metrics model. These are copied from the OpenCensus Node @opencensus/core package.

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

Why not just depend on @opencensus/core?

The @opencensus/core package includes some Node-specific dependencies that make it difficult to import in web-specific packages. This will be particularly true once OpenCensus Web supports building with Bazel (see rules_typescript on GitHub).

This package resolves these dependency issues by copying the types.ts and supporting files from the @opencensus/core. It also uses a polyfill for the NodeJS.EventEmitter type to avoid a dependency on the @types/node package.

Having the types copied will also make it easier to adopt a build with using Bazel (see rules_typescript), Tsickle, and Closure, which would result in more optimized (smaller) JS binary sizes.

How to refresh the types

To refresh the types for a new release (or a non-released commit) of @opencensus/core, modify the copytypes command in the package.json file with the git tag of the new release. You may need to also modify the list of copied files or the patching logic in the scripts/copy-types.js file.

Then run npm run copytypes to copy the types.

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 for details.

In the future we would like to support collecting spans for XHRs and other operations made after the initial page load and then join those back to the Resrouce Timing API information for more detailed network timings and events.

Useful links

• For more information on OpenCensus, visit: https://opencensus.io/
• For more about OpenCensus Web: https://github.com/census-instrumentation/opencensus-web
• For help or feedback on this project, join us on gitter

License

Apache 2.0 - See LICENSE for more information.

Changelog

All notable changes to this project will be documented in this file.

Unreleased

0.0.7 - 2019-09-09

• Support for B3 propagation with new @opencensus/web-propagation-b3 package and the ability to pass it in via startTracing({ propagation: Propagation }). Thanks @edvinasbartkus!

0.0.6 - 2019-08-26

• Fixed TypeError in Safari, thanks @backjo (#167)

0.0.5 - 2019-08-09

• Fixes to interaction tracker.
• Service name can be specified via window variable, thanks @Blightwidow
• Fixes to automated NPM publish script.

0.0.4 - 2019-08-06

• Rename @opencensus/web-all to @opencensus/web-scripts so now this package is only in charge of bundling OC Web to allow importing it as <script> tag.

• To use OC Web as an npm dependency, there are several options: @opencensus/web-initial-load to instrument with only the initial page load module, @opencensus/web-instrumentation-zone to instrument it with all the OC Web functionality plus the Zone.js library and @opencensus/web-instrumentation-zone-peer-dep also exports all the functionality but Zone.js is a peer dependency.

• Implementation of User interaction tracing monkey-patching the Zone.js library. This includes some features like: automatic tracing for click events and route transitions, custom spans, automatic spans for HTTP requests and Browser performance data, relate user interaction traces back the the initial page load trace and sampling.

0.0.3 - 2019-06-08

• Support custom end time for span (#95), thanks @skjindal93
• Upgraded types to match @opencensus/core package version 0.0.13.
• Package upgrades
• Add support for object(SpanOptions) as an argument for startChildSpan function, similar to startRootSpan.
• Please note that there is an API breaking change in methods addMessageEvent(). The field id is now number instead of string.

0.0.2 - 2019-04-29

Fix: add JS bundles and source maps to the NPM files for @opencensus/web-all (#66), which were incorrectly not included before. This enables linking the JS bundles in <script> tags via the unpkg.com or jsdelivr.com CDNs for NPM files.

0.0.1 - 2019-04-26

• TypeScript interfaces and enums extracted from the @opencensus/core package of opencensus-node
• Initial Tracer and Span implementations. The tracer only supports a single root span at a time within a browser tab.
• Exporter to write traces to the OpenCensus Agent via its HTTP/JSON feature.
• Instrumentation to generate trace spans for the resource timing waterfall of an initial page load.
• Option to link the initial HTML load client span with its server-side span by having the client write a traceparent global variable in trace context W3C draft format.
• WebPack build scripts to generate JS bundles to enable adding instrumentation of the initial page load spans and exporting them to the OpenCensus agent.