Add Ability To Get Full JSON Result Object With Streams Enabled

[manedurphy]

PLEASE NOTE the following text from the iperf3 license. Submitting a
pull request to the iperf3 repository constitutes "[making]
Enhancements available...publicly":

You are under no obligation whatsoever to provide any bug fixes, patches, or
upgrades to the features, functionality or performance of the source code
("Enhancements") to anyone; however, if you choose to make your Enhancements
available either publicly, or directly to Lawrence Berkeley National
Laboratory, without imposing a separate written license agreement for such
Enhancements, then you hereby grant the following license: a non-exclusive,
royalty-free perpetual license to install, use, modify, prepare derivative
works, incorporate into other computer software, distribute, and sublicense
such enhancements or derivative works thereof, in binary and source code form.

The complete iperf3 license is available in the LICENSE file in the
top directory of the iperf3 source tree.

• Version of iperf3 (or development branch, such as master or
  3.1-STABLE) to which this pull request applies: master

• Issues fixed (if any):

  • JSON stream feature iperf/#1098
  • The issue is that the implementation assumes that if the user wants to leverage real-time events that they don't have any interest in the full JSON result object.
  • This change allows the user to both acquire real-time events as well as the full result object at the end of the measurement.

• Brief description of code changes (suitable for use as a commit message):

  • The iperf3 command line user can leverage the --json-stream-full-output flag in addition to the --json-stream to get both real-time events as well as the full JSON result at the end of a bandwidth measurement.
  • The libiperf user can use the iperf_set_test_json_stream_full_output API to ensure that a full JSON result object is available at the end of a bandwidth measurement. From the snippet below, the developer can expect that stream events will be printed as well as the full result at the end when iperf_get_test_json_output_string is called.

#include <iostream>
#include <iperf_api.h>

int main()
{
    struct iperf_test *test = iperf_new_test();
    iperf_defaults(test);
    iperf_set_test_role(test, 'c');
    iperf_set_test_server_hostname(test, "127.0.0.1");
    iperf_set_test_server_port(test, 5201);
    iperf_set_test_rate(test, 15000000);
    iperf_set_test_json_output(test, 1);
    iperf_set_test_json_stream(test, 1);
    iperf_set_test_json_stream_full_output(test, 1);
    iperf_run_client(test);

    char *result_json = iperf_get_test_json_output_string(test);
    printf("Result JSON: %s\n", result_json);
    return EXIT_SUCCESS;
}

[bmah888]

Thanks for the PR! Does this new option preserve the existing behavior of --json and --json-stream?

[manedurphy]

@bmah888 it does preserve existing behavior to ensure this note stays true: This avoids unneeded memory build up for long sessions. The users who opt in for the full result will have to do so knowing that memory will build up as the object grows, which is fine for our team's use case since our measurements sit between 30-60 seconds.

[bmah888]

This PR looks pretty reasonable and I'm planning on merging this soon. I'm trying to understand the interactions between --json, --json-stream, and --json-stream-full. So far I've come up with:

--json     --json-stream     --json-stream-full  :  Human-readable   Stream-JSON   End-JSON
no         no                no                     yes              no            no
no         no                yes                    yes              no            no
no         yes               no                     no               yes           no
no         yes               yes                    no               yes           yes
yes        no                no                     no               no            yes
yes        no                yes                    no               no            yes
yes        yes               no                     no               yes           no
yes        yes               yes                    no               yes           yes

--json-stream overrides --json. If --json-stream-full is given in addition, it also adds the original JSON output.

If --json is given but not --json-stream, the original end-of-test output is shown (only). --json-stream-full, if given, is ignored.

If neither --json nor --json-stream is specified, then the human-readable output is shown. --json-stream-full, if given, is ignored.

[manedurphy]

@bmah888 your table is correct. I'm not sure that the varying combinations of these flags are as intuitive as they could be just by reading, but a few trial-and-error tests covers all the cases you've shown in the table here. If I was building this from scratch, I think I would have made --json produce the full output, --json-stream produce the streamed output, and a combination of --json --json-stream to mean both, but that change would break existing functionality now so I opted for a new flag.

[bmah888]

Thanks @manedurphy, I think the functionality of the new flag you added is fine, and we should maybe have thought a little more about -json-stream before it was merged.

So I'm going to merge your patch as-is right now, and then I'm going to maybe make up a few sentences of documentation to add to the manpage to explain the interaction between the various JSON flags. Thanks!

Historical note: At one point (2015-ish), we were considering trying to make JSON the only native output format, and then having a post-processor either pass that through or render that in a human-readable form. But I don't think we could have done that without some major changes to the original --json functionality.

(Note for anyone reading this in 2025 or later, there is no plan to do this within the existing iperf3 code base, so please don't send in a PR unsolicited, even if you have a super-clever way to do this.)

[bmah888]

Approved, thanks!