vnfs/DAaaS/lib/promql_api/README.md

   1 ## What does this API do ?
   2
   3 This API has support for two PROMQL functions as of now :
   4
   5 1. 'query'
   6 2. 'query_range'
   7
   8 You can directly call the above functions with required parameters, and API shall
   9 give out a result set.
  10
  11 ## How to use this API ?
  12
  13 ### Using 'query'
  14
  15 ```
  16 1. Copy the directory 'promql_api' to your working directory.
  17 ```
  18
  19 ```
  20 2. Import the API function: query
  21 from promql_api.prom_ql_api import query
  22 ```
  23
  24 ```
  25 3. have a global or local variable as 'QUERY_STRING'
  26 QUERY_STRING = ['irate(collectd_cpufreq{exported_instance="otconap7",cpufreq="1"}[2m])']
  27 ```
  28
  29 ```
  30 4. Store the result set in a list:
  31 list_of_result_sets = query(QUERY_STRING)
  32 ```
  33
  34 ```
  35 The return is :
  36
  37 [{'metric': {'cpufreq': '1',
  38              'endpoint': 'collectd-prometheus',
  39              'exported_instance': 'otconap7',
  40              'instance': 'ZZ.QQQ.XXX.YY:9103',
  41              'job': 'collectd',
  42              'namespace': 'edge1',
  43              'pod': 'plundering-liger-collectd-wz7xg',
  44              'service': 'collectd'},
  45   'value': [1559177169.415, '119727200']}]
  46 ```
  47 ### Using 'query_range'
  48
  49 ```
  50 1. Copy the directory 'promql_api' to your working directory.
  51 ```
  52
  53 ```
  54 2. Import the API function: query_range
  55 from promql_api.prom_ql_api import query_range
  56 ```
  57
  58 ```
  59 3. Its the calling application's responsibility to pass on the correct set of paramters. Form a map of required parameters:
  60
  61 map_of_parameters = {'query': 'up', 'start': '2019-06-19T20:10:30.781Z', 'end': '2019-06-19T20:10:45.781Z', 'step': '15s'}
  62 ```
  63
  64 ```
  65 4. Store the result set in a list:
  66 list_of_result_sets = query_range(map_of_parameters)
  67 ```
  68
  69 ```
  70 The return is:
  71
  72 [[{'metric': {'__name__': 'up',
  73               'endpoint': 'cadvisor-prometheus',
  74               'instance': 'ZZ.QQQ.XXX.YY:8080',
  75               'job': 'cadvisor',
  76               'namespace': 'default',
  77               'pod': 'cp-cadvisor-69287',
  78               'service': 'cadvisor'},
  79    'values': [[1560975030.781, '1'], [1560975045.781, '1']]},
  80   {'metric': {'__name__': 'up',
  81               'endpoint': 'collectd-prometheus',
  82               'instance': 'ZZ.QQQ.XXX.YY:9103',
  83               'job': 'collectd',
  84               'namespace': 'default',
  85               'pod': 'vcmts-stats-daemonset-lsqjk',
  86               'service': 'collectd'},
  87    'values': [[1560975030.781, '1'], [1560975045.781, '1']]},
  88   {'metric': {'__name__': 'up',
  89               'endpoint': 'metrics',
  90               'instance': 'ZZ.QQQ.XXX.YY:9100',
  91               'job': 'cp-prometheus-node-exporter',
  92               'namespace': 'default',
  93               'pod': 'cp-prometheus-node-exporter-sbbb9',
  94               'service': 'cp-prometheus-node-exporter'},
  95    'values': [[1560975030.781, '1'], [1560975045.781, '1']]},
  96   {'metric': {'__name__': 'up',
  97               'endpoint': 'metrics',
  98               'instance': 'ZZ.QQQ.XXX.YY:9100',
  99               'job': 'cp-prometheus-node-exporter',
 100               'namespace': 'default',
 101               'pod': 'cp-prometheus-node-exporter-mcqtp',
 102               'service': 'cp-prometheus-node-exporter'},
 103    'values': [[1560975030.781, '1'], [1560975045.781, '1']]}]]
 104 ```
 105
 106 ## Troubleshooting tips
 107
 108 * Check the sample file - sample_promql_query.py in the repo ( sample-apps/m3db_promql)
 109 * Make sure the file "__init__.py" is present in promql_api directory after you copy the directory.
 110 * Make sure environment variables like "DATA_ENDPOINT" are correctly set.
 111 * For custom and advanced querying https://prometheus.io/docs/prometheus/latest/querying/api/
 112 * Logs are generated in the directory where the query function is called.
 113 * sample log file - promql_api.log
 114
 115 ```
 116  05-30-2019 08:47:53PM ::prom_ql_api.py :: set_log_config :: INFO :: Set the log configs.
 117  05-30-2019 08:47:53PM ::prom_ql_api.py :: load_and_validate_env_vars :: INFO :: Loading the env variables ...
 118  05-30-2019 08:47:53PM ::prom_ql_api.py :: load_and_validate_env_vars :: ERROR :: Env var: DATA_ENDPOINT not         found !
 119  05-30-2019 08:47:53PM ::prom_ql_api.py :: query :: INFO :: Forming the get request ...
 120  05-30-2019 08:47:53PM ::prom_ql_api.py :: query :: INFO :: API request::: URL: http://ZZ.QQQ.XXX.YY:30090/api/v1/    query
 121  05-30-2019 08:47:53PM ::prom_ql_api.py :: query :: INFO :: API request::: params: {'query':                         'irate(collectd_cpufreq{exported_instance="otconap7",cpufreq="1"}[2m])'}
 122  05-30-2019 08:47:53PM ::connectionpool.py :: _new_conn :: DEBUG :: Starting new HTTP connection (1): ZZ.QQQ.XXX.YY   05-30-2019 08:47:53PM ::connectionpool.py :: _make_request :: DEBUG :: http://ZZ.QQQ.XXX.YY:30090 "GET /api/v1/      query?query=irate%28collectd_cpufreq%7Bexported_instance%3D%22otconap7%22%2Ccpufreq%3D%221%22%7D%5B2m%5D%29 HTTP/1. 1" 200 370
 123  05-30-2019 08:47:53PM ::prom_ql_api.py :: query :: INFO :: ::::::::::RESULTS:::::::::::::                           irate(collectd_cpufreq{exported_instance="otconap7",cpufreq="1"}[2m])
 124  05-30-2019 08:47:53PM ::prom_ql_api.py :: query :: INFO :: {'metric': {'cpufreq': '1', 'endpoint': 'collectd-       prometheus', 'exported_instance': 'otconap7', 'instance': 'ZZ.QQQ.XXX.YY:9103', 'job': 'collectd', 'namespace':      'edge1', 'pod': 'plundering-liger-collectd-wz7xg', 'service': 'collectd'}, 'value': [1559249299.084, '236300']}
 125  ```
 126
 127  * Tested Error scenario: Configure QUERY_STRING as :
 128  ```
 129  QUERY_STRING = ['irate(collectd_cpufreq{exported_instance="otconap7", cpufreq="1"}[2m])', 'collectd_cpu_percent{job="collectd" exported_instance="an11-31"}[1m]']
 130  ```
 131  O/P :
 132  ```
 133  Check logs..HTTP error occurred: 400 Client Error: Bad Request for url: http://ZZ.QQQ.XXX.YY:30090/api/v1/query?query=collectd_cpu_percent%7Bjob%3D%22collectd%22+exported_instance%3D%22an11-31%22%7D%5B1m%5D
 134 [{'metric': {'cpufreq': '1',
 135              'endpoint': 'collectd-prometheus',
 136              'exported_instance': 'otconap7',
 137              'instance': 'ZZ.QQQ.XXX.YY:9103',
 138              'job': 'collectd',
 139              'namespace': 'edge1',
 140              'pod': 'plundering-liger-collectd-wz7xg',
 141              'service': 'collectd'},
 142   'value': [1559343866.631, '119798600']}]
 143 {'error': 'parse error at char 37: missing comma before next identifier '
 144           '"exported_instance"',
 145  'errorType': 'bad_data'}
 146 ```