From c1e1c529ca12fbfe07c5fef65623926615b2b0b5 Mon Sep 17 00:00:00 2001 From: David Schweikert Date: Thu, 18 Dec 2025 18:04:37 +0100 Subject: [PATCH] JSON documentation: reformat --- CHANGELOG.md | 6 ++-- doc/fping-json.md | 82 +++++++++++++++++++++++++---------------------- 2 files changed, 48 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0825152..6cf6f11 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,10 @@ Next ## New features -- New option -J / --json for the JSON output (#386, thanks @bonkf, - @JoshIPT, @sebast-gsnw and @auerswal) +- New option -J / --json for JSON output. See doc/fping-json.md for + the JSON schema. This feature is still in alpha and the schema + might change in future releases (#386, thanks @bonkf, + @JoshIPT, @sebast-gsnw, and @auerswal). - The -g, --generate option now also supports IPv6 addresses (#376, thanks @auerswal) - New option --seqmap-timeout to control the time after which sequence diff --git a/doc/fping-json.md b/doc/fping-json.md index 07172ce..e03d5a9 100644 --- a/doc/fping-json.md +++ b/doc/fping-json.md @@ -1,10 +1,13 @@ # fping JSON Output Format + last updated for: fping 5.5 -> [!IMPORTANT] -> The JSON output feature is currently in **alpha**. The format is subject to change in future versions. +> [!IMPORTANT] The JSON output feature is currently in **alpha**. The format is +> subject to change in future versions. -When using the `--json` (or `-J`) option, fping outputs results as a **stream of JSON objects**, separated by newlines. Each line in the output is a valid, independent JSON document representing a specific event or statistic. +When using the `--json` (or `-J`) option, fping outputs results as a **stream of +JSON objects**, separated by newlines. Each line in the output is a valid, +independent JSON document representing a specific event or statistic. ## General Format @@ -14,11 +17,14 @@ Every JSON object output by fping follows the following pattern: { "type": { "field1": "value1", "field2": "value2" } } ``` -Where `type` identifies the type of the object (e.g., `resp`, `summary`) and the inner object contains the fields relevant to that type. +Where `type` identifies the type of the object (e.g., `resp`, `summary`) and the +inner object contains the fields relevant to that type. ## Forward Compatibility -Any unknown object types and any unknown fields should be ignored for forward-compatibility (we might add new objects and fields to objects over time). +Any unknown object types and any unknown fields should be ignored for +forward-compatibility (we might add new objects and fields to objects over +time). ## Example @@ -34,17 +40,19 @@ $ fping -J -c3 8.8.8.8 ## JSON Object Types -> [!NOTE] -> In the actual output, each JSON object is compacted onto a single line. The examples in this document are formatted across multiple lines for readability. +> [!NOTE] In the actual output, each JSON object is compacted onto a single +> line. The examples in this document are formatted across multiple lines for +> readability. -The following top-level keys identify the type of information contained in each JSON object: +The following top-level keys identify the type of information contained in each +JSON object: -* `resp`: Response to a ping packet. -* `timeout`: Timeout waiting for a packet response. -* `summary`: Summary statistics for a host (used with `-c`). -* `vSum`: Summary of all RTT values for a host (used with `-C`). -* `globalSum`: Global statistics for the entire run (used with `-s`). -* `intSum`: Interval summary statistics (used with `-Q`). +- `resp`: Response to a ping packet. +- `timeout`: Timeout waiting for a packet response. +- `summary`: Summary statistics for a host (used with `-c`). +- `vSum`: Summary of all RTT values for a host (used with `-C`). +- `globalSum`: Global statistics for the entire run (used with `-s`). +- `intSum`: Interval summary statistics (used with `-Q`). ### `resp`: Response @@ -61,16 +69,17 @@ Generated when a ping reply is received. } ``` -* `host`: Target hostname or IP. -* `seq`: Sequence number of the packet (0-indexed). -* `size`: Size of the received packet in bytes. -* `rtt`: Round-trip time in milliseconds. +- `host`: Target hostname or IP. +- `seq`: Sequence number of the packet (0-indexed). +- `size`: Size of the received packet in bytes. +- `rtt`: Round-trip time in milliseconds. **Optional Fields:** -* `timestamps`: If ICMP timestamp requests are used (`--icmp-timestamp`), contains `originate`, `receive`, `transmit`, and `localreceive` timestamps. -* `tos`: If `--print-tos` is used, contains the Type of Service value. -* `ttl`: If `--print-ttl` is used, contains the Time To Live value. +- `timestamps`: If ICMP timestamp requests are used (`--icmp-timestamp`), + contains `originate`, `receive`, `transmit`, and `localreceive` timestamps. +- `tos`: If `--print-tos` is used, contains the Type of Service value. +- `ttl`: If `--print-ttl` is used, contains the Time To Live value. ### `timeout`: Timeout @@ -85,8 +94,8 @@ Generated when a packet times out. } ``` -* `host`: Target hostname or IP. -* `seq`: Sequence number of the timed-out packet. +- `host`: Target hostname or IP. +- `seq`: Sequence number of the timed-out packet. ### `summary`: Host Summary @@ -107,31 +116,28 @@ Generated at end of execution (or interval) when using `-c` (count mode). } ``` -* `xmt`: Packets transmitted. -* `rcv`: Packets received. -* `loss`: Packet loss percentage. -* `outage(ms)`: Total outage time in milliseconds (only if `--outage` is used). -* `rttMin`, `rttAvg`, `rttMax`: Minimum, average, and maximum RTTs. +- `xmt`: Packets transmitted. +- `rcv`: Packets received. +- `loss`: Packet loss percentage. +- `outage(ms)`: Total outage time in milliseconds (only if `--outage` is used). +- `rttMin`, `rttAvg`, `rttMax`: Minimum, average, and maximum RTTs. ### `vSum`: Full RTT Summary -Generated at end of execution when using `-C` (count mode with per-packet RTT reporting). +Generated at end of execution when using `-C` (count mode with per-packet RTT +reporting). ```json { "vSum": { "host": "127.0.0.1", - "values": [ - 0.054, - 0.062, - null, - 0.081 - ] + "values": [0.054, 0.062, null, 0.081] } } ``` -* `values`: Array of RTT values (in ms) for each sequence number. `null` indicates a timeout/loss. +- `values`: Array of RTT values (in ms) for each sequence number. `null` + indicates a timeout/loss. ### `intSum`: Interval Summary @@ -152,8 +158,8 @@ Generated periodically when using `-Q` (quiet with interval reporting). } ``` -* `time`: Unix timestamp of the report. -* Other fields are similar to `summary`. +- `time`: Unix timestamp of the report. +- Other fields are similar to `summary`. ### `globalSum`: Global Summary -- 2.43.0