diff --git a/docgen.sh b/docgen.sh index 78ed7beb..498893d9 100755 --- a/docgen.sh +++ b/docgen.sh @@ -51,6 +51,7 @@ pydocmd simple jc.parsers.systemctl_lj+ > ../docs/parsers/systemctl_lj.md pydocmd simple jc.parsers.systemctl_ls+ > ../docs/parsers/systemctl_ls.md pydocmd simple jc.parsers.systemctl_luf+ > ../docs/parsers/systemctl_luf.md pydocmd simple jc.parsers.timedatectl+ > ../docs/parsers/timedatectl.md +pydocmd simple jc.parsers.traceroute+ > ../docs/parsers/traceroute.md pydocmd simple jc.parsers.uname+ > ../docs/parsers/uname.md pydocmd simple jc.parsers.uptime+ > ../docs/parsers/uptime.md pydocmd simple jc.parsers.w+ > ../docs/parsers/w.md diff --git a/docs/parsers/traceroute.md b/docs/parsers/traceroute.md new file mode 100644 index 00000000..4370a7e8 --- /dev/null +++ b/docs/parsers/traceroute.md @@ -0,0 +1,168 @@ +# jc.parsers.traceroute +jc - JSON CLI output utility traceroute Parser + +Usage: + + specify --traceroute as the first argument if the piped input is coming from traceroute + + Note: on OSX and FreeBSD be sure to redirect STDERR to STDOUT since the header line is sent to STDERR + e.g. $ traceroute 8.8.8.8 2>&1 | jc --traceroute + +Compatibility: + + 'linux', 'darwin', 'freebsd' + +Examples: + + $ traceroute google.com | jc --traceroute -p + { + "destination_ip": "216.58.194.46", + "destination_name": "google.com", + "hops": [ + { + "hop": 1, + "probes": [ + { + "annotation": null, + "asn": null, + "ip": "216.230.231.141", + "name": "216-230-231-141.static.houston.tx.oplink.net", + "rtt": 198.574 + }, + { + "annotation": null, + "asn": null, + "ip": "216.230.231.141", + "name": "216-230-231-141.static.houston.tx.oplink.net", + "rtt": null + }, + { + "annotation": null, + "asn": null, + "ip": "216.230.231.141", + "name": "216-230-231-141.static.houston.tx.oplink.net", + "rtt": 198.65 + } + ] + }, + ... + ] + } + + $ traceroute google.com | jc --traceroute -p -r + { + "destination_ip": "216.58.194.46", + "destination_name": "google.com", + "hops": [ + { + "hop": "1", + "probes": [ + { + "annotation": null, + "asn": null, + "ip": "216.230.231.141", + "name": "216-230-231-141.static.houston.tx.oplink.net", + "rtt": "198.574" + }, + { + "annotation": null, + "asn": null, + "ip": "216.230.231.141", + "name": "216-230-231-141.static.houston.tx.oplink.net", + "rtt": null + }, + { + "annotation": null, + "asn": null, + "ip": "216.230.231.141", + "name": "216-230-231-141.static.houston.tx.oplink.net", + "rtt": "198.650" + } + ] + }, + ... + ] + } + +## info +```python +info(self, /, *args, **kwargs) +``` + +## Traceroute +```python +Traceroute(self, dest_name, dest_ip) +``` + +Abstraction of a traceroute result. + +## Hop +```python +Hop(self, idx) +``` + +Abstraction of a hop in a traceroute. + +## Probe +```python +Probe(self, name=None, ip=None, asn=None, rtt=None, annotation=None) +``` + +Abstraction of a probe in a traceroute. + +## loads +```python +loads(data) +``` +Parser entry point. Parses the output of a traceroute execution +## process +```python +process(proc_data) +``` + +Final processing to conform to the schema. + +Parameters: + + proc_data: (dictionary) raw structured data to process + +Returns: + + Dictionary. Structured data with the following schema: + + { + "destination_ip": string, + "destination_name": string, + "hops": [ + { + "hop": integer, + "probes": [ + { + "annotation": string, + "asn": integer, + "ip": string, + "name": string, + "rtt": float + } + ] + } + ] + } + +## parse +```python +parse(data, raw=False, quiet=False) +``` + +Main text parsing function + +Parameters: + + data: (string) text data to parse + raw: (boolean) output preprocessed JSON if True + quiet: (boolean) suppress warning messages if True + +Returns: + + Dictionary. Raw or processed structured data. +