Skip to content

Commit

Permalink
feat: Template docs
Browse files Browse the repository at this point in the history 
* feat: Template docs
Fixes #493
Co-authored-by: Chris Grindstaff <[email protected]>
  • Loading branch information
@rahulguptajss
rahulguptajss authored Oct 18, 2021
1 parent 2181e32 commit 19b8f14
Show file tree
Hide file tree
Showing 4 changed files with 288 additions and 218 deletions.
2 changes: 2 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -277,6 +277,8 @@ For a list of collector-specific parameters, see the documentation of each colle

### [Unix](cmd/collectors/unix/README.md)

### [Templates](conf/README.md)

### Labels

Labels offer a way to add additional key-value pairs to a poller's metrics. These allow you to tag a cluster's metrics in a cross-cutting fashion. Here's an example:
Expand Down
100 changes: 1 addition & 99 deletions cmd/collectors/zapi/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,102 +65,4 @@ aggr-attributes:
- disk-count => disks
```

will force using `aggr_type` and `aggr_disks` for the label and the metric respectively.

## Creating/editing subtemplates

You can either read [ONTAP's documentation](https://mysupport.netapp.com/documentation/productlibrary/index.html?productID=60427) or use Harvest's `zapi` tool to explore available APIs and metrics on your cluster. Examples:

```sh
$ harvest zapi --poller <poller> show apis
# will print list of apis that are available
# usually apis with the "get-iter" suffix can provide useful metrics
$ harvest zapi --poller <poller> show attrs --api volume-get-iter
# will print the attribute tree of the API
$ harvest zapi --poller <poller> show data --api volume-get-iter
# will print raw data of the API attribute tree
```

(Replace `<poller>` with the name of a poller that can connect to an ONTAP system.)

Instead of editing one of the existing templates, it's better to copy one and edit the copy. That way, your custom template will not be overwritten when upgrading Harvest. For example, if you want to change `conf/zapi/cdot/9.8.0/aggr.yaml`, first create a copy (e.g., `conf/zapi/cdot/9.8.0/custom_aggr.yaml`), then add these lines to `conf/zapi/custom.yaml`:

```yaml
objects:
Aggregate: custom_aggr.yaml
```

After restarting your pollers, `aggr.yaml` will be ignored and the new, `custom_aggr.yaml` subtemplate will be used instead.

### Example subtemplate

In this example, we want to collect sensor metrics from the `environment-sensors-get-iter` API. These are the steps that we need to follow:

#### 1. Create a new subtemplate

Create the file `conf/zapi/cdot/9.8.0/sensor.yaml` (optionally replace `9.8.0` with the version of your ONTAP). Add following content:

```yaml
name: Sensor
query: environment-sensors-get-iter
object: sensor
counters:
environment-sensors-info:
- critical-high-threshold => critical_high
- critical-low-threshold => critical_low
- ^discrete-sensor-state => discrete_state
- ^discrete-sensor-value => discrete_value
- ^^node-name => node
- ^^sensor-name => sensor
- ^sensor-type => type
- ^threshold-sensor-state => threshold_state
- threshold-sensor-value => threshold_value
- ^value-units => unit
- ^warning-high-threshold => warning_high
- ^warning-low-threshold => warning_low
export_options:
include_all_labels: true
```

(See [#counters](#counters) for an explanation about the special symbols used).

#### 2. Enable the new subtemplate

To enable the new subtemplate, create `conf/zapi/custom.yaml` with the lines shown below.

```yaml
objects:
Sensor: sensor.yaml
```
In the future, if you add more subtemplates, you can add those in this same file.

#### 3. Test your changes and restart pollers

Test your new `Sensor` template with a single poller like this:
```
./bin/harvest start <poller> --foreground --verbose --collectors Zapi --objects Sensor
```
Replace `<poller>` with the name of one of your ONTAP pollers.

Once you have confirmed that the new template works, restart any already running pollers that you want to pick up the new template(s).

### Check the metrics

If you are using the Prometheus exporter, check the metrics on the HTTP endpoint with `curl` or a web browser. E.g., my poller is exporting its data on port `15001`. Adjust as needed for your exporter.

```
curl -s 'http://localhost:15001/metrics' | grep sensor_

