Metadata-Version: 2.1
Name: check-json
Version: 0.1.4
Summary: A Nagios/Icinga plugin for monitoring JSON files with Jq filters
Home-page: https://gitlab.com/cspeterson/check_json
Author: Christopher Peterson
Author-email: contact@cspeterson.net
License: UNKNOWN
Project-URL: Bug Tracker, https://gitlab.com/cspeterson/check_json/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.4
Description-Content-Type: text/markdown
License-File: LICENSE

check_json
===========

Check_json is a [Nagios]/[Icinga2] plugin for monitoring JSON files with [Jq] filters.

Requires Python 3.6+

# Installation

You can install with [pip]:

```bash
python3 -m pip install check-json
```

Or install from source:

```bash
git clone https://gitlab.com/cspeterson/check_json.git check_json.git
pip install check_json.git
```

# Usage

Pass the plugin any number of Jq filters and a JSON file. The plugin will report OK so long as no filters evaluate to `false` or `null`.

Outputs Nagios standard perfdata for each filter reported with `1` for success and `0` for failure.

If a given filter is concluded by a comment string of the format `# some-descriptive-string`, it will be used as the perfdata label for that filter.

For all of the things you can do in a filter, refer to the [JQ Manual] for for your version of libjq.

```bash
# A minimal example: report OK if a single filter evaluates to other
# than false/null.
check_json --filter '.select(somekey)' /path/to/jsonfile

# As above, but label that filter "myfilter" in the reporting

check_json --filter '.select(somekey) # myfilter' /path/to/jsonfile

# Multiple, separate filters
check_json --filter '.somekey != "somevalue"' --filter '.otherkey != "othervalue"' /path/to/jsonfile

# Source a filter from a jsonfile
check_json --filter-file /path/to/filterfile /path/to/jsonfile
```

## Icinga2

Here is an Icinga2 `CheckCommand` object for this plugin:

```
object CheckCommand "check_json" {
  command = [ PluginDir + "/check_json", ]
  arguments = {    "--fail-status" = {
      description = "Specify the status to report when a filter comes back false/null. Defaults to warning."
      set_if = "$check_json_fail_status$"
      value = "$check_json_fail_status$"
    }
    "--filter" = {
      description = "A JQ filter to run on the given JSON file."
      set_if = "$check_json_filter$"
      value = "$check_json_filter$"
    }
    "--filter-file" = {
      description = "A file containing a JQ filter to run on the given JSON file."
      set_if = "$check_json_filter_file$"
      value = "$check_json_filter_file$"
    }
    jsonfile = {
      description = "The path to the file to inspect"
      value = "$check_json_jsonfile$"
    }
  }
}
```

NOTE on the command path: the above Icinga2 configuration object points to the `check_json` command in Icinga2's configured `PluginDir`, but this can be configured however you like. For instance:

* point it to wherever it is installed by its full path
* symlink from the specified path to the actual script.
* or take the kludge route, leave it as-is, and copy `check_json/__main__.py` from this repo into `PluginDir + "/check_json"`

Up to you!

# Limitations

What this plugin is *not* for:

* Huge JSON files. This plugin processes and filters the entire JSON file given every time it runs.
* Keeping place in a log file over time. For that (though with admittedly simpler pattern matching), see [check_logfiles].

# Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

To run the test suite:

```bash
# Up to you to create virtual environments etc
# make dependencies
make
```

Please make sure to update tests as appropriate.

# License

[MIT]


[Icinga2]: https://en.wikipedia.org/wiki/Icinga
[Jq Manual]: https://stedolan.github.io/jq/manual/
[Jq]: https://stedolan.github.io/jq/
[MIT]: https://choosealicense.com/licenses/mit/
[Nagios]: https://en.wikipedia.org/wiki/Nagios
[check_logfiles]: https://labs.consol.de/nagios/check_logfiles/index.html
[pip]: https://pip.pypa.io/en/stable/


