Drop output parameter - replace with "verbosity" (#44)

Signed-off-by: Alok Joshi <aljoshi@nvidia.com>

Author: Alok-Joshi

nsight/__init__.py

@@ -5,8 +5,8 @@
 
 from nsight import analyze
 from nsight.annotation import annotate
-from nsight.utils import col_panel, row_panel
+from nsight.utils import VerbosityLevel, col_panel, row_panel
 
 __version__ = version("nsight-python")
 
-__all__ = ["analyze", "annotate"]
+__all__ = ["analyze", "annotate", "VerbosityLevel"]

nsight/analyze.py

@@ -16,6 +16,7 @@
 
 import nsight.collection as collection
 import nsight.visualization as visualization
+from nsight.utils import VerbosityLevel
 
 
 # Overload 1: When used without parentheses: @kernel
@@ -39,7 +40,7 @@ def kernel(
         | None
     ) = None,
     normalize_against: str | None = None,
-    output: Literal["quiet", "progress", "verbose"] = "progress",
+    verbosity: VerbosityLevel = VerbosityLevel.INFO,
     metrics: Sequence[str] = ["gpu__time_duration.sum"],
     ignore_kernel_list: Sequence[str] | None = None,
     clock_control: Literal["base", "none"] = "none",
@@ -68,7 +69,7 @@ def kernel(
         | None
     ) = None,
     normalize_against: str | None = None,
-    output: Literal["quiet", "progress", "verbose"] = "progress",
+    verbosity: VerbosityLevel = VerbosityLevel.INFO,
     metrics: Sequence[str] = ["gpu__time_duration.sum"],
     ignore_kernel_list: Sequence[str] | None = None,
     clock_control: Literal["base", "none"] = "none",
@@ -219,11 +220,14 @@ def wrapped_function(*args, configs=None, **kwargs) -> ProfileResults
         thermal_timeout: Maximum wait time in seconds for GPU to cool down.
             Default: 180 seconds
 
-        output: Controls the verbosity level of the output.
+        verbosity: Controls the verbosity level of the output. Selecting level N
+            enables output at all levels with value <= N. Default: ``VerbosityLevel.INFO``.
 
-            - ``"quiet"``: Suppresses all output.
-            - ``"progress"``: Shows a progress bar along with details about profiling and data extraction progress.
-            - ``"verbose"``: Displays the progress bar, configuration-specific logs, and profiler logs.
+            - ``VerbosityLevel.SILENT``: Suppresses all output.
+            - ``VerbosityLevel.INFO``: Shows a progress bar, profiling completion messages,
+              and report file paths.
+            - ``VerbosityLevel.DEBUG``: Adds configuration-specific logs, the full NCU CLI
+              command, and enables NCU verbose output.
 
         output_prefix: When specified, all intermediate profiler files are created with this prefix.
             For example, if `output_prefix="/home/user/run1_"`, the profiler will generate:
@@ -291,12 +295,6 @@ def wrapped_function(*args, configs=None, **kwargs) -> ProfileResults
 
     def _create_profiler() -> collection.core.NsightProfiler:
         """Helper to create the profiler with the given settings."""
-        if output not in ("quiet", "progress", "verbose"):
-            raise ValueError("output must be 'quiet', 'progress' or 'verbose'")
-
-        output_progress = output == "progress" or output == "verbose"
-        output_detailed = output == "verbose"
-
         # Create the output paths needed for the ncu report, ncu logs and the CSVs
         prefix = output_prefix
         if "NSPY_NCU_PROFILE" not in os.environ:
@@ -311,8 +309,7 @@ def _create_profiler() -> collection.core.NsightProfiler:
         settings = collection.core.ProfileSettings(
             configs=configs,
             runs=runs,
-            output_progress=output_progress,
-            output_detailed=output_detailed,
+            verbosity=verbosity,
             derive_metric=derive_metric,
             normalize_against=normalize_against,
             thermal_mode=thermal_mode,

nsight/collection/core.py

@@ -17,6 +17,7 @@
 import pandas as pd
 
 from nsight import annotation, exceptions, thermovision, transformation, utils
+from nsight.utils import VerbosityLevel
 
 
 def _get_regular_params(
@@ -235,15 +236,14 @@ def run_profile_session(
     func: Callable[..., None],
     configs: List[Sequence[Any]],
     runs: int,
-    output_progress: bool,
-    output_detailed: bool,
+    verbosity: VerbosityLevel,
     thermal_mode: Literal["auto", "manual", "off"],
     thermal_wait: int | None = None,
     thermal_cont: int | None = None,
     thermal_timeout: int | None = None,
 ) -> None:
 
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         print("")
         print("")
 
@@ -255,7 +255,7 @@ def run_profile_session(
             thermal_wait=thermal_wait,
             thermal_cont=thermal_cont,
             thermal_timeout=thermal_timeout,
-            verbose=output_detailed,
+            verbose=verbosity >= VerbosityLevel.DEBUG,
         )
         thermovision_initialized = thermal_controller.init()
         if not thermovision_initialized:
@@ -270,8 +270,8 @@ def run_profile_session(
     bar_length = 100
     progress_time: float = 0
 
-    # overwrite flag: we do not overwrite when output mode is detailed
-    overwrite_output = not output_detailed
+    # overwrite flag: we do not overwrite when output mode is debug
+    overwrite_output = verbosity < VerbosityLevel.DEBUG
     show_return_type_warning = False
     config_lengths: list[int] = list()
 
@@ -300,7 +300,7 @@ def run_profile_session(
 
         curr_config += 1
 
-        if output_progress:
+        if verbosity >= VerbosityLevel.INFO:
             utils.print_config(total_configs, curr_config, c, overwrite_output)
 
         for i in range(runs):
@@ -328,7 +328,7 @@ def run_profile_session(
 
             # Update time estimates every half second
             if time.time() - progress_time > 0.5:
-                if output_progress:
+                if verbosity >= VerbosityLevel.INFO:
                     utils.print_progress_bar(
                         total_runs,
                         curr_run,
@@ -339,7 +339,7 @@ def run_profile_session(
                 progress_time = time.time()
 
     # Update progress bar at end so it shows 100%
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         utils.print_progress_bar(
             total_runs,
             curr_run,
@@ -377,14 +377,10 @@ class ProfileSettings:
     runs: int
     """Number of times each configuration should be executed."""
 
-    output_progress: bool
+    verbosity: VerbosityLevel
     """
-    Will display a progress bar on stdout during profiling
-    """
-
-    output_detailed: bool
-    """
-    Will display a progress bar, detailed output for each config along with the profiler logs
+    Controls verbosity of output. SILENT suppresses all output, INFO shows progress bar,
+    DEBUG shows progress bar plus per-config logs and profiler output.
     """
 
     derive_metric: (
@@ -596,7 +592,7 @@ def wrapper(
                     raw_df,
                     func,
                     self.settings.normalize_against,
-                    self.settings.output_progress,
+                    self.settings.verbosity,
                 )
 
                 # Save to CSV if enabled
@@ -617,7 +613,7 @@ def wrapper(
                         index=False,
                     )
 
-                    if self.settings.output_progress:
+                    if self.settings.verbosity >= VerbosityLevel.INFO:
                         print(
                             f"[NSIGHT-PYTHON] Refer to {raw_csv_path} for the raw profiling data"
                         )

nsight/collection/ncu.py

@@ -21,6 +21,7 @@
 from nsight import exceptions, extraction, utils
 from nsight.collection import core
 from nsight.exceptions import NCUErrorContext
+from nsight.utils import VerbosityLevel
 
 
 def get_signature(
@@ -40,7 +41,7 @@ def launch_ncu(
     cache_control: Literal["none", "all"],
     clock_control: Literal["none", "base"],
     replay_mode: Literal["kernel", "range"],
-    verbose: bool,
+    verbosity: VerbosityLevel,
 ) -> str | None:
     """
     Launch NVIDIA Nsight Compute to profile the current script with specified options.
@@ -51,7 +52,7 @@ def launch_ncu(
         cache_control: Select cache control option
         clock_control: Select clock control option
         replay_mode: Select replay mode option
-        verbose: If False, log is written to a file (ncu_log.txt)
+        verbosity: Controls output verbosity level.
 
     Raises:
         NCUNotAvailableError: If NCU is not available on the system.
@@ -84,11 +85,16 @@ def launch_ncu(
     replay = f"--replay-mode {replay_mode}"
     log_path = os.path.splitext(report_path)[0] + ".log"
     log = f"--log-file {log_path}"
+
     nvtx = f'--nvtx --nvtx-include "regex:{utils.NVTX_DOMAIN}@.+/"'
     metrics_str = ",".join(metrics)
+    verbose_flag = "--verbose" if verbosity >= VerbosityLevel.DEBUG else ""
 
     # Construct the ncu command
-    ncu_command = f"""ncu {log} {cache} {clocks} {replay} {nvtx} --metrics {metrics_str} -f -o {report_path} {sys.executable} {script_path} {script_args}"""
+    ncu_command = f"""ncu {log} {cache} {clocks} {replay} {nvtx} {verbose_flag} --metrics {metrics_str} -f -o {report_path} {sys.executable} {script_path} {script_args}"""
+
+    if verbosity >= VerbosityLevel.DEBUG:
+        print(f"[NSIGHT-PYTHON] NCU command: {ncu_command}")
 
     # Check if ncu is available on the system
     ncu_available = False
@@ -113,19 +119,16 @@ def launch_ncu(
             )
 
             return log_path
-        except subprocess.CalledProcessError as e:
+        except subprocess.CalledProcessError:
             log_parser = utils.NCULogParser()
             error_logs = log_parser.get_logs(log_path, "ERROR")
-
-            # Create error context
-            error_context = NCUErrorContext(
-                errors=error_logs,
-                log_file_path=log_path,
-                metrics=metrics,
-            )
-
-            error_message = utils.format_ncu_error_message(error_context)
-            raise exceptions.ProfilerException(error_message) from None
+            raise exceptions.ProfilerException(
+                utils.format_ncu_error_message(
+                    NCUErrorContext(
+                        errors=error_logs, log_file_path=log_path, metrics=metrics
+                    )
+                )
+            ) from None
     else:
         subprocess.run([sys.executable, script_path], env=env)
         raise exceptions.NCUNotAvailableError(
@@ -230,10 +233,10 @@ def collect(
                 self.cache_control,
                 self.clock_control,
                 self.replay_mode,
-                settings.output_detailed,
+                settings.verbosity,
             )
 
-            if settings.output_progress:
+            if settings.verbosity >= VerbosityLevel.INFO:
                 print("[NSIGHT-PYTHON] Profiling completed successfully !")
                 print(
                     f"[NSIGHT-PYTHON] Refer to {report_path} for the NVIDIA Nsight Compute CLI report"
@@ -250,7 +253,7 @@ def collect(
                 func,
                 settings.derive_metric,
                 self.ignore_kernel_list,  # type: ignore[arg-type]
-                settings.output_progress,
+                settings.verbosity,
                 self.combine_kernel_metrics,
             )
 
@@ -264,7 +267,7 @@ def collect(
             if get_signature(func, configs_list) != sig:
                 return None
 
-            if settings.output_progress:
+            if settings.verbosity >= VerbosityLevel.INFO:
                 utils.print_header(
                     f"Profiling {func.__name__}",
                     f"{len(configs_list)} configurations, {settings.runs} runs each",
@@ -274,8 +277,7 @@ def collect(
                 func,
                 configs_list,
                 settings.runs,
-                settings.output_progress,
-                settings.output_detailed,
+                settings.verbosity,
                 settings.thermal_mode,
                 settings.thermal_wait,
                 settings.thermal_cont,

nsight/extraction.py

@@ -11,7 +11,7 @@
     extract_ncu_action_data(action, metrics):
         Extracts performance data for a specific kernel action from an NVIDIA Nsight Compute report.
 
-    extract_df_from_report(report_path, metrics, configs, iterations, func, derive_metric, ignore_kernel_list, output_progress, combine_kernel_metrics=None):
+    extract_df_from_report(report_path, metrics, configs, iterations, func, derive_metric, ignore_kernel_list, verbosity, combine_kernel_metrics=None):
         Processes the full NVIDIA Nsight Compute report and returns a pandas DataFrame containing performance metrics.
 """
 
@@ -27,7 +27,7 @@
 import pandas as pd
 
 from nsight import exceptions, utils
-from nsight.utils import is_scalar
+from nsight.utils import VerbosityLevel, is_scalar
 
 DerivedValue: TypeAlias = float | int | None
 DerivedValueWithUnit: TypeAlias = tuple[DerivedValue, str]
@@ -84,7 +84,7 @@ def extract_df_from_report(
     func: Callable[..., Any],
     derive_metric: Callable[..., Any] | None,
     ignore_kernel_list: List[str] | None,
-    output_progress: bool,
+    verbosity: VerbosityLevel,
     combine_kernel_metrics: Callable[[float, float], float] | None = None,
 ) -> pd.DataFrame:
     """
@@ -108,13 +108,13 @@ def extract_df_from_report(
         RuntimeError: If multiple kernels are detected per config without a combining function.
         exceptions.ProfilerException: If profiling results are missing or incomplete.
     """
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         print("[NSIGHT-PYTHON] Loading profiled data")
     try:
         report: ncu_report.IContext = ncu_report.load_report(report_path)
     except FileNotFoundError:
         raise exceptions.ProfilerException(
-            "No NVIDIA Nsight Compute report found. Please run nsight-python with `@nsight.analyze.kernel(output='verbose')`"
+            "No NVIDIA Nsight Compute report found. Please run nsight-python with `@nsight.analyze.kernel(verbosity=nsight.VerbosityLevel.DEBUG)`"
             "to identify the issue."
         )
 
@@ -144,7 +144,7 @@ def extract_df_from_report(
     }
 
     # Extract all profiling data
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         print(f"Extracting profiling data")
     profiling_data: dict[str, list[utils.NCUActionData]] = {}
     for range_idx in range(report.num_ranges()):
@@ -171,7 +171,7 @@ def extract_df_from_report(
                 profiling_data[annotation].append(data)
 
     for annotation, annotation_data in profiling_data.items():
-        if output_progress:
+        if verbosity >= VerbosityLevel.INFO:
             print(f"Extracting {annotation} profiling data")
 
         configs_repeated = [

nsight/transformation.py

@@ -15,12 +15,14 @@
 import numpy as np
 import pandas as pd
 
+from nsight.utils import VerbosityLevel
+
 
 def aggregate_data(
     df: pd.DataFrame,
     func: Callable[..., Any],
     normalize_against: str | None,
-    output_progress: bool,
+    verbosity: VerbosityLevel,
 ) -> pd.DataFrame:
     """
     Groups and aggregates profiling data by configuration and annotation.
@@ -29,12 +31,12 @@ def aggregate_data(
         df: The raw profiling results.
         func: Function representing kernel configuration parameters.
         normalize_against: Name of the annotation to normalize against.
-        output_progress: Toggles the display of data processing logs
+        verbosity: Controls display of data processing logs
 
     Returns:
         Aggregated DataFrame and the (possibly normalized) metric name.
     """
-    if output_progress:
+    if verbosity >= VerbosityLevel.INFO:
         print("[NSIGHT-PYTHON] Processing profiled data")
 
     # Get the number of arguments in the signature of func (exclude *args/**kwargs)