This document assumes familiarity with the concepts introduced in how-to-write-metrics.
HistogramSet JSON contains an unordered array of dictionaries, where each dictionary represents either a Histogram or a Diagnostic.
[ { "name": "my amazing metric", "unit": "ms", "binBoundaries": [0, [0, 100, 10]], "description": "this is my awesome amazing metric", "diagnostics": { "stories": "923e4567-e89b-12d3-a456-426655440000", }, "sampleValues": [0, 1, 42, -999999999.99999, null], "maxNumSampleValues": 1000, "numNans": 1, "nanDiagnostics": [ { "events": { "type": "RelatedEventSet", "events": [ { "stableId": "a.b.c", "title": "Title", "start": 0, "duration": 1 } ] } } ], "running": [5, 42, 0, -1, -999, -900, 100], "allBins": { "0": [1], "1": [1], }, "summaryOptions": { "nans": true, "percentile": [0.5, 0.95, 0.99], }, }, { "guid": "923e4567-e89b-12d3-a456-426655440000", "type": "GenericSet", "values": ["browse:news:cnn"], }, ]
name
: any stringunit
: underscore-separated string of 1 or 2 parts:description
: any string, allows metrics to explain results in more depthbinBoundaries
: an array that describes how to build bin boundaries The first element must be a number that specifies the boundary between the underflow bin and the first central bin. Subsequent elements can be eitherbinBoundaries
is undefined, then the Histogram contains single bin whose range spans -Number.MAX_VALUE
to Number.MAX_VALUE
diagnostics
: a DiagnosticMap that pertains to the entire Histogram, allows metrics to help users diagnose regressions and other problems. This can reference shared Diagnostics by guid
.sampleValues
: array of sample values to support Mann-Whitney U hypothesis testing to determine the significance of the difference between two Histograms.maxNumSampleValues
: maximum number of sample values If undefined, defaults to allBins.length * 10.numNans
: number of non-numeric samples added to the HistogramnanDiagnostics
: an array of DiagnosticMaps for non-numeric samplesrunning
: running statistics, an array of 7 numbers: count, max, meanlogs, mean, min, sum, varianceallBins
: either an array of Bins or a dictionary mapping from index to Bin: A Bin is an array containing either 1 or 2 elements:summaryOptions
: dictionary mapping from option names avg, geometricMean, std, count, sum, min, max, nans
to boolean flags. The special option percentile
is an array of numbers between 0 and 1. This allows metrics to specify which summary statistics are interesting and should be displayed.DiagnosticMap is a dictionary mapping strings to Diagnostic dictionaries.
The only field that is required for all Diagnostics, type
, must be one of
Breakdown
DateRange
GenericSet
RelatedEventSet
RelatedNameMap
Scalar
If a Diagnostic is in the root array of the JSON, then it is shared, so it may be referenced by multiple Histograms. Shared Diagnostics must contain a string field guid
containing a UUID.
If a Diagnostic is contained in a Histogram, then it must not have a guid
field.
The other fields of Diagnostic dictionaries depend on type
.
This allows metrics to explain the magnitude of a sample as composed of various categories.
values
: required dictionary mapping from a string category name to number valuescolorScheme
: optional string specifying how the bar chart should be coloredThis is a Range of Dates.
min
: Unix timestamp in msmax
: optional Unix timestamp in msThis allows metrics to store arbitrary untyped data in Histograms.
values
: array of any JSON data.This allows metrics to explain the magnitude of a sample as a parameter of a specific event or set of events in a trace.
events
: array of dictionaries containing stableId
, title
, start
, duration
fields of EventsThis is a Map from short descriptive names to full Histogram names.
names
: a dictionary mapping strings to strings containing Histogram names.Metrics should not use Scalar diagnostics since they cannot be safely merged.
value
: a dictionary containing a string unit
and a number value