From 29536a361a96ec895420d74c359cff97b2c879ba Mon Sep 17 00:00:00 2001 From: Rahul Gupta Date: Thu, 2 Nov 2023 12:09:02 +0530 Subject: [PATCH 1/3] doc: changelog doc --- .../plugin/changelog/change_log_helper.go | 26 ++-- docs/plugins.md | 114 +++++++++++++++++- 2 files changed, 128 insertions(+), 12 deletions(-) diff --git a/cmd/poller/plugin/changelog/change_log_helper.go b/cmd/poller/plugin/changelog/change_log_helper.go index 448310a99..677d6b97a 100644 --- a/cmd/poller/plugin/changelog/change_log_helper.go +++ b/cmd/poller/plugin/changelog/change_log_helper.go @@ -56,27 +56,31 @@ func getChangeLogConfig(parentParams *node.Node, overwriteConfig []byte, logger ) object := parentParams.GetChildS("object").GetContentS() + useDefault := true + if len(overwriteConfig) > 0 { entry, err = preprocessOverwrite(object, overwriteConfig) if err != nil { logger.Warn().Err(err).Str("template", string(overwriteConfig)).Msg("failed to parse changelog dsl. Trying default") } else { - return entry, nil + useDefault = false } } - err = yaml.Unmarshal([]byte(defaultChangeLogTemplate), &config) - if err != nil { - return Entry{}, err + if useDefault { + err = yaml.Unmarshal([]byte(defaultChangeLogTemplate), &config) + if err != nil { + return Entry{}, err + } + i := slices.IndexFunc(config.ChangeLogs, func(entry Entry) bool { + return entry.Object == object + }) + if i == -1 { + return Entry{}, nil + } + entry = config.ChangeLogs[i] } - i := slices.IndexFunc(config.ChangeLogs, func(entry Entry) bool { - return entry.Object == object - }) - if i == -1 { - return Entry{}, nil - } - entry = config.ChangeLogs[i] // populate publish_labels if they are empty if entry.PublishLabels == nil { if exportOption := parentParams.GetChildS("export_options"); exportOption != nil { diff --git a/docs/plugins.md b/docs/plugins.md index 71e2bfd75..bbe245cad 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -631,4 +631,116 @@ compute_metric: # inode_used_percent = inode_files_used / inode_files_total * 100 ``` -# ChangeLog \ No newline at end of file +# ChangeLog Plugin + +The ChangeLog plugin is a feature of Harvest, designed to detect and track changes related to the creation, modification, and deletion of an object. By default, it supports volume, svm, and node objects. However, its functionality can be extended to track changes in any other objects by making relevant changes in the template. + +Please note that the ChangeLog plugin requires the `uuid` label, which is unique, to be collected by the template. Without the `uuid` label, the plugin will not function. + +The ChangeLog feature only detects changes when Harvest is up and running. It does not detect any changes that occur when Harvest is down. Additionally, the plugin currently does not detect changes in metric values. + +## Enabling the Plugin + +The plugin can be enabled in the templates under the plugins section. + +For volume, svm, and node objects, you can enable the plugin with the following configuration: + +```yaml +plugins: + - ChangeLog +``` + +For other objects, you need to specify the labels to track in the plugin configuration. These labels should be relevant to the object you want to track. If these labels are not specified in template, the plugin will not be able to track changes for the object. + +Here's an example of how to enable the plugin for an aggregate object: + +```yaml +plugins: + - ChangeLog: + track: + - aggr + - node + - state +``` + +In the above configuration, the plugin will track changes in the `aggr`, `node`, and `state` labels for the aggregate object. + +## Default Tracking for svm, node, volume + +By default, the plugin tracks changes in the following labels for svm, node, and volume objects: + +- svm: svm, state, type, anti_ransomware_state +- node: node, location, healthy +- volume: node, volume, svm, style, type, aggr, state, status + +For any other objects, defaults are not available and need to be defined in the plugin. + +These default settings can be overwritten as needed in the relevant templates. For instance, if you want to track `junction_path` labels for Volume, you can overwrite this in the volume template. + +```yaml +plugins: + - ChangeLog: + - track: + - node + - volume + - svm + - style + - type + - aggr + - state + - status + - junction_path +``` + +## Change Types and Metrics + +The ChangeLog plugin publishes a metric with various labels providing detailed information about the change when an object is created, modified, or deleted. + +### Object Creation + +When a new object is created, the ChangeLog plugin will publish a metric with the following labels: + +- The name of the ONTAP object that was changed (object) +- The type of change that was made (op) +- The timestamp when Harvest Poller captured the change (Metric Value) + +Example of metric shape for object creation: + +``` +change_log{aggr="umeng_aff300_aggr2", cluster="umeng-aff300-01-02", datacenter="u2", index="0", instance="localhost:12993", job="prometheus", node="umeng-aff300-01", object="volume", op="create", style="flexvol", svm="harvest", volume="harvest_demo"} 1698735558 +``` + +### Object Modification + +When an existing object is modified, the ChangeLog plugin will publish a metric with the following labels: + +- The name of the ONTAP object that was changed (object) +- The type of change that was made (op) +- The property of the object which was modified (Track) +- The new value of the object after the change was made (New Value) +- The previous value of the object before the change was made (Old Value) +- The timestamp when Harvest Poller captured the change (Metric Value) + +Example of metric shape for object modification: + +``` +change_log{aggr="umeng_aff300_aggr2", cluster="umeng-aff300-01-02", datacenter="u2", index="1", instance="localhost:12993", job="prometheus", new_value="offline", node="umeng-aff300-01", object="volume", old_value="online", op="update", style="flexvol", svm="harvest", track="state", volume="harvest_demo"} 1698735677 +``` + +### Object Deletion + +When an object is deleted, the ChangeLog plugin will publish a metric with the following labels: + +- The name of the ONTAP object that was changed (object) +- The type of change that was made (op) +- The timestamp when Harvest Poller captured the change (Metric Value) + +Example of metric shape for object deletion: + +``` +change_log{aggr="umeng_aff300_aggr2", cluster="umeng-aff300-01-02", datacenter="u2", index="2", instance="localhost:12993", job="prometheus", node="umeng-aff300-01", object="volume", op="delete", style="flexvol", svm="harvest", volume="harvest_demo"} 1698735708 +``` + +## Viewing the Metrics + +You can view the metrics published by the ChangeLog plugin in the `ChangeLog Monitor` dashboard in `Grafana`. This dashboard provides a visual representation of the changes tracked by the plugin for volume, svm, and node objects. \ No newline at end of file From 90805ec85306d19a2b170948765ed2ac3731917e Mon Sep 17 00:00:00 2001 From: Chris Grindstaff Date: Mon, 6 Nov 2023 23:58:47 -0500 Subject: [PATCH 2/3] doc: changelog (#2463) --- docs/plugins.md | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index bbe245cad..806655d2b 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -455,7 +455,7 @@ include_regex: ## value_mapping -value_mapping was deprecated in 21.11 and removed in 22.02. Use [value_to_num mapping](#valuetonum) instead. +value_mapping was deprecated in 21.11 and removed in 22.02. Use [value_to_num](#value_to_num) mapping instead. ## value_to_num @@ -633,11 +633,11 @@ compute_metric: # ChangeLog Plugin -The ChangeLog plugin is a feature of Harvest, designed to detect and track changes related to the creation, modification, and deletion of an object. By default, it supports volume, svm, and node objects. However, its functionality can be extended to track changes in any other objects by making relevant changes in the template. +The ChangeLog plugin is a feature of Harvest, designed to detect and track changes related to the creation, modification, and deletion of an object. By default, it supports volume, svm, and node objects. Its functionality can be extended to track changes in other objects by making relevant changes in the template. Please note that the ChangeLog plugin requires the `uuid` label, which is unique, to be collected by the template. Without the `uuid` label, the plugin will not function. -The ChangeLog feature only detects changes when Harvest is up and running. It does not detect any changes that occur when Harvest is down. Additionally, the plugin currently does not detect changes in metric values. +The ChangeLog feature only detects changes when Harvest is up and running. It does not detect changes that occur when Harvest is down. Additionally, the plugin does not detect changes in metric values. ## Enabling the Plugin @@ -650,7 +650,7 @@ plugins: - ChangeLog ``` -For other objects, you need to specify the labels to track in the plugin configuration. These labels should be relevant to the object you want to track. If these labels are not specified in template, the plugin will not be able to track changes for the object. +For other objects, you need to specify the labels to track in the plugin configuration. These labels should be relevant to the object you want to track. If these labels are not specified in the template, the plugin will not be able to track changes for the object. Here's an example of how to enable the plugin for an aggregate object: @@ -673,7 +673,7 @@ By default, the plugin tracks changes in the following labels for svm, node, and - node: node, location, healthy - volume: node, volume, svm, style, type, aggr, state, status -For any other objects, defaults are not available and need to be defined in the plugin. +Other objects are not tracked by default. These default settings can be overwritten as needed in the relevant templates. For instance, if you want to track `junction_path` labels for Volume, you can overwrite this in the volume template. @@ -700,9 +700,11 @@ The ChangeLog plugin publishes a metric with various labels providing detailed i When a new object is created, the ChangeLog plugin will publish a metric with the following labels: -- The name of the ONTAP object that was changed (object) -- The type of change that was made (op) -- The timestamp when Harvest Poller captured the change (Metric Value) +| Label | Description | +|--------------|-----------------------------------------------------------------------------| +| object | name of the ONTAP object that was changed | +| op | type of change that was made | +| metric value | timestamp when Harvest captured the change. 1698735558 in the example below | Example of metric shape for object creation: @@ -714,12 +716,14 @@ change_log{aggr="umeng_aff300_aggr2", cluster="umeng-aff300-01-02", datacenter=" When an existing object is modified, the ChangeLog plugin will publish a metric with the following labels: -- The name of the ONTAP object that was changed (object) -- The type of change that was made (op) -- The property of the object which was modified (Track) -- The new value of the object after the change was made (New Value) -- The previous value of the object before the change was made (Old Value) -- The timestamp when Harvest Poller captured the change (Metric Value) +| Label | Description | +|--------------|-----------------------------------------------------------------------------| +| object | name of the ONTAP object that was changed | +| op | type of change that was made | +| track | property of the object which was modified | +| new_value | new value of the object after the change | +| old_value | previous value of the object before the change | +| metric value | timestamp when Harvest captured the change. 1698735677 in the example below | Example of metric shape for object modification: @@ -731,9 +735,12 @@ change_log{aggr="umeng_aff300_aggr2", cluster="umeng-aff300-01-02", datacenter=" When an object is deleted, the ChangeLog plugin will publish a metric with the following labels: -- The name of the ONTAP object that was changed (object) -- The type of change that was made (op) -- The timestamp when Harvest Poller captured the change (Metric Value) + +| Label | Description | +|--------------|-----------------------------------------------------------------------------| +| object | name of the ONTAP object that was changed | +| op | type of change that was made | +| metric value | timestamp when Harvest captured the change. 1698735708 in the example below | Example of metric shape for object deletion: From e1401df015be5615467d1b00e5fb5fa908d175e3 Mon Sep 17 00:00:00 2001 From: Rahul Gupta Date: Tue, 7 Nov 2023 16:36:48 +0530 Subject: [PATCH 3/3] doc: format text --- grafana/dashboards/cmode/changelogMonitor.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/grafana/dashboards/cmode/changelogMonitor.json b/grafana/dashboards/cmode/changelogMonitor.json index 67e78e71e..e71adbc67 100644 --- a/grafana/dashboards/cmode/changelogMonitor.json +++ b/grafana/dashboards/cmode/changelogMonitor.json @@ -107,7 +107,7 @@ }, "id": 305, "options": { - "content": "To use this dashboard, enable the ChangeLog plugin for node, svm, and volume templates. For more details, visit the [ChangeLog documentation](https://netapp.github.io/harvest/latest/plugins/#changelog).", + "content": "
\n\nTo use this dashboard, enable the ChangeLog plugin for node, svm, and volume templates. For more details, visit the [ChangeLog documentation](https://netapp.github.io/harvest/latest/plugins/#changelog).\n", "mode": "markdown" }, "pluginVersion": "8.1.8",