From acd092a977bc498ba287b4401d84ba26dc438e1c Mon Sep 17 00:00:00 2001
From: Holger Obermaier <40787752+ho-ob@users.noreply.github.com>
Date: Thu, 11 Aug 2022 15:36:18 +0200
Subject: [PATCH] Add redfish receiver documentation

---
 receivers/redfishReceiver.go | 11 +++----
 receivers/redfishReceiver.md | 56 ++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 5 deletions(-)
 create mode 100644 receivers/redfishReceiver.md

diff --git a/receivers/redfishReceiver.go b/receivers/redfishReceiver.go
index 49a9a07..2c3b6a9 100644
--- a/receivers/redfishReceiver.go
+++ b/receivers/redfishReceiver.go
@@ -30,7 +30,8 @@ type RedfishReceiver struct {
 		IntervalString string `json:"interval,omitempty"`
 		Interval       time.Duration
 
-		// Control whether a client verifies the server's certificate (default: true)
+		// Control whether a client verifies the server's certificate
+		// (default: true == do not verify server's certificate)
 		HttpInsecure bool `json:"http_insecure,omitempty"`
 		// Time limit for requests made by this HTTP client (default: 10 s)
 		HttpTimeoutString string `json:"http_timeout,omitempty"`
@@ -45,10 +46,10 @@ type RedfishReceiver struct {
 
 		// Client config for each redfish service
 		ClientConfigs []struct {
-			Hostname *string `json:"hostname"`
-			Username *string `json:"username"`
-			Password *string `json:"password"`
-			Endpoint *string `json:"endpoint"`
+			Hostname *string `json:"hostname"` // Hostname the redfish service belongs to
+			Username *string `json:"username"` // User name to authenticate with
+			Password *string `json:"password"` // Password to use for authentication
+			Endpoint *string `json:"endpoint"` // URL of the redfish service
 
 			// Per client disable collection of power or thermal metrics
 			DisablePowerMetrics   bool `json:"disable_power_metrics"`
diff --git a/receivers/redfishReceiver.md b/receivers/redfishReceiver.md
new file mode 100644
index 0000000..524c330
--- /dev/null
+++ b/receivers/redfishReceiver.md
@@ -0,0 +1,56 @@
+## Redfish receiver
+
+The Redfish receiver uses the [Redfish (specification)](https://www.dmtf.org/standards/redfish) to query thermal and power metrics. Thermal metrics may include various fan speeds and temperatures. Power metrics may include the current power consumption of various hardware components. It may also include the minimum, maximum and average power consumption of these components in a given time interval. The receiver will poll each configured redfish device once in a given interval. Multiple devices can be accessed in parallel to increase throughput.
+
+### Configuration structure
+
+```json
+{
+    "<redfish receiver name>": {
+        "type": "redfish",
+        "exclude_metrics": [ "min_consumed_watts" ],
+        "client_config": [
+            {
+                "hostname": "<host 1>",
+                "username": "<user 1>",
+                "password": "<password 1>",
+                "endpoint": "https://<endpoint 1>"
+            },
+            {
+                "hostname": "<host 2>",
+                "username": "<user 2>",
+                "password": "<password 2>",
+                "endpoint": "https://<endpoint 2>",
+                "disable_power_metrics": true
+            },
+            {
+                "hostname": "<host 3>",
+                "username": "<user 3>",
+                "password": "<password 3>",
+                "endpoint": "https://<endpoint 3>",
+                "disable_thermal_metrics": true
+            }
+        ]
+    }
+}
+```
+
+Global settings:
+
+- `fanout`: Maximum number of simultaneous redfish connections (default: 64)
+- `interval`: How often the redfish power metrics should be read and send to the sink (default: 30 s)
+- `http_insecure`: Control whether a client verifies the server's certificate (default: true == do not verify server's certificate)
+- `http_timeout`: Time limit for requests made by this HTTP client (default: 10 s)
+
+Global and per redfish device settings:
+
+- `disable_power_metrics`: disable collection of power metrics
+- `disable_thermal_metrics`: disable collection of thermal metrics
+- `exclude_metrics`: list of excluded metrics
+
+Per redfish device settings:
+
+- `hostname`: hostname the redfish service belongs to
+- `username`: User name to authenticate with
+- `password`: Password to use for authentication
+- `endpoint`: URL of the redfish service