Merge branch 'code-cleanup' into 'master'

Adds comments to tricky parts of the code

See merge request cloudnative/oci-grafana-plugin!18

Author: Faiq Raza

src/datasource.js

@@ -51,6 +51,7 @@ export default class OCIDatasource {
 
     var targets = _.map(options.targets, target => {
       let region = target.region
+      // check to see if we have tags (dimensions) in the query and turn those into a string for MQL
       let t = []
       if (target.hasOwnProperty('tags')) {
         for (let i = 0; i < target.tags.length; i++) {
@@ -64,6 +65,7 @@ export default class OCIDatasource {
       if (target.region === 'select region') {
         region = this.defaultRegion
       }
+      // If there's nothing there return a blank string otherwise return the dimensions encapsuled by these {}
       let dimension = (t.length === 0) ? '' : `{${t}}`
 
       return {
@@ -78,6 +80,7 @@ export default class OCIDatasource {
         hide: target.hide,
         type: target.type || 'timeserie',
         datasourceId: this.id,
+        // pass the MQL string we built here
         query: `${this.templateSrv.replace(target.metric, options.scopedVars || {})}[${target.window}]${dimension}.${target.aggregation}`
       }
     })
@@ -107,15 +110,16 @@ export default class OCIDatasource {
     })
   }
 
+  // helps match the regex's from creating template variables in grafana
   templateMeticSearch (varString) {
     let compartmentQuery = varString.match(/^compartments\(\)/)
     if (compartmentQuery) {
-      return this.getCompartments()
+      return this.getCompartments().catch(err => { throw new Error('Unable to make request ' + err) })
     }
 
     let regionQuery = varString.match(/^regions\(\)/)
     if (regionQuery) {
-      return this.getRegions()
+      return this.getRegions().catch(err => { throw new Error('Unable to make request ' + err) })
     }
 
     let metricQuery = varString.match(/metrics\((\$?\w+)(,\s*\$\w+)*\)/)
@@ -124,7 +128,7 @@ export default class OCIDatasource {
         namespace: this.templateSrv.replace(metricQuery[1]),
         compartment: this.templateSrv.replace(metricQuery[2]).replace(',', '').trim()
       }
-      return this.metricFindQuery(target)
+      return this.metricFindQuery(target).catch(err => { throw new Error('Unable to make request ' + err) })
     }
 
     let namespaceQuery = varString.match(/namespaces\(\)/)
@@ -137,6 +141,10 @@ export default class OCIDatasource {
     throw new Error('Unable to parse templating string')
   }
 
+  // this function does 2 things - its the entrypoint for finding the metrics from the query editor
+  // and is the entrypoint for templating according to grafana -- since this wasn't docuemnted
+  // in grafana I was lead to believe that it did the former
+  // TODO: break the metric finding for the query editor out into a different function
   metricFindQuery (target) {
     if (typeof (target) === 'string') {
       return this.templateMeticSearch(target)
@@ -273,6 +281,7 @@ export default class OCIDatasource {
     return this.q.when(aggregations)
   }
 
+  // retries all request to the backend grafana 10 times before failure
   doRequest (options) {
     let _this = this
     return retryOrThrow(() => {

src/query_ctrl.js

@@ -28,6 +28,7 @@ export class OCIDatasourceQueryCtrl extends QueryCtrl {
       value: '-- remove tag filter --'
     })
 
+    // rebuilds the tagSegments which are stored as tags when reloading the query editor
     for (let i = 0; i < this.target.tags.length; i++) {
       if (i > 0) {
         this.tagSegments.push(this.uiSegmentSrv.newCondition(','))
@@ -116,6 +117,7 @@ export class OCIDatasourceQueryCtrl extends QueryCtrl {
     return []
   }
 
+  // entrypoint in fetching the dimensions and their values for a particular metric
   getTagsOrValues (segment, index) {
     if (segment.type === 'operator') {
       return this.q.when([])
@@ -129,12 +131,15 @@ export class OCIDatasourceQueryCtrl extends QueryCtrl {
     const key = this.tagSegments[index - 2]
     const options = this.dimCache[key.value]
     const that = this
+    // return all the values for the key
     const optSegments = options.map(v => that.uiSegmentSrv.newSegment({
       value: v
     }))
     return this.q.when(optSegments)
   }
 
+  // we fetch dimensions for a metric in pairs link this key=value
+  // we save them in an object that looks like {key [list, of, values]}
   mapToSegment (dimensions) {
     const dimCache = {}
     const dims = dimensions.map((v) => {
@@ -154,6 +159,7 @@ export class OCIDatasourceQueryCtrl extends QueryCtrl {
     return dims
   }
 
+  // deals with adding or updating new values
   tagSegmentUpdated (segment, index) {
     this.tagSegments[index] = segment
 
@@ -164,16 +170,19 @@ export class OCIDatasourceQueryCtrl extends QueryCtrl {
         this.tagSegments.push(this.uiSegmentSrv.newPlusButton())
       } else if (this.tagSegments.length > 2) {
         this.tagSegments.splice(Math.max(index - 1, 0), 1)
+        // if the thing we removed was the only key value pair add + button so they can put in new metrics
         if (this.tagSegments[this.tagSegments.length - 1].type !== 'plus-button') {
           this.tagSegments.push(this.uiSegmentSrv.newPlusButton())
         }
       }
     } else {
+      // handle adding in the first dimension pair
       if (segment.type === 'plus-button') {
         if (index > 2) {
           this.tagSegments.splice(index, 0, this.uiSegmentSrv.newCondition(','))
         }
         this.tagSegments.push(this.uiSegmentSrv.newOperator('='))
+        // always push in the fake for the first value in case network request breaks
         this.tagSegments.push(this.uiSegmentSrv.newFake('select tag value', 'value', 'query-segment-value'))
         segment.type = 'key'
         segment.cssClass = 'query-segment-key'
@@ -187,6 +196,7 @@ export class OCIDatasourceQueryCtrl extends QueryCtrl {
     this.rebuildTargetTagConditions()
   }
 
+  // take the tagSegments and turn them into tags for the query that gets sent
   rebuildTargetTagConditions () {
     const tags = []
     let tagIndex = 0