Skip to content

Commit

Permalink
Status API: use jsonpb for json marshalling of prometheus metrics (#4324
Browse files Browse the repository at this point in the history 
)

* Wrap the prometheus portion of our metrics in such a way that they use jsonpb for
   encoding to JSON, as prescribed by the protobuf library.

   Note: We're using jsonpb, not protojson, because there is no protobuf V2 version of
   github.com/prometheus/client_golang

* build(deps): bump github.com/prometheus/client_golang (#4307)

 This reverts commit 2f298db.

* CHANGELOG.md: add note re: JSON encoding of Status API payloads

Signed-off-by: Stephan Renatus <stephan.renatus@gmail.com>
  • Loading branch information
@srenatus
srenatus committed Feb 22, 2022
1 parent 1dfa6bd commit 9afdad7
Show file tree
Hide file tree
Showing 13 changed files with 486 additions and 92 deletions.
105 changes: 105 additions & 0 deletions CHANGELOG.md
View file
Expand Up @@ -5,6 +5,111 @@ project adheres to [Semantic Versioning](http://semver.org/).

## Unreleased

### Backwards incompatible changes

The JSON representation of the Status API's payloads -- both for `GET /v1/status`
responses and the metrics sent to a remote Status API endpoint -- have changed:

Previously, they had been serialized into JSON using the standard library "encoding/json"
methods. However, the metrics coming from the Prometheus integration are only available
in Golang structs generated from Protobuf definitions. For serializing these into JSON,
the standard library functions are unsuited:

- enums would be converted into numbers,
- field names would be `snake_case`, not `camelCase`,
- and NaNs would cause the encoder to panic.

Now, we're using the protobuf ecosystem's `jsonpb` package, to serialize the Prometheus
metrics into JSON in a way that is compliant with the Protobuf specification.

Concretely, what would before be
```
"metrics": {
"prometheus": {
"go_gc_duration_seconds": {
"help": "A summary of the GC invocation durations.",
"metric": [
{
"summary": {
"quantile": [
{
"quantile": 0,
"value": 0.000011799
},
{
"quantile": 0.25,
"value": 0.000011905
},
{
"quantile": 0.5,
"value": 0.000040002
},
{
"quantile": 0.75,
"value": 0.000065238
},
{
"quantile": 1,
"value": 0.000104897
}
],
"sample_count": 7,
"sample_sum": 0.000309117
}
}
],
"name": "go_gc_duration_seconds",
"type": 2
},
```

is *now*:
```
"metrics": {
"prometheus": {
"go_gc_duration_seconds": {
"name": "go_gc_duration_seconds",
"help": "A summary of the pause duration of garbage collection cycles.",
"type": "SUMMARY",
"metric": [
{
"summary": {
"sampleCount": "1",
"sampleSum": 4.1765e-05,
"quantile": [
{
"quantile": 0,
"value": 4.1765e-05
},
{
"quantile": 0.25,
"value": 4.1765e-05
},
{
"quantile": 0.5,
"value": 4.1765e-05
},
{
"quantile": 0.75,
"value": 4.1765e-05
},
{
"quantile": 1,
"value": 4.1765e-05
}
]
}
}
]
},
```

Note that `sample_count` is now `sampleCount`, and the `type` is using the enum's
string representation, `"SUMMARY"`, not `2`.

Note: For compatibility reasons (the Prometheus golang client doesn't use the V2
protobuf API), this change uses `jsonpb` and not `protojson`.

## 0.37.2

This is a bugfix release addressing two bugs:
Expand Down
146 changes: 89 additions & 57 deletions docs/content/management-status.md
View file
Expand Up @@ -70,114 +70,146 @@ on the agent, updates will be sent to `/status`.
},
"metrics": {
"prometheus": {
"go_gc_cycles_automatic_gc_cycles_total": {
"name": "go_gc_cycles_automatic_gc_cycles_total",
"help": "Count of completed GC cycles generated by the Go runtime.",
"type": "COUNTER",
"metric": [
{
"counter": {
"value": 1
}
}
]
},
"go_gc_cycles_forced_gc_cycles_total": {
"name": "go_gc_cycles_forced_gc_cycles_total",
"help": "Count of completed GC cycles forced by the application.",
"type": "COUNTER",
"metric": [
{
"counter": {
"value": 0
}
}
]
},
"go_gc_cycles_total_gc_cycles_total": {
"name": "go_gc_cycles_total_gc_cycles_total",
"help": "Count of all completed GC cycles.",
"type": "COUNTER",
"metric": [
{
"counter": {
"value": 1
}
}
]
},
"go_gc_duration_seconds": {
"help": "A summary of the GC invocation durations.",
"name": "go_gc_duration_seconds",
"help": "A summary of the pause duration of garbage collection cycles.",
"type": "SUMMARY",
"metric": [
{
"summary": {
"sampleCount": "1",
"sampleSum": 4.1765e-05,
"quantile": [
{
"quantile": 0,
"value": 0.000011799
"value": 4.1765e-05
},
{
"quantile": 0.25,
"value": 0.000011905
"value": 4.1765e-05
},
{
"quantile": 0.5,
"value": 0.000040002
"value": 4.1765e-05
},
{
"quantile": 0.75,
"value": 0.000065238
"value": 4.1765e-05
},
{
"quantile": 1,
"value": 0.000104897
"value": 4.1765e-05
}
],
"sample_count": 7,
"sample_sum": 0.000309117
]
}
}
],
"name": "go_gc_duration_seconds",
"type": 2
]
},
------------------------------8< SNIP 8<------------------------------
"http_request_duration_seconds": {
"name": "http_request_duration_seconds",
"help": "A histogram of duration for requests.",
"type": "HISTOGRAM",
"metric": [
{
"label": [
{
"name": "code",
"value": "200"
},
{
"name": "handler",
"value": "v1/data"
},
{
"name": "method",
"value": "get"
}
],
"histogram": {
"sampleCount": "2",
"sampleSum": 0.00060022,
"bucket": [
{
"cumulative_count": 1,
"upper_bound": 0.005
},
{
"cumulative_count": 1,
"upper_bound": 0.01
"cumulativeCount": "0",
"upperBound": 1e-06
},
{
"cumulative_count": 1,
"upper_bound": 0.025
"cumulativeCount": "0",
"upperBound": 5e-06
},
{
"cumulative_count": 1,
"upper_bound": 0.05
"cumulativeCount": "0",
"upperBound": 1e-05
},
{
"cumulative_count": 1,
"upper_bound": 0.1
"cumulativeCount": "0",
"upperBound": 5e-05
},
{
"cumulative_count": 1,
"upper_bound": 0.25
"cumulativeCount": "0",
"upperBound": 0.0001
},
{
"cumulative_count": 1,
"upper_bound": 0.5
"cumulativeCount": "2",
"upperBound": 0.0005
},
{
"cumulative_count": 1,
"upper_bound": 1
"cumulativeCount": "2",
"upperBound": 0.001
},
{
"cumulative_count": 1,
"upper_bound": 2.5
"cumulativeCount": "2",
"upperBound": 0.01
},
{
"cumulative_count": 1,
"upper_bound": 5
"cumulativeCount": "2",
"upperBound": 0.1
},
{
"cumulative_count": 1,
"upper_bound": 10
"cumulativeCount": "2",
"upperBound": 1
}
],
"sample_count": 1,
"sample_sum": 0.003157399
},
"label": [
{
"name": "code",
"value": "200"
},
{
"name": "handler",
"value": "v1/data"
},
{
"name": "method",
"value": "get"
}
]
]
}
}
],
"name": "http_request_duration_seconds",
"type": 4
]
}
}
}
Expand Down
2 changes: 1 addition & 1 deletion docs/content/monitoring.md
View file
Expand Up @@ -77,7 +77,7 @@ The Prometheus endpoint exports Go runtime metrics as well as HTTP request laten

