|
2 | 2 | [](https://goreportcard.com/report/github.com/bitly/tsplot) |
3 | 3 | [](https://pkg.go.dev/github.com/bitly/tsplot) |
4 | 4 |
|
5 | | -This package provides a method of querying for raw time series data from the GCM APIs and additionally plotting that data for use in other applications. |
6 | | - |
7 | | -This came to be due to what we consider a small limitation in the Google APIs which require us to re-draw graphs to include them in other applications such as |
8 | | -Slack bots. There is no facility in the Google API that provides a PNG of already graphed data. |
9 | | - |
10 | 5 | ## Authentication |
11 | 6 | This package makes no effort to assist in authentication to the Google APIs. |
12 | 7 | Instead, it will expect the caller to supply an authenticated client. |
13 | 8 |
|
14 | 9 | More information on authentication can be found in the official [Google Cloud documentation](https://cloud.google.com/docs/authentication). |
15 | | - |
16 | | -## Query |
17 | | -tsplot helps to facilitate easy querying of the Google Cloud Monitoring API for time series matching the supplied criteria. |
18 | | -In addition it provides methods of overriding certain aspects of the query. |
19 | | - |
20 | | -For example, the following code snippet will return a single time series for the following metric descriptor: `custom.googleapis.com/opencensus/fishnet/queuereader_fishnet/messages_total`. |
21 | 10 | ``` |
22 | 11 | func main() { |
23 | 12 |
|
24 | | - ... snip ... |
| 13 | +... snip ... |
25 | 14 |
|
26 | 15 | start := time.Now().Add(-1 * time.Hour) |
27 | 16 | end := time.Now() |
28 | | - mq := &tsplot.NewMetricQuery( |
29 | | - "bitly-gcp-prod", // GCP project |
30 | | - "custom.googleapis.com/opencensus/fishent/queuereader_fishnet/messages_total", // metric descriptor |
31 | | - &start, // start of time window |
32 | | - &end, // end of time window |
33 | | - ) |
34 | | -
|
35 | | - // disable cross series reducer (MEAN reduction is default) |
36 | | - query.Set_REDUCE_NONE() |
37 | | -
|
38 | | - // set different alignment window. (Default is 1 minute) |
39 | | - query.SetAlignmentPeriod(time.Minute * 2) |
40 | | -
|
41 | | - tsi, err := mq.PerformWithClient(client) // client is provided by user |
42 | | - if err != nil { |
43 | | - fmt.Printf("error performing query: %v\n", err) |
44 | | - } |
45 | | -} |
46 | | -``` |
47 | | - |
48 | | -## Plotting |
49 | | -To plot the data, tsplot leverages the open source package [gonum/plot](github.com/gonum/plot) to create a graph and plot the data for a given time series. |
50 | | - |
51 | | -The example below creates a new graph containing a singular time series, plots it, and saves the resulting plot to disk. |
52 | | -``` |
53 | | -func main() { |
54 | | -
|
55 | | - ... snip ... |
56 | | -
|
57 | | - ts := tsplot.TimeSeries{} |
58 | | -
|
59 | | - // optionally iterate over returned time series |
60 | | - timeSeries, _ := tsi.Next() |
61 | | - ts[metric] = ts.GetPoints() |
62 | | -
|
63 | | - // create the plot with some formatting options |
64 | | - p, err := ts.Plot([]tsplot.PlotOption{ |
65 | | - tsplot.WithXAxisName("UTC"), |
66 | | - tsplot.WIthGrid(colornames.Darkgrey), |
67 | | - tsplot.WithTitle(metric)}...) |
68 | 17 | |
69 | | - if err != nil { |
70 | | - return err |
| 18 | + // create new request |
| 19 | + request := monitoringpb.ListTimeSeriesRequest{ |
| 20 | + Name: fmt.Sprintf("projects/%s", project), |
| 21 | + Filter: query, |
| 22 | + Interval: &monitoringpb.TimeInterval{ |
| 23 | + EndTime: timestamppb.New(et), |
| 24 | + StartTime: timestamppb.New(st), |
| 25 | + }, |
| 26 | + Aggregation: nil, |
| 27 | + SecondaryAggregation: nil, |
| 28 | + View: monitoringpb.ListTimeSeriesRequest_FULL, |
71 | 29 | } |
72 | | -
|
73 | | - // optionally save the plot to disk |
74 | | - p.Save(8*vg.Inch, 4*vg.Inch, "./my-graph.png") |
| 30 | + |
| 31 | + // execute the request and get the response from Google APIs |
| 32 | + tsi := GoogleCloudMonitoringClient.ListTimeSeries(context.Background(), request) |
| 33 | + |
| 34 | + // Create the plot from the GAPI TimeSeries |
| 35 | + plot, _ := tsplot.NewPlotFromTimeSeriesIterator(tsi, "", nil) |
| 36 | + |
| 37 | + // Save the new plot to disk. |
| 38 | + plot.Save(8*vg.Inch, 4*vg.Inch, "my_plot.png") |
75 | 39 | } |
76 | 40 | ``` |
77 | 41 |
|
78 | 42 | ### Example generated graphs: |
79 | 43 | Query across multiple time series with mean reducer: |
80 | 44 |  |
81 | 45 |
|
82 | | -### Graph Color Scheme |
83 | | -I'm not a UX designer, but I have selected colors that I find higher contrast |
84 | | -and easier to see. I am basing this completely off my colorblindness which is |
85 | | -unique to me. Improvements to the color palette used are welcome. |
0 commit comments