1# gin-metrics
2gin-gonic/gin metrics exporter for Prometheus.
3
4[中文](README_zh.md)
5
6- [Introduction](#Introduction)
7- [Grafana](#Grafana)
8- [Installation](#Installation)
9- [Usage](#Usage)
10- [Custom Metric](#Custom-Metric)
11- [Metric with separate port](#Metric-with-separate-port)
12- [Contributing](#Contributing)
13
14## Introduction
15
16`gin-metrics` defines some metrics for gin http-server. There have easy way to use it.
17
18Below is the detailed description for every metric.
19
20| Metric | Type | Description |
21| ----------------------- | --------- | --------------------------------------------------- |
22| gin_request_total | Counter | all the server received request num. |
23| gin_request_uv | Counter | all the server received ip num. |
24| gin_uri_request_total | Counter | all the server received request num with every uri. |
25| gin_request_body_total | Counter | the server received request body size, unit byte. |
26| gin_response_body_total | Counter | the server send response body size, unit byte. |
27| gin_request_duration | Histogram | the time server took to handle the request. |
28| gin_slow_request_total | Counter | the server handled slow requests counter, t=%d. |
29
30
31## Grafana
32
33
34Set the `grafana` directory for details.
35
36
37
38
39## Installation
40
41```bash
42$ go get github.com/penglongli/gin-metrics
43```
44
45## Usage
46
47Your can see some metrics across `http://localhost:8080/metrics`
48
49```go
50package main
51
52import (
53 "github.com/gin-gonic/gin"
54
55 "github.com/penglongli/gin-metrics/ginmetrics"
56)
57
58func main() {
59 r := gin.Default()
60
61 // get global Monitor object
62 m := ginmetrics.GetMonitor()
63
64 // +optional set metric path, default /debug/metrics
65 m.SetMetricPath("/metrics")
66 // +optional set slow time, default 5s
67 m.SetSlowTime(10)
68 // +optional set request duration, default {0.1, 0.3, 1.2, 5, 10}
69 // used to p95, p99
70 m.SetDuration([]float64{0.1, 0.3, 1.2, 5, 10})
71
72 // set middleware for gin
73 m.Use(r)
74
75 r.GET("/product/:id", func(ctx *gin.Context) {
76 ctx.JSON(200, map[string]string{
77 "productId": ctx.Param("id"),
78 })
79 })
80
81 _ = r.Run()
82}
83```
84
85## Custom Metric
86
87`gin-metric` provides ways to custom your own metric.
88
89### Gauge
90
91With `Gauge` type metric, you can use three functions to change it's value.
92
93And you should define a `Gauge` Metric first,
94
95```go
96gaugeMetric := &ginmetrics.Metric{
97 Type: ginmetrics.Gauge,
98 Name: "example_gauge_metric",
99 Description: "an example of gauge type metric",
100 Labels: []string{"label1"},
101}
102
103// Add metric to global monitor object
104_ = ginmetrics.GetMonitor().AddMetric(gaugeMetric)
105```
106
107**SetGaugeValue**
108
109`SetGaugeValue` will setting metric value directly。
110
111```go
112_ = ginmetrics.GetMonitor().GetMetric("example_gauge_metric").SetGaugeValue([]string{"label_value1"}, 0.1)
113```
114
115**Inc**
116
117`Inc` will increase 1 to metric value
118
119```go
120_ = ginmetrics.GetMonitor().GetMetric("example_gauge_metric").Inc([]string{"label_value1"})
121```
122
123**Add**
124
125`Add` will add float64 num to metric value
126
127```go
128_ = ginmetrics.GetMonitor().GetMetric("example_gauge_metric").Add([]string{"label_value1"}, 0.2)
129```
130
131### Counter
132
133With `Counter` type metric, you can use `Inc` and `Add` function, don't use `SetGaugeValue`.
134
135
136### Histogram and Summary
137
138For `Histogram` and `Summary` type metric, should use `Observe` function.
139
140## Metric with separate port
141
142For some users, they don't want to merge the port of the metric with the port of the application.
143
144So we provide a way to separate the metric port. Here is the example.
145
146```go
147func main() {
148 appRouter := gin.Default()
149 metricRouter := gin.Default()
150
151 m := ginmetrics.GetMonitor()
152 // use metric middleware without expose metric path
153 m.UseWithoutExposingEndpoint(appRouter)
154 // set metric path expose to metric router
155 m.Expose(metricRouter)
156
157 appRouter.GET("/product/:id", func(ctx *gin.Context) {
158 ctx.JSON(200, map[string]string{
159 "productId": ctx.Param("id"),
160 })
161 })
162 go func() {
163 _ = metricRouter.Run(":8081")
164 }()
165 _ = appRouter.Run(":8080")
166}
167```
168
169## Contributing
170
171If someone has a problem or suggestions, you can submit [new issues](https://github.com/penglongli/gin-metrics/issues/new)
172or [new pull requests](https://github.com/penglongli/gin-metrics/pulls).
173
View as plain text