outage-detector/README.md

# Outage Detector

This script pings a host and logs whether a connection could be established.
It then can also extract the major outages from these logs.
It is mainly used as a tool for statistical analysis of residential internet connections.

## Usage

You can set these options in a json file and pass it with the `--config` option.
Additional command line parameters override options defined in a config.

```txt
If no argument is passed then de defaults are assumed.

--config    Path to a config file in JSON format.
            To set a command line argument, use it as a key and set its value.
            Config is not used unless explicitly set.

--log       Path to a the file where results should be appended to.
            Created the file if it does not already exist.
            Default: ./connection.log

--host      IP or hostname of a server to query.
            Default: 1.1.1.1

--timeout   Set the timeout in seconds to use for the connection test
            Default: 2

--outages   Print the outages to stdout.
            Set the lenght in minutes where a connection loss is condidered an outage
            This option can only be used with --log.
            Default: 3

--stdout    Return the resulting logline in the terminal.
            Default Behaviour: Do not print to stdout.

--help      Print this menu
```

### Config

Save an example config options as a `.json` file with this format:

```json
{
    "host": "1.1.1.1",
    "timeout": null, // To use the default value of 2
    "log": "./connection.log",
}
```

### Example 1

```txt
$ outage_detector --config ./config.json --host 1.1.1.1 --log --stdout
> [YYYY-MM-DD HH:MM:SS][1.1.1.1][OK]
```

Loads values from `./config.json`.
Overrides `host` with `example.com`.
Appends the result to `log.txt` and prints it to `stdout`

```txt
$ outage_detector --config ./config.json --host example.com --log another.log --stdout
> [YYYY-MM-DD HH:MM:SS][1.1.1.1][FAIL]
```

Loads values from `./config.json`.
Overrides `host` with `example.com`.
Appends the result to `another.log` and prints it to `stdout`

### Example 2

```txt
$ outage_detector --log ./outage-detector.log --outages 5
> [YYYY-MM-DD HH:MM:SS][1.1.1.1] lasting for X Hours and Y Minutes
> [YYYY-MM-DD HH:MM:SS][1.1.1.1] lasting for X Hours and Y Minutes
```

Print to `stdout` all outages from `./outage-detector.log` in chronological order that lasted at least 5 minutes.