prom2json

README

prom2json

A tool to scrape a Prometheus client and dump the result as JSON.

Background

(Pre-)historically, Prometheus clients were able to expose metrics as JSON. For various reasons, the JSON exposition format was deprecated.

Usually, scraping of a Prometheus client is done by the Prometheus server, which preferably happens with the protocol buffer format. Sometimes, a human being needs to inspect what a Prometheus clients exposes. In that case, the text format is used (which is otherwise meant to allow simplistic clients like shell scripts to expose metrics to a Prometheus server).

However, some users wish to scrape Prometheus clients with programs other than the Prometheus server. Those programs would usually use the protocol buffer format, but for small ad hoc programs, that is too much of an (programming) overhead. JSON comes in handy for these use-cases, as many languages offer tooling for JSON parsing.

To avoid maintaining a JSON format in all client libraries, the prom2json tool has been created, which scrapes a Prometheus client in protocol buffer or text format and dumps the result as JSON to stdout.

Usage

Installing and building:

$ go get github.com/prometheus/prom2json/cmd/prom2json

Running:

$ prom2json http://my-prometheus-client.example.org:8080/metrics

Running with TLS client authentication:

$ prom2json --cert=/path/to/certificate --key=/path/to/key http://my-prometheus-client.example.org:8080/metrics

This will dump the JSON to stdout. Note that the dumped JSON is not using the deprecated JSON format as specified in the Prometheus exposition format reference. The created JSON uses a format much closer in structure to the protocol buffer format. It is only used by the prom2json tool and has no significance elsewhere. See below for a description.

A typical use-case is to pipe the JSON format into a tool like jq to run a query over it. That looked like the following when the clients still supported the deprecated JSON format:

$ curl http://my-prometheus-client.example.org:8080/metrics | jq .

Now simply use prom2json instead of curl (and change the query syntax according to the changed JSON format generated by prom2json):

$ prom2json http://my-prometheus-client.example.org:8080/metrics | jq .

Example query to retrieve the number of metrics in the http_requests_total metric family (only works with the new format):

$ prom2json http://my-prometheus-client.example.org:8080/metrics | jq '.[]|select(.name=="http_requests_total")|.metrics|length'

JSON format

Note that all numbers are encoded as strings. Some parsers want it that way. Also, Prometheus allows sample values like NaN or +Inf, which cannot be encoded as JSON numbers.

[
  {
    "name": "http_request_duration_microseconds",
    "help": "The HTTP request latencies in microseconds.",
    "type": "SUMMARY",
    "metrics": [
      {
        "labels": {
          "method": "get",
          "handler": "prometheus",
          "code": "200"
        },
        "quantiles": {
          "0.99": "67542.292",
          "0.9": "23902.678",
          "0.5": "6865.718"
        },
        "count": "743",
        "sum": "6936936.447000001"
      },
      {
        "labels": {
          "method": "get",
          "handler": "prometheus",
          "code": "400"
        },
        "quantiles": {
          "0.99": "3542.9",
          "0.9": "1202.3",
          "0.5": "1002.8"
        },
        "count": "4",
        "sum": "345.01"
      }
    ]
  },
  {
    "name": "roshi_select_call_count",
    "help": "How many select calls have been made.",
    "type": "COUNTER",
    "metrics": [
      {
        "value": "1063110"
      }
    ]
  }
]

Using Docker

You can deploy this tool using the prom/prom2json Docker image.

For example:

docker pull prom/prom2json

docker run --rm -ti prom/prom2json http://my-prometheus-client.example.org:8080/metrics

Documentation

Index

• func FetchMetricFamilies(url string, ch chan<- *dto.MetricFamily, certificate string, key string, ...) error
• func ParseResponse(resp *http.Response, ch chan<- *dto.MetricFamily) error
• type Family
  • func NewFamily(dtoMF *dto.MetricFamily) *Family
  • func (f *Family) AddLabel(key, val string)
• type Histogram
• type Metric
• type Summary

Functions

func FetchMetricFamilies

func FetchMetricFamilies(
	url string, ch chan<- *dto.MetricFamily,
	certificate string, key string,
	skipServerCertCheck bool,
) error

FetchMetricFamilies retrieves metrics from the provided URL, decodes them into MetricFamily proto messages, and sends them to the provided channel. It returns after all MetricFamilies have been sent.

func ParseResponse

func ParseResponse(resp *http.Response, ch chan<- *dto.MetricFamily) error

ParseResponse consumes an http.Response and pushes it to the MetricFamily channel. It returns when all all MetricFamilies are parsed and put on the channel.

Types

type Family

type Family struct {
	//Time    time.Time
	Name    string        `json:"name"`
	Help    string        `json:"help"`
	Type    string        `json:"type"`
	Metrics []interface{} `json:"metrics,omitempty"` // Either metric or summary.
}

Family mirrors the MetricFamily proto message.

func NewFamily

func NewFamily(dtoMF *dto.MetricFamily) *Family

NewFamily consumes a MetricFamily and transforms it to the local Family type.

func (*Family) AddLabel

func (f *Family) AddLabel(key, val string)

AddLabel allows to add key/value labels to an already existing Family.

type Histogram

type Histogram struct {
	Labels  map[string]string `json:"labels,omitempty"`
	Buckets map[string]string `json:"buckets,omitempty"`
	Count   string            `json:"count"`
	Sum     string            `json:"sum"`
}

Histogram mirrors the Histogram proto message.

type Metric

type Metric struct {
	Labels map[string]string `json:"labels,omitempty"`
	Value  string            `json:"value"`
}

Metric is for all "single value" metrics, i.e. Counter, Gauge, and Untyped.

type Summary

type Summary struct {
	Labels    map[string]string `json:"labels,omitempty"`
	Quantiles map[string]string `json:"quantiles,omitempty"`
	Count     string            `json:"count"`
	Sum       string            `json:"sum"`
}

Summary mirrors the Summary proto message.