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

Commit ee5b86b

Browse files
draffenspergerdraffensperger
authored
Update per-package READMEs (#59)
1 parent 3d4d79b commit ee5b86b

File tree

6 files changed

+271
-29
lines changed

6 files changed

+271
-29
lines changed

‎packages/opencensus-web-all/README.md‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,63 @@
1-
# OpenCensus Web All package
1+
# OpenCensus Web All (JS bundles)
2+
[![Gitter chat][gitter-image]][gitter-url]
3+
4+
*For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
25

36
This package combines all of the main functionality of the OpenCensus Web
47
packages into a variety of distributions for easy inclusion into web
58
applications via a `<script>` tag.
9+
10+
The library is in alpha stage and the API is subject to change.
11+
12+
## Build commands
13+
14+
To generate production minified JS bundles run `npm run build:prod`. For
15+
non-minified bundles use `npm run build:dev`.
16+
17+
To serve the bundles from a local webpack server run `npm run
18+
start:webpack-server`.
19+
20+
## Generated scripts
21+
22+
These are the generated bundles.
23+
24+
If you don't mind loading a single larger bundle on the initial page load, use:
25+
26+
* **`./dist/initial-load-all.js`** - This script combines the functionality of
27+
the `instrument-initial-load.js` and `export-initial-load.js` below. That
28+
is, it records spans based on the [resource timing API][resource-timing-url]
29+
for the initial page load and exports it to the OpenCensus Agent based on
30+
configured global variables. See the main
31+
[OpenCensus Web readme][oc-web-readme-url] for details.
32+
33+
If you would like to minimize the amount of JS loaded initially, you can use
34+
these two bundles to do instrumentation first and then an export more lazily:
35+
36+
* **`./dist/instrument-initial-load.js`** - This is a small script that sets up the
37+
instrumentation configuration for getting resource timing span data for the
38+
initial page load. Specifically, it starts recording
39+
[Long Tasks][long-tasks-url] and increases the
40+
[resource timing buffer size][resource-timing-buffer-url]. This code should
41+
be loaded as part of the initial page load
42+
* **`./dist/export-initial-load.js`** - This script exports the resouce timing
43+
and long task information for the initial load to the agent. It can be
44+
retrieved after the initial page load has fully completed so it being
45+
downloaded and parsed doesn't need to compete with resources for the main
46+
page load.
47+
48+
## Useful links
49+
- For more information on OpenCensus, visit: <https://opencensus.io/>
50+
- For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
51+
- For help or feedback on this project, join us on [gitter][gitter-url]
52+
53+
## License
54+
55+
Apache 2.0 - See [LICENSE][license-url] for more information.
56+
57+
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
58+
[gitter-url]: https://gitter.im/census-instrumentation/lobby
59+
[oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
60+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-all/LICENSE
61+
[long-tasks-url]: https://w3c.github.io/longtasks/
62+
[resource-timing-buffer-url]: https://www.w3.org/TR/resource-timing-2/#dom-performance-setresourcetimingbuffersize
63+
[resource-timing-url]: https://www.w3.org/TR/resource-timing-2/

‎packages/opencensus-web-core/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# OpenCensus Web Core (Trace Model)
2+
[![Gitter chat][gitter-image]][gitter-url]
3+
4+
*For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
5+
6+
This package combines contains the core trace model used by OpenCensus Web. This
7+
trace model is based on the same TypeScript interfaces that
8+
[OpenCensus Node](https://github.com/census-instrumentation/opencensus-node)
9+
uses.
10+
11+
The library is in alpha stage and the API is subject to change.
12+
13+
## Usage
14+
15+
Currently the primary intended usage of OpenCensus Web is to collect
16+
spans from the resource timing waterfall of an initial page load. See the
17+
[OpenCensus Web readme][oc-web-readme-url] for details.
18+
19+
In the future we would like to make it easy to generate custom spans that will
20+
be conveniently exported to the [OpenCensus Agent][opencensus-service-url]. This
21+
package has the API that will support generation of custom spans. Although it's
22+
not fully wired up and supported yet, you're welcome to poke around the source
23+
code and try to use it!
24+
25+
## Useful links
26+
- For more information on OpenCensus, visit: <https://opencensus.io/>
27+
- For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
28+
- For help or feedback on this project, join us on [gitter][gitter-url]
29+
30+
## License
31+
32+
Apache 2.0 - See [LICENSE][license-url] for more information.
33+
34+
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
35+
[gitter-url]: https://gitter.im/census-instrumentation/lobby
36+
[oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
37+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-core/LICENSE
38+
[long-tasks-url]: https://w3c.github.io/longtasks/
39+
[resource-timing-buffer-url]: https://www.w3.org/TR/resource-timing-2/#dom-performance-setresourcetimingbuffersize
40+
[resource-timing-url]: https://www.w3.org/TR/resource-timing-2/
41+
[opencensus-service-url]: https://github.com/census-instrumentation/opencensus-service

‎packages/opencensus-web-exporter-ocagent/README.md‎

Lines changed: 43 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,48 @@
1-
# OpenCensus Agent Exporter for web browser clients
1+
# OpenCensus Web exporter for the OpenCensus Agent
2+
[![Gitter chat][gitter-image]][gitter-url]
23

3-
The OpenCensus Agent Exporter allows browser clients to send traces to the via
4-
HTTP/JSON. This is possible now that the OpenCensus Agent supports
5-
`grpc-gateway` for writing traces (see
6-
[relevant PR](https://github.com/census-instrumentation/opencensus-service/pull/270)).
4+
*For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
75

6+
This OpenCensus Web agent exporter allows browser clients to send traces to the
7+
[OpenCensus Agent][opencensus-service-url] via HTTP/JSON, which the [agent
8+
supports][oc-agent-http-url] via `grpc-gateway`.
89

9-
This project is still at an early stage of development, it's subject to change.
10+
The library is in alpha stage and the API is subject to change.
1011

11-
For the shape of the HTTP/JSON API, see the [auto-generated OpenAPi document for
12-
it](https://github.com/census-instrumentation/opencensus-proto/blob/master/gen-openapi/opencensus/proto/agent/trace/v1/trace_service.swagger.json).
12+
## Overview
1313

14-
This package has a dev dependency on the
15-
[@opencensus/core](https://www.npmjs.com/package/@opencensus/core) package that
16-
was written for the
17-
[OpenCensus Node](https://github.com/census-instrumentation/opencensus-node)
18-
library. That dev dependency allows the library to conform to the same
19-
interfaces provided in `@opencensus/core`, but it uses Webpack to prevent any of
20-
the Node.js specific dependencies from being included in the generated code
21-
for it.
14+
This package converts spans from the OpenCensus Web core trace model into the
15+
JSON that the OpenCensus Agent expects and sends an XHR to the agent to export
16+
the traces. For the shape of the HTTP/JSON API that the OpenCensus Agent
17+
expects traces to be sent in, see this
18+
[auto-generated OpenAPi document for it][trace-openapi-url].
19+
20+
## Usage
21+
22+
Currently the primary intended usage of OpenCensus Web is to collect
23+
spans from the resource timing waterfall of an initial page load. See the
24+
[OpenCensus Web readme][oc-web-readme-url] for details.
25+
26+
In the future we would like to make it easy to generate custom spans that will
27+
be conveniently exported to the [OpenCensus Agent][opencensus-service-url]. This
28+
package provides the exporter needed to hook up those custom generated spans to
29+
be sent to the agent and ultimately then to a trace storage backend. Although
30+
it's not fully wired up and supported yet, you're welcome to poke around the
31+
source code and try to use it!
32+
33+
## Useful links
34+
- For more information on OpenCensus, visit: <https://opencensus.io/>
35+
- For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
36+
- For help or feedback on this project, join us on [gitter][gitter-url]
37+
38+
## License
39+
40+
Apache 2.0 - See [LICENSE][license-url] for more information.
41+
42+
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
43+
[gitter-url]: https://gitter.im/census-instrumentation/lobby
44+
[oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
45+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-exporter-ocagent/LICENSE
46+
[opencensus-service-url]: https://github.com/census-instrumentation/opencensus-service
47+
[oc-agent-http-url]: https://github.com/census-instrumentation/opencensus-service/blob/master/receiver/README.md#writing-with-httpjson
48+
[trace-openapi-url]: https://github.com/census-instrumentation/opencensus-proto/blob/master/gen-openapi/opencensus/proto/agent/trace/v1/trace_service.swagger.json

‎packages/opencensus-web-instrumentation-perf/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# OpenCensus Web instrumentation for web performance APIs
2+
[![Gitter chat][gitter-image]][gitter-url]
3+
4+
*For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
5+
6+
This package generates OpenCensus Web trace model spans based on performance API
7+
data provided by the browser. Specifically, it generates spans for the initial
8+
page load of a site based on the [Resource Timing][resource-timing-url],
9+
[Navigation Timing][nav-timing-url], and [Long Task][long-tasks-url] browser
10+
APIs. It attempts to gracefully degrade for older browsers that do not support
11+
those timing APIs, but it has not been tested yet for browser compatibility.
12+
13+
The library is in alpha stage and the API is subject to change.
14+
15+
## Usage
16+
17+
Currently the primary intended usage of OpenCensus Web is to collect
18+
spans from the resource timing waterfall of an initial page load. See the
19+
[OpenCensus Web readme][oc-web-readme-url] for details.
20+
21+
In the future we would like to support collecting spans for XHRs and other
22+
operations made after the initial page load and then join those back to the
23+
Resrouce Timing API information for more detailed network timings and events.
24+
25+
## Useful links
26+
- For more information on OpenCensus, visit: <https://opencensus.io/>
27+
- For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
28+
- For help or feedback on this project, join us on [gitter][gitter-url]
29+
30+
## License
31+
32+
Apache 2.0 - See [LICENSE][license-url] for more information.
33+
34+
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
35+
[gitter-url]: https://gitter.im/census-instrumentation/lobby
36+
[oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
37+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-instrumentation-perf/LICENSE
38+
[nav-timing-url]: https://www.w3.org/TR/navigation-timing-2/
39+
[resource-timing-url]: https://www.w3.org/TR/resource-timing-2/
40+
[long-tasks-url]: https://w3c.github.io/longtasks/

‎packages/opencensus-web-propagation-tracecontext/README.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,39 @@
1-
# OpenCensus Trace Context Format Propagation for Web Browsers
1+
# OpenCensus Trace Context format propagation for web browsers
2+
[![Gitter chat][gitter-image]][gitter-url]
23

3-
OpenCensus Trace Context Format Propagation sends a span context on the wire in an HTTP request, allowing other services to create spans with the right context.
4+
*For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
45

5-
This project is still at an early stage of development. It's subject to change.
6+
OpenCensus Trace Context format propagation provides utilities to serialize and
7+
deserialize a trace context header in the [W3C Trace Context][trace-context-url]
8+
format.
69

7-
See https://www.w3.org/TR/trace-context/ for details about the Trace Context
8-
header format.
10+
The library is in alpha stage and the API is subject to change.
11+
12+
## Usage
13+
14+
Currently the primary intended usage of OpenCensus Web is to collect
15+
spans from the resource timing waterfall of an initial page load. See the
16+
[OpenCensus Web readme][oc-web-readme-url] for details.
17+
18+
This package is currently used to deserialize the `window.traceparent` global
19+
variable that the server can send back to the client to indicate the parent
20+
trace context for the initial page load.
21+
22+
In the future we would like to support propagating trace contextspans for XHRs,
23+
and this library could be used to also serialize a `traceparent` header to send
24+
along to XHR calls.
25+
26+
## Useful links
27+
- For more information on OpenCensus, visit: <https://opencensus.io/>
28+
- For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
29+
- For help or feedback on this project, join us on [gitter][gitter-url]
30+
31+
## License
32+
33+
Apache 2.0 - See [LICENSE][license-url] for more information.
34+
35+
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
36+
[gitter-url]: https://gitter.im/census-instrumentation/lobby
37+
[oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
38+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-propagation-tracecontext/LICENSE
39+
[trace-context-url]: https://www.w3.org/TR/trace-context/

‎packages/opencensus-web-types/README.md‎

Lines changed: 52 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,17 @@
11
# OpenCensus Web types
2+
[![Gitter chat][gitter-image]][gitter-url]
23

3-
Since both OpenCensus Web and OpenCensus Node are designed for JavaScript
4-
applications, we would like to keep type compatibility between them.
4+
*For overview and usage info see the main [OpenCensus Web readme][oc-web-readme-url].*
55

6-
However the `@opencensus/core` package includes some Node-specific dependencies
6+
This package provides TypeScript interfaces and enums for the OpenCensus core
7+
trace and metrics model. These are copied from the OpenCensus Node
8+
[@opencensus/core][opencensus-core-url] package.
9+
10+
The library is in alpha stage and the API is subject to change.
11+
12+
## Why not just depend on `@opencensus/core`?
13+
14+
The `@opencensus/core` package includes some Node-specific dependencies
715
that make it difficult to import in web-specific packages. This will be
816
particularly true once OpenCensus Web supports building with Bazel (see
917
[rules_typescript](https://github.com/bazelbuild/rules_typescript) on GitHub).
@@ -12,7 +20,44 @@ This package resolves these dependency issues by copying the `types.ts` and
1220
supporting files from the `@opencensus/core`. It also uses a polyfill for the
1321
`NodeJS.EventEmitter` type to avoid a dependency on the `@types/node` package.
1422

15-
To refresh the types for a new release of `@opencensus/core`, modify the
16-
`copytypes` command in the `package.json` file with the git tag of the new
17-
release. You may need to also modify the list of copied files or the patching
18-
logic in the `scripts/copy-types.js` file.
23+
Having the types copied will also make it easier to adopt a build with using
24+
Bazel (see [rules_typescript][rules-typescript-url]), [Tsickle][tsickle-url],
25+
and [Closure][closure-url], which would result in more optimized
26+
(smaller) JS binary sizes.
27+
28+
## How to refresh the types
29+
30+
To refresh the types for a new release (or a non-released commit) of
31+
`@opencensus/core`, modify the `copytypes` command in the `package.json` file
32+
with the git tag of the new release. You may need to also modify the list of
33+
copied files or the patching logic in the `scripts/copy-types.js` file.
34+
35+
Then run `npm run copytypes` to copy the types.
36+
37+
## Usage
38+
39+
Currently the primary intended usage of OpenCensus Web is to collect
40+
spans from the resource timing waterfall of an initial page load. See the
41+
[OpenCensus Web readme][oc-web-readme-url] for details.
42+
43+
In the future we would like to support collecting spans for XHRs and other
44+
operations made after the initial page load and then join those back to the
45+
Resrouce Timing API information for more detailed network timings and events.
46+
47+
## Useful links
48+
- For more information on OpenCensus, visit: <https://opencensus.io/>
49+
- For more about OpenCensus Web: <https://github.com/census-instrumentation/opencensus-web>
50+
- For help or feedback on this project, join us on [gitter][gitter-url]
51+
52+
## License
53+
54+
Apache 2.0 - See [LICENSE][license-url] for more information.
55+
56+
[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
57+
[gitter-url]: https://gitter.im/census-instrumentation/lobby
58+
[opencensus-core-url]: https://github.com/census-instrumentation/opencensus-node/tree/master/packages/opencensus-core
59+
[oc-web-readme-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/README.md
60+
[license-url]: https://github.com/census-instrumentation/opencensus-web/blob/master/packages/opencensus-web-instrumentation-perf/LICENSE
61+
[rules-typescript-url]: https://github.com/bazelbuild/rules_typescript
62+
[tsickle-url]: https://github.com/angular/tsickle
63+
[closure-url]: https://github.com/google/closure-compiler

0 commit comments

Comments
 (0)