ziomon/ziorep_utilization: introduce parameter for reports separation

The output of ziorep_utilization tool currently contains reports for both
the physical and the virtual adapter. As binding of physical and virtual
adapter reports together can be confusing for evaluation of results, introduce
--fcp-device tool parameter for reports separation. This parameter was
introduced to mark virtual adapter report as it represents utilization report
of FCP devices.

So, if --fcp-device was specified by the user, virtual adapter report is
printed. Otherwise physical adapter report is printed.

Parameter --fcp-device has no influence on CSV format report printing.

Refactor also print_reports() function for both reports for better
--fcp-device parameter handling.

Add clarification messages on how to use --fcp-device parameter.

Delete empty separator line between former two reports.

Add description of --fcp-device parameter to man pages.

Add examples for using of ziorep_utilization tool to man pages.

Signed-off-by: Fedor Loshakov <loshakov@linux.ibm.com>
Reviewed-by: Benjamin Block <bblock@linux.ibm.com>
Reviewed-by: Sakshi Singh <005c7w@linux.ibm.com>
Reviewed-by: M Nikhil <nikh1092@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>

ziomon/ziorep_utilization.8

@@ -1,4 +1,4 @@
-.\" Copyright 2017 IBM Corp.
+.\" Copyright 2024 IBM Corp.
 .\" s390-tools is free software; you can redistribute it and/or modify
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
@@ -58,6 +58,15 @@ Print a summary of the data, then exit.
 Only consider the specified physical adapter. Adapters must be specified in hex.
 If multiple adapters should be specified, specify each one separately.
 
+.TP
+.BR "\-f" " or " "\-\-fcp-device"
+Print a utilization report for an FCP device. If this option is specified, then
+a virtual adapter report is printed, otherwise a physical adapter report with FCP
+channel scope is printed. This parameter has no influence on CSV format report printing.
+Using the --export-csv option causes both physical and virtual adapter utilization
+reports to be printed into two separate CSV-formatted files independent of the
+--fcp-device parameter.
+
 .TP
 .BR "\-x" " or " "\-\-export-csv"
 Write data to file(s) in CSV format. Output filenames will be based on the data filename.
@@ -127,14 +136,23 @@ give the values for read and write requests respectively.
 
 
 .SH EXAMPLES
-Print a utilization report using
+Print a physical adapter utilization report only using
 .IR sample.log
 , considering adapters 4e and 4f only.
-Only data between 8:57 April 5, 2008, and 17:09 June 21, 2008, should be considered.
+Only data between 8:57 April 5, 2024, and 17:09 June 21, 2024, should be considered.
 Data should be aggregated to 60 second intervals.
 
-ziorep_utilization -c 4e -c 4f -i 60 -b "2008-04-05 08:57" -e "2008-06-21 17:09"
+ziorep_utilization sample.log -c 4e -c 4f -i 60 -b "2024-04-05 08:57" -e "2024-06-21 17:09"
 
+Print virtual adapter report only using sample.log. Consider adapter 4f only. Data should be
+aggregated to 3 seconds interval. Print topline after every 2nd frame.
+
+ziorep_utilization sample.log -c 4f -i 3 -t 2 --fcp-device
+
+Print both physical and virtual adapter reports using sample.log in two separate CSV-formatted
+files with the default interval. Considering adapter 4f only. Print topline after every 2nd frame.
+
+ziorep_utilization sample.log -c 4f -t 2 --export-csv
 
 .SH "SEE ALSO"
 .BR ziorep_config (8),

ziomon/ziorep_utilization.cpp

@@ -3,7 +3,7 @@
  *
  * Utilization report program
  *
- * Copyright IBM Corp. 2008, 2017
+ * Copyright IBM Corp. 2008, 2024
  *
  * s390-tools is free software; you can redistribute it and/or modify
  * it under the terms of the MIT license. See LICENSE for details.
@@ -49,6 +49,7 @@ struct options {
 	char*		filename;
 	bool		print_summary;
 	bool		csv_export;
+	bool		fcp_device;
 };
 
 
@@ -61,6 +62,7 @@ static void init_opts(struct options *opts)
 	opts->filename		= NULL;
 	opts->print_summary	= false;
 	opts->csv_export	= false;
+	opts->fcp_device	= false;
 }
 
 
@@ -85,6 +87,8 @@ static const char help_text[] =
     "-s, --summary           Show a summary of the data.\n"
     "-c, --chpid <chpid>     Select physical adapter in hex.\n"
     "                        E.g. '-c 32a'\n"
