/*
 *-------------------------------------------------------------------
 * 
 * README - helpfile for handling custom metrics
 *
 *-------------------------------------------------------------------
 *
 * Copyright (c) 2020 by cisco Systems, Inc.
 * All rights reserved.
 *
 *-------------------------------------------------------------------
 */

The purpose of this file is to outline the workflow to integrate custom 
metrics into Cisco Healthcheck framework.

Workflow

1. Startup

When healthcheck rpm is installed, a directory named custom_metrics is
created on harddisk:, and two files custom_metric_sample and 
README (this file) are placed under the directory. Let's call the 
directory HOME directory in the rest of the document.


2. Custom Metrics Data Collecting Program Creation

In order to integrate a custom metric, first need to create a data
collecting program under HOME directory for the custom metric. 

The program can be anything (python, bash, C or whatever) as long as 
it's an executable and its name is the same as the custom metric to be
integrated. For instance, if we want to integrate a custom metric
named custom_metric_foo, the name of the program must be 
custom_metric_foo too.

The program will run to completion once launched, and will generate a
data file in json format under HOME directory. The name of the data 
file is the same as the custome metric with a suffix .json. So in the 
above example, the name of the data file is custom_metric_foo.json.

The contents of the data file must be compliant with the format below.
  {
      "custom_metric": {
          "name": "custom_metric_1"
          "health_msg": "Health description", 
          "health_state": "Normal", 
          "last_update": "25/06/20 07:01 03 PM", 
          "metric_info": {
              "paramBar": "Information bar", 
              "paramFoo": "Information foo"
          }, 
      }
  }

Where, all keys in the dictionary "custom_metric" are mandatory, and their 
values can't be empty. Among which, "metric_info" is an json object, 
that any proprietary information related to the custom metric can be
stored.

Refer to custom_metric_sample for how to generate the data file in 
Python. Also, simpily execute the script will generate an example data file.
 

3. Custom Metric Registration

To register a custom metric, use the following config CLI or Yang request.
  ios(config)#healthcheck metric custom-metric-list custom_metric_foo

  <edit-config>
    <target><candidate/></target>
    <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
      <health-check xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-healthcheck-cfg">
        <ord-b>
          <metric>
            <custom-metrics>
              <custom-metric>custom_metric_foo</custom-metric>
            </custom-metrics>
          </metric>
        <ord-b>
      </health-check>
    </config>
  </edit-config>

The maximum number of custom metrics allowed to be registered is 5.

To unregister the custom metrics, use no notion of the CLI or delete
action in the Yang request.


4. Custom Metrics Data Collection

By enabling healthcheck, registered custom metric programs will be 
executed periodically (configurable) and data files will be generated.
For each iteration, the newly generated data files will overwrite the 
old ones and no backup will be kept.

After data files are generated, Cisco Healthcheck Manager will process 
the data and make them queryable through show CLI and Yang request.

If any error is encountered while executing the program or processing 
the data file for a particular custom metric, the service state of the 
custom metric will be set to ERROR, and no data is avaialbe until next
iteration. In case of error, proper syslog messages are generated.

To stop data collection, just disable healthcheck.

Custom metric can be monitored together with other Cisco predefined
metrics, or just by itself (disable all Cisco predefined metrics).


5. Query Custom Metrics

To query custom metrics operational data, use following show CLI or Yang 
request.
  ios#show healthcheck metric custom-metric all info
  ios#show healthcheck metric custom-metric custom_metric_foo info

  <health-check xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-healthcheck-oper">
    <metric-info>
      <custom-metric/>
    </metric-info>
  </health-check>

  <health-check xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-healthcheck-oper">
    <metric-info>
      <custom-metric>
        <custom-metric-infos>
          <custom-metric-info>
            <metric-name>custom_metric_foo</metric-name>
          </custom-metric-info>
        </custom-metric-infos>
      </custom-metric>
    </metric-info>
  </health-check>
