Document that annotations must launch the same number of kernels

Add a known issue and note it in the combine_kernel_metrics docstring.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Alok Joshi <aljoshi@nvidia.com>

Author: Alok-Joshi

docs/source/release_notes/known_issues.rst

@@ -9,3 +9,4 @@ Known Issues
 - Nested annotations (using ``nsight.annotate`` within another ``nsight.annotate`` context) are not supported. nsight-python errors out when nested annotations are used.
 - ``*args`` and ``**kwargs`` in decorated function signatures are tolerated but ignored — they will always be empty and will not appear in the profiling output.
 - Calling :func:`@nsight.analyze.kernel <nsight.analyze.kernel>`-decorated functions from multiple threads is not supported, whether the threads run sequentially or concurrently.
+- Each annotation must launch the same number of kernels across configurations and repeated runs, even with ``combine_kernel_metrics``. Different counts may cause an error or incorrect results. Profile configurations separately when their kernel counts differ.

nsight/analyze.py

@@ -201,7 +201,9 @@ def wrapped_function(*args, configs=None, **kwargs) -> ProfileResults
             how to summarize the collected metrics into a single number. For example,
             if we profile runtime and want to sum the times of all kernels we can specify
             ``combine_kernel_metrics = lambda x, y: x + y``. The function should take
-            two arguments and return a single value. Default: ``None``.
+            two arguments and return a single value. Each annotation must still launch
+            the same number of kernels across configurations and repeated runs;
+            different counts may cause an error or incorrect results. Default: ``None``.
         clock_control: Control the behavior of the GPU clocks during profiling. Allowed values:
 
             - ``"base"``: GPC and memory clocks are locked to their respective base frequency during profiling. This has no impact on thermal throttling. Note that actual clocks might still vary, depending on the level of driver support for this feature. As an alternative, use nvidia-smi to lock the clocks externally and set this option to ``"none"``.