+    "-f, --fcp-device        Print utilization report for FCP device scope.\n"
+    "                        Otherwise for FCP channel scope.\n"
     "-x, --export-csv        Export data to files in CSV format.\n"
     "-t, --topline <num>     Repeat topline after every 'num' frames.\n"
     "                        0 for no repeat (default).\n";
@@ -99,7 +103,7 @@ static void print_help()
 static void print_version()
 {
         printf("%s: Utilization report generator version %s\n"
-               "Copyright IBM Corp. 2008, 2017\n", toolname, RELEASE_STRING);
+               "Copyright IBM Corp. 2008, 2024\n", toolname, RELEASE_STRING);
 }
 
 
@@ -121,6 +125,7 @@ static int parse_params(int argc, char **argv, struct options *opts)
 		{ "chpid",           required_argument, NULL, 'c'},
 		{ "export-csv",      no_argument,       NULL, 'x'},
 		{ "topline",         required_argument, NULL, 't'},
+		{ "fcp-device",      no_argument,       NULL, 'f'},
                 { 0,                 0,                 0,     0 }
 	};
 
@@ -130,7 +135,7 @@ static int parse_params(int argc, char **argv, struct options *opts)
 	}
 
 	assert(sizeof(long long int) == sizeof(__u64));
-	while ((c = getopt_long(argc, argv, "b:e:i:c:t:xshvV",
+	while ((c = getopt_long(argc, argv, "b:e:i:c:t:xshvVf",
 				long_options, &index)) != EOF) {
 		switch (c) {
 		case 'V':
@@ -183,6 +188,9 @@ static int parse_params(int argc, char **argv, struct options *opts)
 			if (parse_topline_arg(optarg, &opts->topline))
 				return -1;
 			break;
+		case 'f':
+			opts->fcp_device = true;
+			break;
 		default:
 			fprintf(stderr, "%s: Try '%s --help' for"
 				" more information.\n", toolname, toolname);
@@ -297,43 +305,65 @@ static int print_reports(struct options *opts, ConfigReader &cfg)
 
 	type_flt.push_back(utilization);
 
+	// physical adapter report
 	if (opts->csv_export) {
 		fp = open_csv_output_file(opts->filename,
 					  "_util_phys_adpt.csv", &rc);
 		if (!fp)
 			goto out;
-	}
+	} else {
-	else
 		fp = stdout;
-
-	if ( (rc = print_report(fp, opts->begin, opts->end,
-				opts->interval, opts->filename, opts->topline,
-				&type_flt, dev_filt, noop_col,
-				physPrnt)) < 0 ) {
-		rc = -3;
-		goto out1;
 	}
 
-	if (rc == 0)
+	if (!opts->fcp_device || opts->csv_export) {
-		fprintf(stderr, "%s: No eligible data found.\n", toolname);
+		rc = print_report(fp, opts->begin, opts->end,
+				  opts->interval, opts->filename, opts->topline,
+				  &type_flt, dev_filt, noop_col, physPrnt);
+		if (rc < 0) {
+			rc = -3;
+			goto out1;
+		} else if (rc == 0) {
+			fprintf(stderr, "%s: No eligible data found.\n",
+				toolname);
+		}
 
+		if (!opts->csv_export)
+			fprintf(stderr,
+				"%s: The FCP channel utilization report was "
+				"printed. To print the FCP device utilization "
+				"report, use the -f/--fcp-device option.\n",
+				toolname);
+	}
+
+	// virtual adapter report
 	if (opts->csv_export) {
 		fclose(fp);
 		fp = open_csv_output_file(opts->filename,
 					  "_util_virt_adpt.csv", &rc);
 		if (!fp)
 			goto out;
-	}
+	} else {
-	else {
 		fp = stdout;
-		fputc('\n', fp);
 	}
 
-	if (print_report(fp, opts->begin, opts->end, opts->interval,
+	if (opts->fcp_device || opts->csv_export) {
-			 opts->filename, opts->topline, NULL, dev_filt,
+		rc = print_report(fp, opts->begin, opts->end, opts->interval,
-			 *col, virtPrnt)) {
+				  opts->filename, opts->topline, NULL, dev_filt,
-		rc = -4;
+				  *col, virtPrnt);
-		goto out1;
+		if (rc < 0) {
+			rc = -4;
+			goto out1;
+		} else if (rc == 0) {
+			fprintf(stderr, "%s: No eligible data found.\n",
+				toolname);
+		}
+
+		if (!opts->csv_export)
+			fprintf(stderr,
+				"%s: The FCP device utilization report was "
+				"printed. To print the FCP channel utilization "
+				"report, omit the -f/--fcp-device option.\n",
+				toolname);
 	}
 
 out1: