HistogramSet JSON Format

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"],
  },
]

Histograms

Required fields

• name: any string
• unit: underscore-separated string of 1 or 2 parts:
  • The required unit base name must be one of
    • ms
    • tsMs
    • n%
    • sizeInBytes
    • J
    • W
    • unitless
    • count
    • sigma
  • Optional improvement direction must be one of
    • biggerIsBetter
    • smallerIsBetter

Optional fields

• description: any string, allows metrics to explain results in more depth
• binBoundaries: 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 either
  • numbers specifying bin boundaries, or
  • arrays of 3 numbers that specify how to build sequences of bin boundaries:
    • The first of which is an enum:
      • 0 (LINEAR)
      • 1 (EXPONENTIAL)
    • The second number is the maximum bin boundary of the sequence.
    • The third and final number is the number of bin boundaries in the sequence. If binBoundaries 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 Histogram
• nanDiagnostics: an array of DiagnosticMaps for non-numeric samples
• running: running statistics, an array of 7 numbers: count, max, meanlogs, mean, min, sum, variance
• allBins: either an array of Bins or a dictionary mapping from index to Bin: A Bin is an array containing either 1 or 2 elements:
  • Required number bin count,
  • Optional array of sample DiagnosticMaps
• 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.

Diagnostics

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.

Breakdown

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 values
• colorScheme: optional string specifying how the bar chart should be colored

DateRange

This is a Range of Dates.

• min: Unix timestamp in ms
• max: optional Unix timestamp in ms

GenericSet

This allows metrics to store arbitrary untyped data in Histograms.

• values: array of any JSON data.

RelatedEventSet

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 Events

RelatedNameMap

This is a Map from short descriptive names to full Histogram names.

• names: a dictionary mapping strings to strings containing Histogram names.

Scalar

Metrics should not use Scalar diagnostics since they cannot be safely merged.

• value: a dictionary containing a string unit and a number value