github.com/aristanetworks/goarista@v0.0.0-20240514173732-cca2755bbd44/cmd/octsdb/README.md (about)

     1  # octsdb
     2  
     3  This is a client for the OpenConfig gRPC interface that pushes telemetry to
     4  OpenTSDB.  Non-numerical data isn't supported by OpenTSDB and is silently
     5  dropped.
     6  
     7  This tool requires a config file to specify how to map the path of the
     8  notificatons coming out of the OpenConfig gRPC interface onto OpenTSDB
     9  metric names, and how to extract tags from the path.
    10  
    11  ## Getting Started
    12  To begin, a list of subscriptions is required (excerpt from `sampleconfig.json`):
    13  
    14  ```json
    15  	"subscriptions": [
    16  		"/Sysdb/interface/counter/eth/lag",
    17  		"/Sysdb/interface/counter/eth/slice/phy",
    18  
    19  		"/Sysdb/environment/temperature/status",
    20  		"/Sysdb/environment/cooling/status",
    21  		"/Sysdb/environment/power/status",
    22  
    23  		"/Sysdb/hardware/xcvr/status/all/xcvrStatus"
    24  	],
    25  	...
    26  ```
    27  
    28  Note that subscriptions should not end with a trailing `/` as that will cause
    29  the subscription to fail.
    30  
    31  Afterwards, the metrics are defined (excerpt from `sampleconfig.json`):
    32  
    33  ```json
    34  	"metrics": {
    35  		"tempSensor": {
    36  			"path": "/Sysdb/(environment)/temperature/status/tempSensor/(?P<sensor>.+)/((?:maxT|t)emperature)"
    37  		},
    38  		...
    39  	}
    40  ```
    41  
    42  In the metrics path, unnamed matched groups are used to make up the metric name, and named matched groups
    43  are used to extract optional tags. Note that unnamed groups are required, otherwise the metric
    44  name will be empty and the update will be silently dropped.
    45  
    46  For example, using the above metrics path applied to an update for the path
    47  `/Sysdb/environment/temperature/status/tempSensor/TempSensor1/temperature`
    48  will lead to the metric name `environment.temperature` and tags `sensor=TempSensor1`.
    49  
    50  You can optionally rewrite values of type string with integer values using StaticValueMap.
    51  ``` "metrics":{
    52        "operStatus":{
    53           "path":"/Sysdb/interface/status/eth/phy/slice/1/intfStatus/(?P<intf>.+)/operStatus$",
    54           "StaticValueMap":{
    55               "intfOperUp": 1,
    56               "intfOperDown": 0,
    57               "intfOperNotPresent": 0,
    58               "default": 0
    59           }
    60        }
    61     }
    62  ```
    63  ## Usage
    64  
    65  See the `-help` output, but here's an example to push all the metrics defined
    66  in the sample config file:
    67  ```
    68  octsdb -addr <switch-hostname>:6042 -config sampleconfig.json -text | nc <tsd-hostname> 4242
    69  ```