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

     1  # ocprometheus
     2  
     3  This is a client for the OpenConfig gRPC interface that pushes telemetry to
     4  Prometheus. Numerical and boolean (converted to 1 for true and 0 for false) are
     5  supported. Non-numerical data isn't supported by Prometheus and is silently
     6  dropped. Arrays (even with numeric values) are not yet supported.
     7  
     8  This tool requires a config file to specify how to map the path of the
     9  notificatons coming out of the OpenConfig gRPC interface onto Prometheus
    10  metric names, and how to extract labels from the path.  For example, the
    11  following rule, excerpt from `sampleconfig_above_4.20.yml`:
    12  
    13  ```yaml
    14  metrics:
    15          - name: tempSensor
    16            path: /Sysdb/environment/temperature/status/tempSensor/(?P<sensor>.+)/(?P<type>(?:maxT|t)emperature)/value
    17            help: Temperature and Maximum Temperature
    18            # ...
    19  ```
    20  
    21  Applied to an update for the path
    22  `/Sysdb/environment/temperature/status/tempSensor/TempSensor1/temperature/value`
    23  will lead to the metric name `tempSensor` and labels `sensor=TempSensor1` and `type=temperature`.
    24  
    25  Basically, named groups are used to extract (optional) metrics.
    26  Unnamed groups will be given labels names like "unnamedLabelX" (where X is the group's position).
    27  The timestamps from the notifications are not preserved since Prometheus uses a pull model and
    28  doesn't have (yet) support for exporter specified timestamps.
    29  Prometheus 2.0 will probably support timestamps.
    30  
    31  Support for `eos_native` origin when using ocprometheus with the Octa agent (enabled with `provider eos-native` under `management api gnmi`) was added as part of #c6473e3ed183a4706d17336671d4e5be1991b7df
    32  
    33  The [sample_configs](./sample_configs) folder contains per platform examples using EOS native paths and also examples for OpenConfig paths.
    34  
    35  ## Usage
    36  
    37  See the `-help` output, but here's an example to push all the metrics defined
    38  in the sample config file:
    39  ```
    40  ocprometheus -addr <switch-hostname>:6042 -config sampleconfig.yml
    41  ```
    42  
    43  For more usage examples and a detailed demo please visit:
    44  https://eos.arista.com/streaming-eos-telemetry-states-to-prometheus/
    45  
    46  ### Dynamic label extraction
    47  
    48  This feature can be enabled by passing the `-enable-description-labels` flag. Paths where labels can be extracted from are defined in the configuration file, e.g.
    49  
    50  ```yaml
    51  description-label-subscriptions:
    52          - /interfaces/interface/state/description
    53          - /network-instances/network-instance/protocols/protocol/static-routes/static/state/description
    54  ```
    55  
    56  These paths are used to dynamically retrieve labels from other nodes. The default regex used is `\[([^=\]]+)(=[^]]+)?]`.
    57  It finds the nearest list node and adds these labels to any nodes under that list node.
    58  
    59  For example, with the example subscriptions above, if we got the following description `[baz][foo=bar]` on the path
    60  `interfaces/interface[name=Ethernet4]/state/description`, it will add the labels `baz=1` and `foo=bar` to all metrics
    61  under `interfaces/interface[name=Ethernet4]`, e.g. interfaces/interface[name=Ethernet4]/state/counter/in-pkts will have
    62  these labels attached to it. The description regex can be changed by passing the `-description-regex <regex>` flag.
    63  
    64  These labels will update dynamically as the descriptions change on the box.