### Status Metrics

When Prometheus is enabled in the status plugin (see [Configuration](../configuration/#status), the OPA instance's Prometheus endpoint also exposes these metrics:
When Prometheus is enabled in the status plugin (see [Configuration](../configuration/#status)), the OPA instance's Prometheus endpoint also exposes these metrics:

| Metric name | Metric type | Description | Status |
| --- | --- |----------------------------------------------------------|--------|
Expand Down
3 changes: 2 additions & 1 deletion go.mod
View file
Expand Up @@ -15,6 +15,7 @@ require (
github.com/go-logr/logr v1.2.2
github.com/gobwas/glob v0.2.3
github.com/golang/glog v1.0.0 // indirect
github.com/golang/protobuf v1.5.2
github.com/golang/snappy v0.0.4 // indirect
github.com/gorilla/mux v1.8.0
github.com/klauspost/compress v1.13.5 // indirect
Expand All @@ -24,7 +25,7 @@ require (
github.com/olekukonko/tablewriter v0.0.5
github.com/peterh/liner v0.0.0-20170211195444-bf27d3ba8e1d
github.com/pkg/errors v0.9.1
github.com/prometheus/client_golang v1.12.0
github.com/prometheus/client_golang v1.12.1
github.com/rcrowley/go-metrics v0.0.0-20200313005456-10cdbea86bc0
github.com/sirupsen/logrus v1.8.1
github.com/spf13/cobra v1.3.0
Expand Down
4 changes: 2 additions & 2 deletions go.sum
View file
Expand Up @@ -371,8 +371,8 @@ github.com/prometheus/client_golang v1.0.0/go.mod h1:db9x61etRT2tGnBNRi70OPL5Fsn
github.com/prometheus/client_golang v1.4.0/go.mod h1:e9GMxYsXl05ICDXkRhurwBS4Q3OK1iX/F2sw+iXX5zU=
github.com/prometheus/client_golang v1.7.1/go.mod h1:PY5Wy2awLA44sXw4AOSfFBetzPP4j5+D6mVACh+pe2M=
github.com/prometheus/client_golang v1.11.0/go.mod h1:Z6t4BnS23TR94PD6BsDNk8yVqroYurpAkEiz0P2BEV0=
github.com/prometheus/client_golang v1.12.0 h1:C+UIj/QWtmqY13Arb8kwMt5j34/0Z2iKamrJ+ryC0Gg=
github.com/prometheus/client_golang v1.12.0/go.mod h1:3Z9XVyYiZYEO+YQWt3RD2R3jrbd179Rt297l4aS6nDY=
github.com/prometheus/client_golang v1.12.1 h1:ZiaPsmm9uiBeaSMRznKsCDNtPCS0T3JVDGF+06gjBzk=
github.com/prometheus/client_golang v1.12.1/go.mod h1:3Z9XVyYiZYEO+YQWt3RD2R3jrbd179Rt297l4aS6nDY=
github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo=
github.com/prometheus/client_model v0.0.0-20190129233127-fd36f4220a90/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
Expand Down

0 comments on commit 9afdad7

Please sign in to comment.