@opencensus/core

What is @opencensus/core?

The @opencensus/core package is a set of libraries for collecting, processing, and exporting telemetry data (metrics and traces) for analysis to improve the performance and reliability of applications. It is part of the OpenCensus project, which aims to provide a single, high-quality telemetry collection framework across multiple languages.

What are @opencensus/core's main functionalities?

Tracing

This feature allows the collection and export of trace data, which helps in understanding the flow of requests through various services and in identifying bottlenecks and latency issues.

const { Tracing } = require('@opencensus/core');
const tracing = Tracing.instance;

// Configure tracing
tracing.start({samplingRate: 1});

// Create a custom span
const rootSpan = tracing.tracer.startRootSpan({name: 'main'}, rootSpan => {
  // Do work within the span
  rootSpan.end(); // End the span
});

Metrics

This feature enables the collection and aggregation of metrics data, such as counts or latencies, which can be used for monitoring application performance and health.

const { Metrics, MeasureUnit } = require('@opencensus/core');
const metrics = Metrics.instance;

// Create a measure
const requestCountMeasure = metrics.createMeasureInt64('request_count', MeasureUnit.UNIT, 'Count of requests received');

// Create and register a view to aggregate the data
metrics.createView('request_count_view', requestCountMeasure, 'count', [], 'The count of requests', []);

// Record data
metrics.record([{measure: requestCountMeasure, value: 1}]);

Other packages similar to @opencensus/core

prom-client

The prom-client package is specifically designed for creating metrics in the Prometheus format. It focuses solely on metrics collection and exposition, unlike @opencensus/core, which supports both tracing and metrics. This makes prom-client a good choice if you are specifically looking for Prometheus support, but it lacks the tracing capabilities of @opencensus/core.

README

OpenCensus Core Node.js

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.

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

Installation

Install the opencensus-core package with NPM:

npm install @opencensus/core

Usage

Set up a new Stats manager instance.

To enable metrics, we’ll import a few items from OpenCensus Core package.

const { Stats, MeasureUnit, AggregationType } = require('@opencensus/core');

// Create the Stats manager
const stats = new Stats();

// The latency in milliseconds
const mLatencyMs = stats.createMeasureDouble(
  "repl/latency",
  MeasureUnit.MS,
  "The latency in milliseconds"
);

Create Views and Tags:

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.

const methodTagKey = "method";
const statusTagKey = "status";
const errorTagKey = "error";

const latencyView = stats.createView(
  "demo/latency",
  mLatencyMs,
  AggregationType.DISTRIBUTION,
  [methodTagKey, statusTagKey, errorTagKey],
  "The distribution of the latencies",
  // Bucket Boundaries:
  // [>=0ms, >=25ms, >=50ms, >=75ms, >=100ms, >=200ms, >=400ms, >=600ms, >=800ms, >=1s, >=2s, >=4s, >=6s]
  [0, 25, 50, 75, 100, 200, 400, 600, 800, 1000, 2000, 4000, 6000]
);

Recording Metrics:

Now we will record the desired metrics. To do so, we will use stats.record() and pass in measurements.

const [_, startNanoseconds] = process.hrtime();
const tags = {method: "repl", status: "OK"};

stats.record({
  measure: mLatencyMs,
  tags,
  value: sinceInMilliseconds(startNanoseconds)
});


function sinceInMilliseconds(startNanoseconds) {
  const [_, endNanoseconds] = process.hrtime();
  return (endNanoseconds - startNanoseconds) / 1e6;
}

See Quickstart/Metrics for a full example of registering and collecting metrics.

Useful links

• For more information on OpenCensus, visit: https://opencensus.io/
• To checkout the OpenCensus for Node.js, visit: https://github.com/census-instrumentation/opencensus-node
• For help or feedback on this project, join us on gitter

LICENSE

Apache License 2.0

Changelog

0.0.8 - 2018-12-14

Contains API breaking changes for stats/metrics implementations

• Enforce --noUnusedLocals Compiler Options on [opencensus-core] package.
• Fix bugs related to Stackdriver Metrics Descriptor and TimeSeries.
• Remove support for min/max in the stats Distribution to make it compatible with Metrics.
• Remove default prefix from [exporter-prometheus]. This could be a breaking change if you have Prometheus metrics from OpenCensus Prometheus exporter of previous versions, please point to the new metrics with no prefix instead.
• Zipkin exporter: Convert "timestamp" and "duration" to "number" type per spec.
• Exporter/Stats/Prometheus: Sanitize metric names.