From 6b7430329cbe1bfb95b47bcfe031906641c127e1 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 22 Sep 2021 14:38:13 -0700 Subject: [PATCH] doc update --- README.md | 2 + docs/parsers/vmstat.md | 145 +++++++++++++++++++++++++++++++++++++++ docs/parsers/vmstat_s.md | 105 ++++++++++++++++++++++++++++ jc/parsers/vmstat_s.py | 6 ++ man/jc.1 | 12 +++- 5 files changed, 269 insertions(+), 1 deletion(-) create mode 100644 docs/parsers/vmstat.md create mode 100644 docs/parsers/vmstat_s.md diff --git a/README.md b/README.md index 87be27ee..de0f2c7b 100644 --- a/README.md +++ b/README.md @@ -177,6 +177,8 @@ The JSON output can be compact (default) or pretty formatted with the `-p` optio - `--uname` enables the `uname -a` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/uname)) - `--upower` enables the `upower` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/upower)) - `--uptime` enables the `uptime` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/uptime)) +- `--vmstat` enables the `vmstat` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/vmstat)) +- `--vmstat-s` enables the `vmstat` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/vmstat_s)) - `--w` enables the `w` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/w)) - `--wc` enables the `wc` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/wc)) - `--who` enables the `who` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/who)) diff --git a/docs/parsers/vmstat.md b/docs/parsers/vmstat.md new file mode 100644 index 00000000..c7cc74d7 --- /dev/null +++ b/docs/parsers/vmstat.md @@ -0,0 +1,145 @@ +[Home](https://kellyjonbrazil.github.io/jc/) + +# jc.parsers.vmstat +jc - JSON CLI output utility `vmstat` command output parser + +Options supported: `-a`, `-w`, `-d`, `-t` + +Usage (cli): + + $ vmstat | jc --vmstat + + or + + $ jc vmstat + +Usage (module): + + import jc.parsers.vmstat + result = jc.parsers.vmstat.parse(vmstat_command_output) + +Schema: + + [ + { + 'runnable_procs': integer, + 'uninterruptible_sleeping_procs': integer, + 'virtual_mem_used': integer, + 'free_mem': integer, + 'buffer_mem': integer, + 'cache_mem': integer, + 'inactive_mem': integer, + 'active_mem': integer, + 'swap_in': integer, + 'swap_out': integer, + 'blocks_in': integer, + 'blocks_out': integer, + 'interrupts': integer, + 'context_switches': integer, + 'user_time': integer, + 'system_time': integer, + 'idle_time': integer, + 'io_wait_time': integer, + 'stolen_time': integer, + 'disk': string, + 'total_reads': integer, + 'merged_reads': integer, + 'sectors_read': integer, + 'reading_ms': integer, + 'total_writes': integer, + 'merged_writes': integer, + 'sectors_written': integer, + 'writing_ms': integer, + 'current_io': integer, + 'io_seconds': integer, + 'timestamp': string, + 'timezone': string, + 'epoch': integer, # naive timestamp if -t flag is used + 'epoch_utc': integer # aware timestamp if -t flag is used and UTC TZ + } + ] + +Examples: + + $ vmstat | jc --vmstat -p + [ + { + "runnable_procs": 2, + "uninterruptible_sleeping_procs": 0, + "virtual_mem_used": 0, + "free_mem": 2794468, + "buffer_mem": 2108, + "cache_mem": 741208, + "inactive_mem": null, + "active_mem": null, + "swap_in": 0, + "swap_out": 0, + "blocks_in": 1, + "blocks_out": 3, + "interrupts": 29, + "context_switches": 57, + "user_time": 0, + "system_time": 0, + "idle_time": 99, + "io_wait_time": 0, + "stolen_time": 0, + "timestamp": null, + "timezone": null + } + ] + + $ vmstat | jc --vmstat -p -r + [ + { + "runnable_procs": "2", + "uninterruptible_sleeping_procs": "0", + "virtual_mem_used": "0", + "free_mem": "2794468", + "buffer_mem": "2108", + "cache_mem": "741208", + "inactive_mem": null, + "active_mem": null, + "swap_in": "0", + "swap_out": "0", + "blocks_in": "1", + "blocks_out": "3", + "interrupts": "29", + "context_switches": "57", + "user_time": "0", + "system_time": "0", + "idle_time": "99", + "io_wait_time": "0", + "stolen_time": "0", + "timestamp": null, + "timezone": null + } + ] + + +## info +```python +info() +``` +Provides parser metadata (version, author, etc.) + +## 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: + + List of Dictionaries. Raw or processed structured data. + +## Parser Information +Compatibility: linux + +Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com) diff --git a/docs/parsers/vmstat_s.md b/docs/parsers/vmstat_s.md new file mode 100644 index 00000000..c7baafa5 --- /dev/null +++ b/docs/parsers/vmstat_s.md @@ -0,0 +1,105 @@ +[Home](https://kellyjonbrazil.github.io/jc/) + +# jc.parsers.vmstat_s +jc - JSON CLI output utility `vmstat` command output streaming parser + +Options supported: `-a`, `-w`, `-d`, `-t` + +Usage (cli): + + $ vmstat | jc --vmstat-s + +Usage (module): + + import jc.parsers.vmstat_s + result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines()) # result is an iterable object + for item in result: + # do something + +Schema: + + { + 'runnable_procs': integer, + 'uninterruptible_sleeping_procs': integer, + 'virtual_mem_used': integer, + 'free_mem': integer, + 'buffer_mem': integer, + 'cache_mem': integer, + 'inactive_mem': integer, + 'active_mem': integer, + 'swap_in': integer, + 'swap_out': integer, + 'blocks_in': integer, + 'blocks_out': integer, + 'interrupts': integer, + 'context_switches': integer, + 'user_time': integer, + 'system_time': integer, + 'idle_time': integer, + 'io_wait_time': integer, + 'stolen_time': integer, + 'disk': string, + 'total_reads': integer, + 'merged_reads': integer, + 'sectors_read': integer, + 'reading_ms': integer, + 'total_writes': integer, + 'merged_writes': integer, + 'sectors_written': integer, + 'writing_ms': integer, + 'current_io': integer, + 'io_seconds': integer, + 'timestamp': string, + 'timezone': string, + 'epoch': integer, # naive timestamp if -t flag is used + 'epoch_utc': integer # aware timestamp if -t flag is used and UTC TZ + "_meta": # This object only exists if using -q or quiet=True + { + "success": booean, # true if successfully parsed, false if error + "error": string, # exists if "success" is false + "line": string # exists if "success" is false + } + } + +Examples: + + $ vmstat | jc --vmstat-s + {"runnable_procs":2,"uninterruptible_sleeping_procs":0,"virtual_mem_used":0,"free_mem":2794468,"buffer_mem":2108,"cache_mem":741208,"inactive_mem":null,"active_mem":null,"swap_in":0,"swap_out":0,"blocks_in":1,"blocks_out":3,"interrupts":29,"context_switches":57,"user_time":0,"system_time":0,"idle_time":99,"io_wait_time":0,"stolen_time":0,"timestamp":null,"timezone":null} + ... + + $ vmstat | jc --vmstat-s -r + {"runnable_procs":"2","uninterruptible_sleeping_procs":"0","virtual_mem_used":"0","free_mem":"2794468","buffer_mem":"2108","cache_mem":"741208","inactive_mem":null,"active_mem":null,"swap_in":"0","swap_out":"0","blocks_in":"1","blocks_out":"3","interrupts":"29","context_switches":"57","user_time":"0","system_time":"0","idle_time":"99","io_wait_time":"0","stolen_time":"0","timestamp":null,"timezone":null} + ... + + +## info +```python +info() +``` +Provides parser metadata (version, author, etc.) + +## parse +```python +parse(data, raw=False, quiet=False) +``` + +Main text parsing generator function. Returns an iterator object. + +Parameters: + + data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True + quiet: (boolean) suppress warning messages and ignore parsing exceptions if True + +Yields: + + Dictionary. Raw or processed structured data. + +Returns: + + Iterator object + +## Parser Information +Compatibility: linux + +Version 0.5 by Kelly Brazil (kellyjonbrazil@gmail.com) diff --git a/jc/parsers/vmstat_s.py b/jc/parsers/vmstat_s.py index b12d1499..1320b334 100644 --- a/jc/parsers/vmstat_s.py +++ b/jc/parsers/vmstat_s.py @@ -50,6 +50,12 @@ Schema: 'timezone': string, 'epoch': integer, # naive timestamp if -t flag is used 'epoch_utc': integer # aware timestamp if -t flag is used and UTC TZ + "_meta": # This object only exists if using -q or quiet=True + { + "success": booean, # true if successfully parsed, false if error + "error": string, # exists if "success" is false + "line": string # exists if "success" is false + } } Examples: diff --git a/man/jc.1 b/man/jc.1 index 55e8fbc5..134119e9 100644 --- a/man/jc.1 +++ b/man/jc.1 @@ -1,4 +1,4 @@ -.TH jc 1 2021-09-21 1.17.0 "JSON CLI output utility" +.TH jc 1 2021-09-22 1.17.0 "JSON CLI output utility" .SH NAME jc \- JSONifies the output of many CLI tools and file-types .SH SYNOPSIS @@ -372,6 +372,16 @@ Key/Value file parser \fB--uptime\fP `uptime` command parser +.TP +.B +\fB--vmstat\fP +`vmstat` command parser + +.TP +.B +\fB--vmstat-s\fP +`vmstat` command streaming parser + .TP .B \fB--w\fP