Skip to content
This repository was archived by the owner on Oct 3, 2023. It is now read-only.

Commit 3bb31f0

Browse files
draffenspergerdraffensperger
authored
Update readme, add contributing guide & changelog (#43)
1 parent a02eff2 commit 3bb31f0

3 files changed

Lines changed: 199 additions & 7 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
## Unreleased
6+
7+
- TypeScript interfaces and enums extracted from the `@opencensus/core`
8+
package of [opencensus-node][opencensus-node-url]
9+
- Initial `Tracer` and `Span` implementations. The tracer only supports a single
10+
root span at a time within a browser tab.
11+
- Exporter to write traces to the OpenCensus Agent via its [HTTP/JSON feature][oc-agent-http-url].
12+
- Instrumentation to generate trace spans for the resource timing waterfall of
13+
an initial page load.
14+
- Option to link the initial HTML load client span with its server-side span by
15+
having the client write a `traceparent` global variable in
16+
[trace context W3C draft format][trace-context-url].
17+
- WebPack build scripts to generate JS bundles to enable adding instrumentation
18+
- of the initial page load spans and exporting them to the OpenCensus agent.
19+
20+
[oc-agent-http-url]: https://github.com/census-instrumentation/opencensus-service/tree/master/receiver#writing-with-httpjson
21+
[opencensus-node-url]: http://github.com/census-instrumentation/opencensus-node
22+
[trace-context-url]: https://www.w3.org/TR/trace-context/

‎CONTRIBUTING.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Contributing Guide
2+
3+
The `opencensus-web` project is written in TypeScript.
4+
5+
The command `npm test` tests code the same way that our CI will test it.
6+
This is a convenience command for a number of steps, which can run separately if needed:
7+
8+
- `npm run compile` compiles the code, checking for type errors.
9+
- `npm run bootstrap` Bootstrap the packages in the current Lerna repo. Installs all of their dependencies and links any cross-dependencies.
10+
11+
# How to become a contributor and submit your own code
12+
13+
## Contributor License Agreements
14+
15+
We'd love to accept your patches! Before we can take them, we have to jump a couple of legal hurdles.
16+
17+
Please fill out either the individual or corporate Contributor License Agreement (CLA).
18+
19+
* If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an [individual CLA][individual-cla-url].
20+
* If you work for a company that wants to allow you to contribute your work, then you'll need to sign a [corporate CLA][corporate-cla-url].
21+
22+
Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests.
23+
24+
## Contributing A Patch
25+
26+
1. Submit an issue describing your proposed change to the repo in question.
27+
1. The repo owner will respond to your issue promptly.
28+
1. Fork the desired repo, develop and test your code changes.
29+
1. Submit a pull request.
30+
1. If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
31+
32+
[individual-cla-url]: http://code.google.com/legal/individual-cla-v1.0.html
33+
[corporate-cla-url]: http://code.google.com/legal/corporate-cla-v1.0.html

‎README.md‎

Lines changed: 144 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,151 @@
1-
# OpenCensus for Web Browsers
1+
# OpenCensus - A stats collection and distributed tracing framework
22
[![Gitter chat][gitter-image]][gitter-url]
3+
[![circleci][circleci-image]][circleci-url]
4+
[![codecov][codecov-image]][codecov-url]
5+
[![Known Vulnerabilities][snyk-image]][snyk-url]
6+
[![Apache License][license-image]][license-url]
37

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

7-
The library is in an experimental pre-alpha stage and the API is subject to
8-
change, and is not suitable for production use.
14+
The library is in alpha stage and the API is subject to change.
915

10-
Please join [gitter](https://gitter.im/census-instrumentation/Lobby) for help or feedback on this
11-
project.
16+
Please join [gitter][gitter-url] for help or feedback on this project.
1217

18+
## Usage
19+
20+
**NOTE**: *These usage instructions will likely change as the project matures.
21+
The goal is to make this easier to use over time!*
22+
23+
See the [examples/initial_load][examples-initial-load-url] folder for a full
24+
example of how to use OpenCensus Web in an application. Below are
25+
the steps that are currently needed to use it.
26+
27+
### 1. Deploy the OpenCensus agent to collect traces
28+
29+
The OpenCensus Web library currently only exports traces via the
30+
[OpenCensus Agent][oc-agent-url], which can then export them to a variety of
31+
tracing backends such as Zipkin, Jaeger, Stackdriver, DataDog, Honeycomb,
32+
and AWS X-Ray. See this [example's README][initial-load-example-url]
33+
for steps to run the agent locally or in the cloud.
34+
35+
When you run the agent in the cloud you will need to expose it to your
36+
application via the internet. You may also to proxy the agent behind the
37+
authentication or CSRF protection layer of your application to to only allow
38+
traces to be written by authenticated end users.
39+
40+
### 2. Use the OpenCensus Web library code in your application
41+
42+
To include the OpenCensus Web library code, clone this repo and the build the JS
43+
bundles:
44+
```bash
45+
git clone https://github.com/census-instrumentation/opencensus-web
46+
cd packages/opencensus-web-all
47+
npm run build:prod
48+
```
49+
50+
Then you copy the script `./dist/initial-load-all.js` as a static asset
51+
of your application, and include it in a `<script>` tag, e.g.
52+
`<script src="/static/initial-load-all.js"></script>` assuming you were serving
53+
it from the `/static` folder of your site.
54+
55+
Once the OpenCensus Web packages are released to NPM, you will also be able to
56+
include them in your JavaScript build pipeline as an imported dependency.
57+
58+
In order to indicate the endpoint of the OpenCensus Agent so that traces can be
59+
written, you will need to include a snippet of JavaScript that sets the
60+
`ocAgent` global variable, for instance:
61+
62+
```html
63+
<script>ocAgent = 'https://example.com/my-opencensus-agent-endpoint'</script>
64+
```
65+
66+
### 3. Optional: Send a trace parent and sampling decision from your server
67+
68+
Currently, the OpenCensus Web will sample all requests by default. This is
69+
useful for experimentation with the library but is not appropriate for a real
70+
application.
71+
72+
OpenCensus Web also supports connecting the server side spans for the initial
73+
HTML load with the client side span for the load from the browser's timing API.
74+
75+
Because the browser does not send a trace context header for the initial page
76+
navigation, the server needs to fake a trace context header in a middleware and
77+
then send that trace context header back to the client as a global `traceparent`
78+
variable. The `traceparent` variable should be in the
79+
[trace context W3C draft format][trace-context-url].
80+
81+
To see a full example of how the middleware to generate a trace context header
82+
and send it back to the client, see the
83+
[server.go][initial-load-example-server-go] file and the
84+
[index.html][initial-load-example-index-html] template in the
85+
[examples/initial_load][initial-load-example-url] folder.
86+
87+
## Packages
88+
89+
The OpenCensus web library is composed of the following packages:
90+
91+
- **[@opencensus/web-types][package-web-types]**. This has automatically copied types from the [@opencensus/core][package-core] package of [OpenCensus Node][opencensus-node]. The types are copied because the `@opencensus/core` package has Node-specific dependencies that make it hard to depend on from browser-specific code.
92+
- **[@opencensus/web-core][package-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.
93+
- **[@opencensus/web-exporter-ocagent][package-web-exporter-ocagent]**. This handles exporting spans to the [OpenCensus Agent][opencensus-service-url]
94+
- **[@opencensus/web-instrumentation-perf][package-web-instrumentation-perf]**. This is code to convert the initial load resource waterfall timings from the browser [Navigation Timing API][navigation-timing-url] and [Resource Timing API][resource-timing-url] into the spans for a trace of the overall initial load for a page.
95+
- **[@opencensus/web-propagation-tracecontext][package-web-propagation-tracecontext]**. This provides utilities to serialize and deserialize a `traceparent` trace context header in the [W3C draft trace context format][trace-context-url]
96+
- **[@opencensus/web-all][package-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.
97+
98+
## Useful links
99+
- For more information on OpenCensus, visit: <https://opencensus.io/>
100+
- For help or feedback on this project, join us on [gitter][gitter-url]
101+
102+
## Versioning
103+
104+
This library follows [Semantic Versioning][semver-url].
105+
106+
**GA**: Libraries defined at a GA quality level are stable, and will not introduce
107+
backwards-incompatible changes in any minor or patch releases. We will address issues and requests
108+
with the highest priority. If we were to make a backwards-incompatible changes on an API, we will
109+
first mark the existing API as deprecated and keep it for 18 months before removing it.
110+
111+
**Beta**: Libraries defined at a Beta quality level are expected to be mostly stable and we're
112+
working towards their release candidate. We will address issues and requests with a higher priority.
113+
There may be backwards incompatible changes in a minor version release, though not in a patch
114+
release. If an element is part of an API that is only meant to be used by exporters or other
115+
opencensus libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18
116+
months before removing it, if possible.
117+
118+
**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.
119+
120+
## License
121+
122+
Apache 2.0 - See [LICENSE][license-url] for more information.
123+
124+
[circleci-image]: https://circleci.com/gh/census-instrumentation/opencensus-web.svg?style=shield
125+
[circleci-url]: https://circleci.com/gh/census-instrumentation/opencensus-web
126+
[codecov-image]: https://codecov.io/gh/census-instrumentation/opencensus-web/branch/master/graph/badge.svg
127+
[codecov-url]: https://codecov.io/gh/census-instrumentation/opencensus-web
128+
[examples-initial-load-url]: https://github.com/census-instrumentation/opencensus-web/tree/master/examples/initial_load
13129
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
14130
[gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
131+
[initial-load-example-index-html]: https://github.com/census-instrumentation/opencensus-web/blob/master/examples/initial_load/index.html
132+
[initial-load-example-server-go]: https://github.com/census-instrumentation/opencensus-web/blob/master/examples/initial_load/server.go
133+
[initial-load-example-url]: https://github.com/census-instrumentation/opencensus-web/tree/master/examples/initial_load
134+
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
135+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/LICENSE
136+
[navigation-timing-url]: https://www.w3.org/TR/navigation-timing-2/
137+
[oc-agent-url]: https://github.com/census-instrumentation/opencensus-service
138+
[opencensus-node-url]: https://github.com/census-instrumentation/opencensus-node
139+
[opencensus-service-url]: https://github.com/census-instrumentation/opencensus-service
140+
[package-core]: https://github.com/census-instrumentation/opencensus-node/tree/master/packages/opencensus-core
141+
[package-web-all]: https://github.com/census-instrumentation/opencensus-web/tree/master/packages/opencensus-web-all
142+
[package-web-core]: https://github.com/census-instrumentation/opencensus-web/tree/master/packages/opencensus-web-core
143+
[package-web-exporter-ocagent]: https://github.com/census-instrumentation/opencensus-web/tree/master/packages/opencensus-web-exporter-ocagent
144+
[package-web-instrumentation-perf]: https://github.com/census-instrumentation/opencensus-web/tree/master/packages/opencensus-web-instrumentation-perf
145+
[package-web-propagation-tracecontext]: https://github.com/census-instrumentation/opencensus-web/tree/master/packages/opencensus-web-propagation-tracecontext
146+
[package-web-types]: https://github.com/census-instrumentation/opencensus-web/tree/master/packages/opencensus-web-types
147+
[resource-timing-url]: https://www.w3.org/TR/resource-timing-2/
148+
[semver-url]: http://semver.org/
149+
[snyk-image]: https://snyk.io/test/github/census-instrumentation/opencensus-web/badge.svg?style=flat
150+
[snyk-url]: https://snyk.io/test/github/census-instrumentation/opencensus-web
151+
[trace-context-url]: https://www.w3.org/TR/trace-context/

0 commit comments

Comments
 (0)