sensor_value{datacenter="WDRF",cluster="shopfloor",critical_high="3664",node="shopfloor-02",sensor="P3.3V STBY",type="voltage",warning_low="3040",critical_low="2960",threshold_state="normal",unit="mV",warning_high="3568"} 3280
sensor_value{datacenter="WDRF",cluster="shopfloor",sensor="P1.2V STBY",type="voltage",threshold_state="normal",warning_high="1299",warning_low="1105",critical_low="1086",node="shopfloor-02",critical_high="1319",unit="mV"} 1193
sensor_value{datacenter="WDRF",cluster="shopfloor",unit="mV",critical_high="15810",critical_low="0",node="shopfloor-02",sensor="P12V STBY",type="voltage",threshold_state="normal"} 11842
sensor_value{datacenter="WDRF",cluster="shopfloor",sensor="P12V STBY Curr",type="current",threshold_state="normal",unit="mA",critical_high="3182",critical_low="0",node="shopfloor-02"} 748
sensor_value{datacenter="WDRF",cluster="shopfloor",critical_low="1470",node="shopfloor-02",sensor="Sysfan2 F2 Speed",type="fan",threshold_state="normal",unit="RPM",warning_low="1560"} 2820
sensor_value{datacenter="WDRF",cluster="shopfloor",sensor="PSU2 Fan1 Speed",type="fan",threshold_state="normal",unit="RPM",warning_low="4600",critical_low="4500",node="shopfloor-01"} 6900
sensor_value{datacenter="WDRF",cluster="shopfloor",sensor="PSU1 InPwr Monitor",type="unknown",threshold_state="normal",unit="mW",node="shopfloor-01"} 132000
sensor_value{datacenter="WDRF",cluster="shopfloor",critical_high="58",type="thermal",unit="C",warning_high="53",critical_low="0",node="shopfloor-01",sensor="Bat Temp",threshold_state="normal",warning_low="5"} 24
sensor_value{datacenter="WDRF",cluster="shopfloor",critical_high="9000",node="shopfloor-01",sensor="Bat Charge Volt",type="voltage",threshold_state="normal",unit="mV",warning_high="8900"} 8200
sensor_value{datacenter="WDRF",cluster="shopfloor",node="shopfloor-02",sensor="PSU1 InPwr Monitor",type="unknown",threshold_state="normal",unit="mW"} 132000
```
will force using `aggr_type` and `aggr_disks` for the label and the metric respectively.
119 changes: 0 additions & 119 deletions cmd/collectors/zapiperf/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,39 +48,6 @@ Parameters in poller section should define (at least) the address and authentica

It is recommended creating a read-only user on the ONTAP system dedicated to Harvest. See section [Authentication](#authentication) for guidance.

We can define the configuration file of the collector. If no configuration file is specified, the default configuration file (`conf/zapiperf/default.yaml`) will be used and if the file `conf/zapiperf/default.yaml` is present, it will be merged to the default one. If we specify our own configuration file for the collector, it can have any name, and it will not be merged.

Examples:

Define a poller that will run the ZapiPerf collector using its default configuration file:

```yaml
Pollers:
jamaica: # name of the poller
datacenter: munich
addr: 10.65.55.2
auth_style: basic_auth
username: harvest
password: 3t4ERTW%$W%c
collectors:
- ZapiPerf # will use conf/zapiperf/default.yaml and optionally merge with conf/zapiperf/custom.yaml
```
Define a poller that will run the ZapiPerf collector using a custom configuration file:
```yaml
Pollers:
jamaica: # name of the poller
addr: 10.65.55.2
auth_style: basic_auth
username: harvest
password: 3t4ERTW%$W%c
collectors:
- ZapiPerf:
- limited.yaml # will use conf/zapiperf/limited.yaml
# if more templates are added, they will be merged
```

### Collector configuration file

This configuration file (the "template") contains a list of objects that should be collected and the filenames of their configuration (explained in the next section).
Expand Down Expand Up @@ -140,89 +107,3 @@ Parameters in this section tell the exporters how to handle the collected data.
* `instances_keys` (list): display names of labels to export with each data-point
* `instance_labels` (list): display names of labels to export as a separate data-point
* `include_all_labels` (bool): export all labels with each data-point (overrides previous two parameters)

## Creating/editing subtemplates

You can use Harvest's `zapi` to explore available objects and counters on your cluster. Examples:

```sh
$ harvest zapi --poller <poller> show objects
# will print the list of zapiperf objects
$ harvest zapi --poller <poller> show counters --object ip
# will print the list of counters of ip object
$ harvest zapi --poller <poller> export counters --object ip
# will export the list of counters into a subtemplate
```
Instead of editing one of the existing templates, it's better to copy one and edit the copy. That way, your custom template will not be overwritten when upgrading Harvest. For example, if you want to change `conf/zapiperf/cdot/9.8.0/volume.yaml`, first create a copy (e.g., `conf/zapiperf/cdot/9.8.0/custom_volume.yaml`), then add these lines to `conf/zapiperf/custom.yaml` to override the default subtemplate:

```yaml
objects:
Volume: custom_volume.yaml
```

### Example subtemplate

In this example, we want to collect metrics of the `ip` object. These are the steps that we need to follow:

#### 1. Create new subtemplate

Create `conf/zapiperf/cdot/9.8.0/ip.yaml` with the following content:

```yaml
name: IP
query: ip
object: ip
instance_key: uuid
counters:
- instance_name
- instance_uuid
- node_name => node
- packets_delivered
- packets_forwarded
- packets_redirected
- packets_unforwardable
export_options:
instance_keys:
- ip
- node
```

### Enable the new template

To enable the new template, create `conf/zapiperf/custom.yaml` with the lines shown below.

In the future, if you add more templates, you can add those in this same file.

```yaml
objects:
IP: ip.yaml
```

### Test your changes and restart pollers

Test your new `IP` template with a single poller like this:
```
./bin/harvest start <poller> --foreground --verbose --collectors ZapiPerf --objects IP
```
Replace `<poller>` with the name of one of your ONTAP pollers.

Once you have confirmed that the new template works, restart any already running pollers that you want to pick up the new template(s).

### Check the metrics

If you are using the Prometheus exporter, check the metrics on the HTTP endpoint with `curl` or a web browser. E.g., my poller is exporting its data on port `15001`. Adjust as needed for your exporter. Note that the ZapiPerf collector will emit metrics only after the second poller, so you have to wait about 1 minute.

```
curl -s 'http://localhost:15001/metrics' | grep ip_
ip_packets_unforwardable{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967294",node="shopfloor-02"} 0
ip_packets_delivered{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967294",node="shopfloor-02"} 4245
ip_packets_unforwardable{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-02"} 0
ip_packets_delivered{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-02"} 0
ip_packets_redirected{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-02"} 0
ip_packets_forwarded{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-02"} 0
ip_packets_unforwardable{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-01"} 0
ip_packets_delivered{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-01"} 0
ip_packets_redirected{datacenter="WDRF",cluster="shopfloor",ip="ip_ipsid_0014967293",node="shopfloor-01"} 0
```
Loading

0 comments on commit 19b8f14

Please sign in to comment.