1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
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
$ curl http://my-prometheus-client.example.org:8080/metrics | prom2json
$ prom2json /tmp/metrics.prom
Running with TLS client authentication:
$ prom2json --cert=/path/to/certificate --key=/path/to/key http://my-prometheus-client.example.org:8080/metrics
Running without TLS validation (insecure, do not use in production!):
$ prom2json --accept-invalid-cert https://my-prometheus-client.example.org:8080/metrics
Advanced HTTP through `curl`:
$ curl -XPOST -H 'X-CSRFToken: 1234567890abcdef' --connect-timeout 60 'https://username:password@my-prometheus-client.example.org:8080/metrics' | prom2json
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](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing). 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.
```json
[
{
"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](https://registry.hub.docker.com/u/prom/prom2json/) Docker image.
For example:
```bash
docker pull prom/prom2json
docker run --rm -ti prom/prom2json http://my-prometheus-client.example.org:8080/metrics
```
|
