Merge pull request #218 from rustycl0ck/fix-example-doc

SuperQ · web-flow · commit 7ab7efcafd39 · 2023-06-06T04:45:03.000+02:00
Fix example syntax and update documentation
diff --git a/README.md b/README.md
@@ -3,103 +3,73 @@ json_exporter
 [![CircleCI](https://circleci.com/gh/prometheus-community/json_exporter.svg?style=svg)](https://circleci.com/gh/prometheus-community/json_exporter)
 
 A [prometheus](https://prometheus.io/) exporter which scrapes remote JSON by JSONPath.
-For checking the JSONPath configuration supported by this exporter please head over [here](https://kubernetes.io/docs/reference/kubectl/jsonpath/).  
-Checkout the [examples](/examples) directory for sample exporter configuration, prometheus configuration and expected data format.  
 
-#### :warning: The configuration syntax has changed in version `0.3.x`. If you are migrating from `0.2.x`, then please use the above mentioned JSONPath guide for correct configuration syntax.
+- [Supported JSONPath Syntax](https://kubernetes.io/docs/reference/kubectl/jsonpath/)
+- [Examples configurations](/examples)
 
 ## Example Usage
 
 ```console
-$ cat examples/data.json
-{
-    "counter": 1234,
-    "values": [
-        {
-            "id": "id-A",
-            "count": 1,
-            "some_boolean": true,
-            "state": "ACTIVE"
-        },
-        {
-            "id": "id-B",
-            "count": 2,
-            "some_boolean": true,
-            "state": "INACTIVE"
-        },
-        {
-            "id": "id-C",
-            "count": 3,
-            "some_boolean": false,
-            "state": "ACTIVE"
-        }
-    ],
-    "location": "mars"
-}
-
-$ cat examples/config.yml
----
-modules:
-  default:
-    metrics:
-    - name: example_global_value
-      path: "{ .counter }"
-      help: Example of a top-level global value scrape in the json
-      labels:
-        environment: beta # static label
-        location: "planet-{.location}"          # dynamic label
-
-    - name: example_value
-      type: object
-      help: Example of sub-level value scrapes from a json
-      path: '{.values[?(@.state == "ACTIVE")]}'
-      labels:
-        environment: beta # static label
-        id: '{.id}'          # dynamic label
-      values:
-        active: 1      # static value
-        count: '{.count}' # dynamic value
-        boolean: '{.some_boolean}'
-
-    headers:
-      X-Dummy: my-test-header
+## SETUP
 
+$ make build
+$ ./json_exporter --config.file examples/config.yml &
 $ python3 -m http.server 8000 &
 Serving HTTP on :: port 8000 (http://[::]:8000/) ...
 
-$ ./json_exporter --config.file examples/config.yml &
 
-$ curl "http://localhost:7979/probe?module=default&target=http://localhost:8000/examples/data.json" | grep ^example
+## TEST with 'default' module
+
+$ curl "http://localhost:7979/probe?module=default&target=http://localhost:8000/examples/data.json"
+# HELP example_global_value Example of a top-level global value scrape in the json
+# TYPE example_global_value untyped
 example_global_value{environment="beta",location="planet-mars"} 1234
+# HELP example_timestamped_value_count Example of a timestamped value scrape in the json
+# TYPE example_timestamped_value_count untyped
+example_timestamped_value_count{environment="beta"} 2
+# HELP example_value_active Example of sub-level value scrapes from a json
+# TYPE example_value_active untyped
 example_value_active{environment="beta",id="id-A"} 1
 example_value_active{environment="beta",id="id-C"} 1
+# HELP example_value_boolean Example of sub-level value scrapes from a json
+# TYPE example_value_boolean untyped
 example_value_boolean{environment="beta",id="id-A"} 1
 example_value_boolean{environment="beta",id="id-C"} 0
+# HELP example_value_count Example of sub-level value scrapes from a json
+# TYPE example_value_count untyped
 example_value_count{environment="beta",id="id-A"} 1
 example_value_count{environment="beta",id="id-C"} 3
 
-# To test through prometheus:
+
+## TEST with a different module for different json file
+
+$ curl "http://localhost:7979/probe?module=animals&target=http://localhost:8000/examples/animal-data.json"
+# HELP animal_population Example of top-level lists in a separate module
+# TYPE animal_population untyped
+animal_population{name="deer",predator="false"} 456
+animal_population{name="lion",predator="true"} 123
+animal_population{name="pigeon",predator="false"} 789
+
+
+## TEST through prometheus:
+
 $ docker run --rm -it -p 9090:9090 -v $PWD/examples/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus
 ```
 Then head over to http://localhost:9090/graph?g0.range_input=1h&g0.expr=example_value_active&g0.tab=1 or http://localhost:9090/targets to check the scraped metrics or the targets.
 
 ## Using custom timestamps
 
-This exporter allows you to use a field of the metric as the (unix/epoch) timestamp for the data as an int64. However, this may lead to unexpected behaviour, as the prometheus implements a [Staleness](https://prometheus.io/docs/prometheus/latest/querying/basics/#staleness) mechanism. Including timestamps in metrics disabled this staleness handling and can make data visible for longer than expected.
-
-## Exposing metrics through HTTPS
+This exporter allows you to use a field of the metric as the (unix/epoch) timestamp for the data as an int64. However, this may lead to unexpected behaviour, as the prometheus implements a [Staleness](https://prometheus.io/docs/prometheus/latest/querying/basics/#staleness) mechanism.
 
-TLS configuration supported by this exporter can be found at [exporter-toolkit/web](https://github.com/prometheus/exporter-toolkit/blob/v0.5.1/docs/web-configuration.md)
+:warning: Including timestamps in metrics disables the staleness handling and can make data visible for longer than expected.
 
-## Build
+## Exposing metrics through HTTPS
 
-```sh
-make build
-```
+TLS configuration supported by this exporter can be found at [exporter-toolkit/web](https://github.com/prometheus/exporter-toolkit/blob/v0.9.0/docs/web-configuration.md)
 
 ## Sending body content for HTTP `POST`
 
-If `body` paramater is set in config, it will be sent by the exporter as the body content in the scrape request. The HTTP method will also be set as 'POST' in this case.
+If `modules.<module_name>.body` paramater is set in config, it will be sent by the exporter as the body content in the scrape request. The HTTP method will also be set as 'POST' in this case.
 ```yaml
 body:
   content: |
@@ -132,9 +102,6 @@ Then `curl "http://exporter:7979/probe?target=http://scrape_target:8080/test/dat
 ## Docker
 
 ```console
-docker run \
-  -v $PWD/examples/config.yml:/config.yml \
-  quay.io/prometheuscommunity/json-exporter \
-  --config.file=/config.yml
+$ docker run -v $PWD/examples/config.yml:/config.yml quay.io/prometheuscommunity/json-exporter --config.file=/config.yml
 ```
 
diff --git a/examples/animal-data.json b/examples/animal-data.json
@@ -0,0 +1,17 @@
+[
+  {
+    "noun": "lion",
+    "population": 123,
+    "predator": true
+  },
+  {
+    "noun": "deer",
+    "population": 456,
+    "predator": false
+  },
+  {
+    "noun": "pigeon",
+    "population": 789,
+    "predator": false
+  }
+]
diff --git a/examples/config.yml b/examples/config.yml
@@ -1,45 +1,49 @@
 ---
 modules:
   default:
+    headers:
+      X-Dummy: my-test-header
     metrics:
     - name: example_global_value
-      path: "{ .counter }"
+      path: '{ .counter }'
       help: Example of a top-level global value scrape in the json
       labels:
         environment: beta # static label
-        location: "planet-{.location}"          # dynamic label
+        location: 'planet-{.location}'          # dynamic label
     - name: example_timestamped_value
+      type: object
       path: '{ .values[?(@.state == "INACTIVE")] }'
-      epochTimestamp: "{ .timestamp }"
+      epochTimestamp: '{ .timestamp }'
       help: Example of a timestamped value scrape in the json
       labels:
         environment: beta # static label
+      values:
+        count: '{.count}' # dynamic value
     - name: example_value
       type: object
       help: Example of sub-level value scrapes from a json
       path: '{.values[?(@.state == "ACTIVE")]}'
       labels:
         environment: beta # static label
-        id: '{.id}'          # dynamic label
+        id: '{.id}'       # dynamic label
       values:
-        active: 1      # static value
+        active: 1         # static value
         count: '{.count}' # dynamic value
         boolean: '{.some_boolean}'
-    headers:
-      X-Dummy: my-test-header
 
-    # If 'body' is set, it will be sent by the exporter as the body content in the scrape request. The HTTP method will also be set as 'POST' in this case.
-    # body:
-    #   content: |
-    #     {"time_diff": "1m25s", "anotherVar": "some value"}
-
-    # The body content can also be a Go Template (https://golang.org/pkg/text/template), with all the functions from the Sprig library (https://masterminds.github.io/sprig/) available. All the query parameters sent by prometheus in the scrape query to the exporter, are available in the template.
-    # body:
-    #   content: |
-    #     {"time_diff": "{{ duration `95` }}","anotherVar": "{{ .myVal | first }}"}
-    #   templatize: true
+  animals:
+    metrics:
+    - name: animal
+      type: object
+      help: Example of top-level lists in a separate module
+      path: '{ [*] }'
+      labels:
+        name: '{ .noun }'
+        predator: '{ .predator }'
+      values:
+        population: '{ .population }'
 
-    # For full http client config parameters, ref: https://pkg.go.dev/github.com/prometheus/common/config?tab=doc#HTTPClientConfig
+    ## HTTP connection configurations can be set in 'modules.<module_name>.http_client_config' field. For full http client config parameters, ref: https://pkg.go.dev/github.com/prometheus/common/config?tab=doc#HTTPClientConfig
     #
     # http_client_config:
     #   tls_config:
@@ -49,5 +53,17 @@ modules:
     #     #password: veryverysecret
     #     password_file: /tmp/mysecret.txt
 
-    # Accepted status codes for this probe. Defaults to 2xx.
-    # valid_status_codes: [ <int>, ... | default = 2xx ]
+    ## List of accepted status codes for this probe can be set in 'modules.<module_name>.valid_status_codes' field. Defaults to 2xx.
+    # valid_status_codes: [ <int>, ... | default = 2xx ]
+
+    ## If 'modueles.<module_name>.body' field is set, it will be sent by the exporter as the body content in the scrape request. The HTTP method will also be set as 'POST' in this case.
+    # body:
+    #   content: |
+    #     {"time_diff": "1m25s", "anotherVar": "some value"}
+
+    ## The body content can also be a Go Template (https://golang.org/pkg/text/template), with all the functions from the Sprig library (https://masterminds.github.io/sprig/) available. All the query parameters sent by prometheus in the scrape query to the exporter, are available in the template.
+    # body:
+    #   content: |
+    #     {"time_diff": "{{ duration `95` }}","anotherVar": "{{ .myVal | first }}"}
+    #   templatize: true
+
