Merge pull request #75 from sentrysoftware/feature/issue-9-document-c…

…onnector-design-guide

Issue #9: Document Connector Design Guide

metricshub-doc/src/site/markdown/connector-design-guide/connector-object-references.md

@@ -0,0 +1,170 @@
+keywords: guide, connector, connector, object, reference
+description: This page shows how to reference connector objects such as sources, entries, columns and files, etc. inside the YAML document.
+
+# Connector Object References
+
+This page shows how to reference connector objects such as sources, entries, columns and files, etc. inside the YAML document.
+
+* [Source Reference](#source_reference)
+    * [Format](#source-format)
+    * [Example](#source-example)
+* [Entry Reference](#entry_reference)
+    * [Format](#entry-format)
+    * [Example](#entry-example)
+* [Column Reference](#column_reference)
+    * [Format](#column-format)
+    * [Example](#column-example)
+* [File Reference](#file_reference)
+    * [Format](#file-format)
+    * [Example](#file-example)
+* [Mono-Instance Reference](#mono-instance_reference)
+    * [Format](#mono-instance-format)
+    * [Example](#mono-instance-example)
+* [Translation Table Reference](#translation_table_reference)
+    * [Format](#translation-table-format)
+    * [Example](#translation-table-example)
+* [Awk Script Reference](#awk_script_reference)
+    * [Format](#awk-script-format)
+    * [Example](#awk-script-example)
+
+## Source Reference
+
+### <a id="source-format" />Format
+
+A Source can be referenced either with its full path or its relative path. A relative path can be used only if the referenced source is in the same monitor and same job as the current source.
+
+### <a id="source-example" />Example
+```yaml
+      mapping:
+        source: ${source::monitors.disk_controller.discovery.sources.source_discovery}
+```
+
+```yaml
+        sourceDiscovery:
+          type: tableJoin
+          leftTable: ${source::monitors.enclosure.collect.sources.source_chassis} # full path for a source in another monitor
+          rightTable: ${source::source_enclosure} # relative path
+          leftKeyColumn: 1
+          rightKeyColumn: 1
+```
+
+## Entry Reference
+
+### <a id="entry-format" />Format
+```yaml
+$<columnNumber>
+```
+
+### <a id="entry-example" />Example
+```yaml
+        source(3):
+          type: http
+          method: GET
+          executeForEachEntryOf:
+            source: ${source::monitors.enclosure.discovery.sources.source(2)}
+            concatMethod: list
+          path: /api/rest/StorageCenter/ScChassis/$2/PowerSupplyList
+```
+
+## Column Reference
+
+### <a id="column-format" />Format
+```yaml
+$<columnNumber>
+```
+
+### <a id="column-example" />Example
+```yaml
+      mapping:
+        # PowerSupply
+        # tableID;ID;DisplayName;objectType;enclosure/controllerID;deviceType
+        source: ${source::monitors.power_supply.discovery.sources.source(4)}
+        attributes:
+          id: $2
+          __display_id: $3
+          hw.parent.type: $6
+          hw.parent.id: $5
+          name: $3
+```
+
+## File Reference
+
+### <a id="file-format" />Format
+```yaml
+${file::<relativeFilePath>}
+```
+
+### <a id="file-example" />Example
+```yaml
+   criteria:
+    - type: osCommand
+      commandLine: /bin/sh ${file::storman-drives.sh}
+      expectedResult: Hard drive
+      errorMessage: No Adaptec Controller with Physical Disks attached or not enough rights to execute arcconf.
+```
+
+## Mono-Instance Reference
+
+### <a id="mono-instance-format" />Format
+```yaml
+${attribute::<attribute-key>}
+```
+
+### <a id="mono-instance-example" />Example
+```yaml
+ collect:
+      # Collect type is multi-instance
+      type: monoInstance
+      sources:
+        source(1):
+          type: osCommand
+          commandLine: /bin/sh ${file::script.sh} ${attribute::id}
+          keep: ^MSHW;
+          separators: ;
+          selectColumns: "2,3,4,5,6,7,8,9"
+```
+
+## Translation Table Reference
+
+### <a id="translation-table-format" />Format
+```yaml
+${translation::<translationTable>}
+```
+
+### <a id="translation-table-example" />Example
+```yaml
+    collect:
+      # Collect type = multi-instance
+      type: multiInstance
+      sources:
+        source(1):
+          # Source(1) = connUnitSensorTable SNMP Table
+          # ID;Status;Value;
+          type: snmpTable
+          oid: 1.3.6.1.4.1.1588.2.1.1.1.1.22.1
+          selectColumns: "ID,3,4"
+          computes:
+            # Translate the first column status into a PATROLStatus
+            # ID;PatrolStatus;Value;
+          - type: translate
+            column: 2
+            translationTable: ${translation::SensorStatusTranslationTable}
+```
+
+## Awk Script Reference
+
+### <a id="awk-script-format" />Format
+```yaml
+${awk::<script>}
+```
+
+### <a id="awk-script-example" />Example
+```yaml
+    monitors:
+      battery:
+        discovery:
+          mapping:
+            source: ${source::monitors.battery.discovery.sources.source(1)}
+            attributes:
+              name: ${awk::sprintf("%s (%s)", "Cisco", $1)}
+```

metricshub-doc/src/site/markdown/connector-design-guide/connector.md

@@ -0,0 +1,30 @@
+keywords: guide, connector
+description: The connector section defines the connector’s identifying information such as the display name, the version or detection criteria of the connector.
+
+# Connector
+
+The first part of a connector is a list of information defining its identity, what is the purpose of this connector and what type of platforms and systems it can be used against. The goal of this part is for someone to understand quickly what this connector is about.
+
+## Format
+
+```yaml
+connector:
+  displayName: # <string>
+  platforms: # <string>
+  reliesOn: # <string>
+  version:  # <string>
+  projectVersion: # <string> | default: ${project.version}
+  information: # <string>
+  detection: # <object>
+```
+
+## Properties
+| Property              | Description              |
+| --------------------- | ------------------------ |
+| `displayName` | Name of the connector, which can be displayed in the console or reported in the metric’s attribute.(`connector.status{name="Dell OpenManage (WMI)"}`)<br />This preferably refers to the underlying instrumentation layer (e.g.: Dell OpenManage (WMI)).<br />If several connectors are required to cover different aspects of a platform (one connector for the CPU, memory, another for the disks, and a last one for the network cards, for example), the name will specify it with a dash separator.<br /><br />The typical display name therefore looks like:<br />`<Instrumentation Layer> [ - Subcomponent ] [ - OS ] [ (protocol) ]`. |
+| `information` | Describes what the connector monitors and how.<br /><br /> This ends up in the documentation of the Hardware Connector Library as the description of the connector.<br /> Do not hesitate to provide details about the specific requirements for the connector to work properly. | 
+| `platforms` | Typical targeted system.<br /> Examples: "`HP ProLiant`" or "`Any system with SNMP`"<br /> This property is leveraged to build the Supported Platforms in the documentation.<br /> The platform name must be short and simple enough to group several connectors targeting the same type of systems.<br /> Several platforms can be specified in a comma-separated list.<br /> Connectors that monitor components that may be present in large number of platforms (e.g.: the <br /> connector which monitors network cards in all Windows systems) must specify: `Any system with [xxx]`. |
+| `reliesOn` | Name of the instrumentation layer this connector leverages. This can also be considered as the <br /> technical prerequisites for this connector work, but it can only mention one instrumentation layer. <br /><br />This also ends up in the documentation and in the [Supported Platforms](../platform-requirements.html) and it is important that all<br /> connectors have a consistent wording for this property. |
+| `projectVersion` | The current version of the connector library project. |
+| `version` | The current version of the connector. |
+| `detection` | Defines all the information required to perform connector’s detection. See specification in [Detection](detection.md). |

metricshub-doc/src/site/markdown/connector-design-guide/constants.md

@@ -0,0 +1,17 @@
+keywords: guide, connector, constants
+description: This page describes how to declare constant in a connector file.
+
+# Constants
+
+This page describes how to declare constant in a connector file.
+
+## Format
+
+```yaml
+connector:
+  # ...
+connector:
+  # ...
+constants: # <object>
+  <constantName>: # <string>
+```