1 | # OpenCensus Core Node.js
|
2 | [![Gitter chat][gitter-image]][gitter-url] ![Node Version][node-img] [![NPM Published Version][npm-img]][npm-url] ![dependencies Status][dependencies-status] ![devDependencies Status][devdependencies-status] ![Apache License][license-image]
|
3 |
|
4 | OpenCensus for Node.js is an implementation of OpenCensus, a toolkit for collecting application performance and behavior monitoring data. It currently includes 3 apis: stats, tracing and tags.
|
5 |
|
6 | The library is in alpha stage and the API is subject to change.
|
7 |
|
8 | ## Installation
|
9 |
|
10 | Install the opencensus-core package with NPM:
|
11 | ```bash
|
12 | npm install @opencensus/core
|
13 | ```
|
14 |
|
15 | ## Usage
|
16 |
|
17 | #### Get the global Stats manager instance.
|
18 |
|
19 | To enable metrics, we’ll import a few items from OpenCensus Core package.
|
20 |
|
21 | ```javascript
|
22 | const { globalStats, MeasureUnit, AggregationType, TagMap } = require('@opencensus/core');
|
23 |
|
24 | // The latency in milliseconds
|
25 | const mLatencyMs = globalStats.createMeasureDouble(
|
26 | "repl/latency",
|
27 | MeasureUnit.MS,
|
28 | "The latency in milliseconds"
|
29 | );
|
30 | ```
|
31 |
|
32 | #### Create Views and Tags:
|
33 |
|
34 | We now determine how our metrics will be organized by creating ```Views```. We will also create the variable needed to add extra text meta-data to our metrics – ```methodTagKey```, ```statusTagKey```, and ```errorTagKey```.
|
35 |
|
36 | ```javascript
|
37 | const methodTagKey = { name: "method" };
|
38 | const statusTagKey = { name: "status" };
|
39 | const errorTagKey = { name: "error" };
|
40 |
|
41 | // Create & Register the view.
|
42 | const latencyView = globalStats.createView(
|
43 | "demo/latency",
|
44 | mLatencyMs,
|
45 | AggregationType.DISTRIBUTION,
|
46 | [methodTagKey, statusTagKey, errorTagKey],
|
47 | "The distribution of the latencies",
|
48 | // Bucket Boundaries:
|
49 | // [>=0ms, >=25ms, >=50ms, >=75ms, >=100ms, >=200ms, >=400ms, >=600ms, >=800ms, >=1s, >=2s, >=4s, >=6s]
|
50 | [0, 25, 50, 75, 100, 200, 400, 600, 800, 1000, 2000, 4000, 6000]
|
51 | );
|
52 | globalStats.registerView(latencyView);
|
53 | ```
|
54 |
|
55 | #### Recording Metrics:
|
56 |
|
57 | Now we will record the desired metrics. To do so, we will use ```globalStats.record()``` and pass in measurements.
|
58 |
|
59 | ```javascript
|
60 | const [_, startNanoseconds] = process.hrtime();
|
61 | const tags = new TagMap();
|
62 | tags.set(methodTagKey, { value: "REPL" });
|
63 | tags.set(statusTagKey, { value: "OK" });
|
64 |
|
65 | globalStats.record([{
|
66 | measure: mLatencyMs,
|
67 | value: sinceInMilliseconds(startNanoseconds)
|
68 | }], tags);
|
69 |
|
70 | function sinceInMilliseconds(startNanoseconds) {
|
71 | const [_, endNanoseconds] = process.hrtime();
|
72 | return (endNanoseconds - startNanoseconds) / 1e6;
|
73 | }
|
74 | ```
|
75 |
|
76 | Measures can be of type `Int64` or `DOUBLE`, created by calling `createMeasureInt64` and `createMeasureDouble` respectively. Its units can be:
|
77 |
|
78 | | MeasureUnit | Usage |
|
79 | | ----------- | ----- |
|
80 | | `UNIT` | for general counts |
|
81 | | `BYTE` | bytes |
|
82 | | `KBYTE` | Kbytes |
|
83 | | `SEC` | seconds |
|
84 | | `MS` | millisecond |
|
85 | | `NS` | nanosecond |
|
86 |
|
87 | Views can have agregations of type `SUM`, `LAST_VALUE`, `COUNT` and `DISTRIBUTION`. To know more about Stats core concepts, please visit: [https://opencensus.io/core-concepts/metrics/](https://opencensus.io/core-concepts/metrics/)
|
88 |
|
89 | See [Quickstart/Metrics](https://opencensus.io/quickstart/nodejs/metrics/) for a full example of registering and collecting metrics.
|
90 |
|
91 | ## Useful links
|
92 | - For more information on OpenCensus, visit: <https://opencensus.io/>
|
93 | - To checkout the OpenCensus for Node.js, visit: <https://github.com/census-instrumentation/opencensus-node>
|
94 | - For help or feedback on this project, join us on [gitter](https://gitter.im/census-instrumentation/Lobby)
|
95 |
|
96 | [gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
|
97 | [gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
|
98 | [npm-url]: https://www.npmjs.com/package/@opencensus/core
|
99 | [npm-img]: https://badge.fury.io/js/%40opencensus%2Fcore.svg
|
100 | [node-img]: https://img.shields.io/node/v/@opencensus/core.svg
|
101 | [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
|
102 | [dependencies-status]: https://david-dm.org/census-instrumentation/opencensus-node/status.svg?path=packages/opencensus-core
|
103 | [devdependencies-status]:
|
104 | https://david-dm.org/census-instrumentation/opencensus-node/dev-status.svg?path=packages/opencensus-core
|
105 |
|
106 | ## LICENSE
|
107 |
|
108 | Apache License 2.0
|