OpenCensus is being archived! Read the blog post to learn more

Measure

Measure

A measure represents a metric type to be recorded. For example, request latency in µs and request size in KBs are examples of measures to collect from a server.

Definition

All measures are identified by a name and also have a description and a unit. Libraries and frameworks can define and export measures for their end users to collect data on the provided measures.

Constituent Description Example Restrictions
Name a string by which the measure will be referred to by “rpc_server_latency”, “vm_cpu_cycles” MUST be unique within the library. It is recommended to use names compatible with the intended end usage e.g. use host/path pattern
Description a string detailing the purpose of the measure “RPC latency in milliseconds”, “Virtual cycles executed on a VM
Unit a string descriptive of the unit of the Measure “By”, “1”, “ms” MUST follow Unified code for units of
measure

Types

OpenCensus currently supports two types of measures

Type Description
Int64 Records int-like values
Float64 Records float-like values

Recording measurements

Measurements are produced by recording a numeric value with a Measure usually in a tagContext

Source code example

package main

import (
	"go.opencensus.io/stats"
)

func main() {
	mLatencyMs = stats.Float64("latency", "The latency in milliseconds", "ms")
	mLines = stats.Int64("lines_in", "The number of lines processed", "1")
	mBytesIn = stats.Int64("bytes_in", "The number of bytes received", "By")

	// Invoking .M produces measurements that we then record against
	// a context "ctx" with tags.
	stats.Record(ctx,
		mLatencyMs.M(17),
		mLines.M(238),
		mBytesIn.M(7000))
}
package io.opencensus.metrics.snippet;

import io.opencensus.stats.Measure.MeasureDouble;
import io.opencensus.stats.Measure.MeasureLong;
import io.opencensus.stats.Stats;
import io.opencensus.stats.StatsRecorder;

public class JavaSnippet {
    private static final MeasureDouble M_LATENCY_MS = MeasureDouble.create("latency", "The latency in milliseconds", "ms");
    private static final MeasureLong M_LINES = MeasureLong.create("lines_in", "The number of lines processed", "1");
    private static final MeasureLong M_BYTES_IN = MeasureLong.create("bytes_in", "The number of bytes received", "By");

    private static final StatsRecorder STATS_RECORDER = Stats.getStatsRecorder();

    public static void main(String[] args) {
        // Record the values, having already added tags in the current context
        STATS_RECORDER.newMeasureMap()
                .put(M_LATENCY_MS, 17.0)
                .put(M_LINES, 238)
                .put(M_BYTES_IN, 7000)
                .record();
    }
}
#/usr/bin/env python

from opencensus.stats import stats
from opencensus.stats import measure

def main():
    m_latency_ms = measure.MeasureFloat("latency", "The latency in milliseconds", "ms")
    m_lines = measure.MeasureInt("lines_in", "The number of lines processed", "1")
    m_bytes_in = measure.MeasureInt("bytes_in", "The number of bytes received", "By")

    mmap = stats.Stats().stats_recorder.new_measurement_map()
    mmap.measure_float_put(m_latency_ms, 17)
    mmap.measure_int_put(m_lines, 238)
    mmap.measure_int_put(m_bytes_in, 7000)

    # Record the measurements against tags in "tmap"
    mmap.record(tmap);

if __name__ == '__main__':
    main()
#include "opencensus/stats/stats.h"

opencensus::stats::MeasureDouble LatencyMsMeasure() {
    static const auto measure = opencensus::stats::MeasureDouble::Register(
            "latency", "The latency in milliseconds", "ms");
    return measure;
}

opencensus::stats::MeasureInt64 LinesMeasure() {
    static const auto measure = opencensus::stats::MeasureInt64::Register(
            "lines_in", "The number of lines processed", "1");
    return measure;
}

opencensus::stats::MeasureInt64 BytesInMeasure() {
    static const auto measure = opencensus::stats::MeasureInt64::Register(
            "bytes_in", "The number of bytes received", "By");
    return measure;
}

int main(int argc, char** argv) {
    opencensus::stats::Record({
            {LatencyMsMeasure(), 17.0},
            {LinesMeasure(), 238},
            {BytesInMeasure(), 7000}
    });
}
import { globalStats, MeasureUnit } from "@opencensus/core";

const mLatencyMs = globalStats.createMeasureDouble("latency", MeasureUnit.MS, "The latency in milliseconds");
const mBytesIn = globalStats.createMeasureInt64("size", MeasureUnit.BYTE, "The number of bytes received");

const measurement1 = {measure: mLatencyMs, value: 17};
const measurement2 = {measure: mBytesIn, value: 7000};

globalStats.record([measurement1, measurement2]);

Relation to Measurements

When a Measure records a value, it produces a Measurement.

Relation to Views

A View couples the Measurement produced by a Measure, with an Aggregation and optionally Tags to produce metrics.

References

Resource URL
Unified code for units of measure http://unitsofmeasure.org/ucum.html
Measure in the specs specs/Record.Measure
Go Measures stats.Measure
Java Measures stats.Measure
Python Measures stats.measure.Measure
C++ Measures stats/measure.h
Node.js Measures stats.Measure