Notes on https://github.com/influxdata/telegraf/pull/4977/files

4977.txt

on the stackdriver side
=======================
https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.metricDescriptors
https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries


Init
====
this creates the stackdriver struct

i think it is setting defaults for

- rate limit
- lookback seconds
- delay seconds
- scrape distribution buckets
- distribution aggregation aligners

I think that what you put in the cond would override these defaults, but i'm not sure how

I think any setting in the conf that isn't here doesn't have a default

Gather
=======
I believe this is run once every interval

it calls
- initializeStackdriverClient
- updateWindow
- generatetimeSeriesConfs

then it initializes a ratelimiter and a waitgroup

for each of the time series confs it
  creates a goroutine
  calls scrapeTimeSeries on the time series conf
  and adds it to a waitgroup

finally it waits on the waitgroup

initializeStackdriverClient
============================
this just creates and returns a stackdriver monitoring client

updateWindow
============
this changes the stackdriver struct directly

when window end is zero, i think that means the program just started
in that case we set the window start to be now - delaySeconds - lookbackSeconds
otherwise we set the start window to be the previous end window

we always set the new end window to be now - delaySeconds

generatetimeSeriesConfs
=======================
if a cache exists and it is valid
(meaning it has some timeseries in it and its younger than its ttl)
generate a new interval based on the start and stop windows
for each cached time series conf, update the interval
return all the time series confs

otherwise call newListMetricDescriptorsFilters to to a list of filters
if its empty add one "catchall" item to it that should match everything

for each filter
  call the stackdriver listmetricdescriptors api
  for each metric returned
    if the filter was the catchall filter, call includeMetricType and skip if it is false
    if the metric is a distribution, either call newTimeSeriesConf once if scraping buckets or once for each configured aggregation aligner. run either initforDistribution or initForAggregate
    if it wasn't, just call  newTimeSeriesConf once

create a cache with all of the timeseriescofs we just created. store the current time and the ttl

newListMetricDescriptorsFilters
================================
this returns each item includeMetricTypePrefixes proeprly formatted as a filter for the stackdriver metric descriptors api

includeMetricType
=================
via includeExcludeHelper compares the metric name against includeMetricTypePrefixes and excludeMetricTypePrefixes
returns whether to include or not

initfordistribution
===================
tweak the metric name, not sure exactly why this is needed

initforaggregate
================
sets the aggregation aligner we'll use when calling stackdriver api and tweaks the metric name to include it

newTimeSeriesConf
=================
calls newListimeSeriesFilter to generate the filter expression
set the interval based on the window start and end
builds and returns the proper structs needed to make a request to the stackdriver list timeseries api

newListimeSeriesFilter
======================
this takes the metric name plus any user-supplied resource and metric label filters and generates a filter expression for the stackdriver list time series api
it uses includeExcludeHelper
In the unmodified PR, this has a bug that generates an invalid filter for the metric if the user hasn't configured any additional filters
this results in an error about listing timeseries returning too many results and no data


scrapeTimeSeries
=================
take a timeseriesconf and makes a request to stackdrivers listtimeseries api

for each time series in the response
  build up a list of tags to output, filtering  using includTags
  for each data point in the series
    get the timestamp
    build up a map of fields to output, calling scrapeDistribution if its a distribution. i think if we configured an aggregation aligner we don't get back a distribution.
  call the telegraf accumulator's  AddFields function to output the data

includtag
=========
via includeExcludeHelper compares the tag against includeTagPrefixes and excludeTagPrefixes
returns whether to include or not

scrapeDistribution
==================
haevn't dug in, appears to return multiple specially named fields each with a count of the number of items in that bucket