1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Installation Guide — nsight-systems 2023.4 documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/design-style.b7bb847fb20b106c3d81b95245e65545.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/omni-style.css" type="text/css" />
<link rel="stylesheet" href="../_static/api-styles.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/mermaid-init.js"></script>
<script src="../_static/design-tabs.js"></script>
<script src="../_static/version.js"></script>
<script src="../_static/social-media.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="User Guide" href="../UserGuide/index.html" />
<link rel="prev" title="Release Notes" href="../ReleaseNotes/index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html">
<img src="../_static/devzone.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../ReleaseNotes/index.html">Release Notes</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="#system-requirements">System Requirements</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#supported-platforms">Supported Platforms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cuda-version">CUDA Version</a></li>
<li class="toctree-l3"><a class="reference internal" href="#requirements-for-x86-64-power-and-arm-sbsa-targets-on-linux">Requirements for x86_64, Power, and Arm SBSA Targets on Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="#x86-64-windows-target-device-requirements">x86_64 Windows Target Device Requirements</a></li>
<li class="toctree-l3"><a class="reference internal" href="#host-application-requirements">Host Application Requirements</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#getting-started-guide">Getting Started Guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#finding-the-right-package">Finding the Right Package</a></li>
<li class="toctree-l3"><a class="reference internal" href="#installing-gui-on-the-host-system">Installing GUI on the Host System</a></li>
<li class="toctree-l3"><a class="reference internal" href="#optional-setting-up-the-cli">Optional: Setting up the CLI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#launching-the-gui">Launching the GUI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#installing-multi-report-analysis-system">Installing Multi Report Analysis System</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../UserGuide/index.html">User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../CopyrightAndLicenses/index.html">Copyright and Licenses</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Archives</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../Archives/index.html">Archives</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">nsight-systems</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> »</li>
<li>Installation Guide</li>
<li class="wy-breadcrumbs-aside">
</li>
<li class="wy-breadcrumbs-aside">
<span>v2023.4 |</span>
<a href="https://developer.nvidia.com/nsight-systems/" class="reference external">Archive</a>
<span> </span>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="installation-guide">
<h1>Installation Guide<a class="headerlink" href="#installation-guide" title="Permalink to this heading"></a></h1>
<p>NVIDIA Nsight Systems installation guide.</p>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this heading"></a></h2>
<p>Nsight Systems is a statistical sampling profiler with tracing features. It is designed to work with devices and devkits based on NVIDIA Tegra SoCs (system-on-chip), Arm SBSA (server based system architecture) systems, IBM Power systems, and systems based on the x86_64 processor architecture that also include NVIDIA GPU(s).</p>
<p>Throughout this document we will refer to the device on which profiling happens as the <strong>target</strong>, and the computer on which the user works and controls the profiling session as the <strong>host</strong>. Note that for x86_64 based systems these may be on the same device, whereas with Tegra, Arm, or IBM Power based systems they will always be separate.</p>
<p>Furthermore, three different activities are distinguished as follows:</p>
<ul class="simple">
<li><p><strong>Profiling</strong> — The process of collecting any performance data. A profiling session in Nsight Systems typically includes sampling and tracing.</p></li>
<li><p><strong>Sampling</strong> — The process of periodically stopping the <em>profilee</em> (the application under investigation during the profiling session), typically to collect backtraces (call stacks of active threads), which allows you to understand statistically how much time is spent in each function. Additionally, hardware counters can also be sampled. This process is inherently imprecise when a low number of samples have been collected.</p></li>
<li><p><strong>Tracing</strong> — The process of collecting precise information about various activities happening in the profilee or in the system. For example, profilee API execution may be traced providing the exact time and duration of a function call.</p></li>
</ul>
<p>Nsight Systems supports multiple generations of Tegra SoCs, NVIDIA discrete GPUs, and various CPU architectures, as well as various target and host operating systems. This documentation describes the full set of features available in any version of Nsight Systems. In the event that a feature is not available in all versions, that will be noted in the text. In general, Nsight Systems Embedded Platforms Edition indicates the package that supports Tegra processors for the embedded and automotive market and Nsight Systems Workstation Edition supports x86_64, IBM Power, and Arm server (SBSA) processors for the workstation and cluster market.</p>
<p>Common features that are supported by Nsight Systems on most platforms include the following:</p>
<ul class="simple">
<li><p>Sampling of the profilee and collecting backtraces using multiple algorithms (such as frame pointers or DWARF data). Building top-down, bottom-up, and flat views as appropriate. This information helps identify performance bottlenecks in CPU-intensive code.</p></li>
<li><p>Sampling or tracing system power behaviors, such as CPU frequency.</p></li>
<li><p>(Only on Nsight Systems Embedded Platforms Edition)Sampling counters from Arm PMU (Performance Monitoring Unit). Information such as cache misses gets statistically correlated with function execution.</p></li>
<li><p>Support for multiple windows. Users with multiple monitors can see multiple reports simultaneously, or have multiple views into the same report file.</p></li>
</ul>
<p>With Nsight Systems, a user could:</p>
<ul class="simple">
<li><p>Identify call paths that monopolize the CPU.</p></li>
<li><p>Identify individual functions that monopolize the CPU (across different call paths).</p></li>
<li><p>For Nsight Systems Embedded Platforms Edition, identify functions that have poor cache utilization.</p></li>
<li><p>If platform supports CUDA, see visual representation of CUDA Runtime and Driver API calls, as well as CUDA GPU workload. Nsight Systems uses the CUDA Profiling Tools Interface (CUPTI), for more information, see: <a class="reference external" href="https://docs.nvidia.com/cuda/cupti/index.html">CUPTI documentation</a>.</p></li>
<li><p>If the user annotates with NVIDIA Tools Extension (NVTX), see visual representation of NVTX annotations: ranges, markers, and thread names.</p></li>
<li><p>For Windows targets, see visual representation of D3D12: which API calls are being made on the CPU, graphic frames, stutter analysis, as well as GPU workloads (command lists and debug ranges).</p></li>
<li><p>For x86_64 targets, see visual representation of Vulkan: which API calls are being made on the CPU, graphic frames, stutter analysis, as well as Vulkan GPU workloads (command buffers and debug ranges).</p></li>
</ul>
</section>
<section id="system-requirements">
<h2>System Requirements<a class="headerlink" href="#system-requirements" title="Permalink to this heading"></a></h2>
<p>Nsight Systems supports multiple platforms. For simplicity, think of these as Nsight Systems Embedded Platforms Edition and Nsight Systems Workstation Edition, where Nsight Systems Workstation Edition supports desktops, workstations, and clusters with x86_64, IBM Power, and Arm SBSA CPUs on Linux and Windows OSs, while Nsight Systems Embedded Platforms Edition supports NVIDIA Tegra products for the embedded and gaming space on Linux for Tegra and QNX OSs.</p>
<section id="supported-platforms">
<h3>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Permalink to this heading"></a></h3>
<p>Depending on your OS, different GPUs are supported</p>
<p>L4T (Linux for Tegra)</p>
<ul class="simple">
<li><p>Jetson AGX Xavier</p></li>
<li><p>Jetson TX2</p></li>
<li><p>Jetson TX2i</p></li>
<li><p>Jetson TX</p></li>
<li><p>Jetson Nano</p></li>
<li><p>Jetson Xavier NX</p></li>
</ul>
<p>x86_64, IBM Power (from Power 9), or Arm SBSA</p>
<ul class="simple">
<li><p>NVIDIA GPU architectures starting with Pascal</p></li>
<li><p>OS (64 bit only)</p>
<ul>
<li><p>Ubuntu 18.04, 20.04, and 22.04</p></li>
<li><p>CentOS and RedHat Enterprise Linux 7.4+ with kernel version 3.10.0-693 or later.</p></li>
<li><p>Windows 10, 11, and Win Server 2022</p></li>
</ul>
</li>
</ul>
</section>
<section id="cuda-version">
<h3>CUDA Version<a class="headerlink" href="#cuda-version" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>Nsight Systems supports CUDA 10.0, 10.1, 10.2, and 11.X for most platforms</p></li>
<li><p>Nsight Systems on Arm SBSA supports 10.2 and 11.X</p></li>
</ul>
<p>Note that CUDA version and driver version must be compatible.</p>
<table class="table-no-stripes docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>CUDA Version</p></th>
<th class="head"><p>Driver minimum version</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>11.0</p></td>
<td><p>450</p></td>
</tr>
<tr class="row-odd"><td><p>10.2</p></td>
<td><p>440.30</p></td>
</tr>
<tr class="row-even"><td><p>10.1</p></td>
<td><p>418.39</p></td>
</tr>
<tr class="row-odd"><td><p>10.0</p></td>
<td><p>410.48</p></td>
</tr>
</tbody>
</table>
<p>From CUDA 11.X on, any driver from 450 on will be supported, although new features introduced in more recent drivers will not be available.</p>
<p>For information about which drivers were specifically released with each toolkit, see <a class="reference external" href="https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions">CUDA Toolkit Release Notes - Major Component Versions</a></p>
</section>
<section id="requirements-for-x86-64-power-and-arm-sbsa-targets-on-linux">
<h3>Requirements for x86_64, Power, and Arm SBSA Targets on Linux<a class="headerlink" href="#requirements-for-x86-64-power-and-arm-sbsa-targets-on-linux" title="Permalink to this heading"></a></h3>
<p>When attaching to x86_64, Power, or Arm SBSA Linux-based target from the GUI on the host, the connection is established through SSH.</p>
<p><strong>Use of Linux Perf</strong>: To collect thread scheduling data and IP (instruction pointer) samples, the Linux operating system’s perf_event_paranoid level must be 2 or less. Use the following command to check:</p>
<blockquote>
<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>cat /proc/sys/kernel/perf_event_paranoid
</pre></div>
</div>
</div></blockquote>
<p>If the output is >2, then do the following to temporarily adjust the paranoid level (note that this has to be done after each reboot):</p>
<blockquote>
<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo sh -c 'echo 2 >/proc/sys/kernel/perf_event_paranoid'
</pre></div>
</div>
</div></blockquote>
<p>To make the change permanent, use the following command:</p>
<blockquote>
<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo sh -c 'echo kernel.perf_event_paranoid=2 > /etc/sysctl.d/local.conf'
</pre></div>
</div>
</div></blockquote>
<p><strong>Kernel version</strong>: To collect thread scheduling data and IP (instruction pointer) samples and backtraces, the kernel version must be:</p>
<ul class="simple">
<li><p>3.10.0-693 or later for CentOS and RedHat Enterprise Linux 7.4+</p></li>
<li><p>4.3 or greater for all other distros including Ubuntu</p></li>
</ul>
<p>To check the version number of the kernel on a target device, run the following command on the device:</p>
<blockquote>
<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>uname -a
</pre></div>
</div>
</div></blockquote>
<p>Note that only CentOS, RedHat, and Ubuntu distros are tested/confirmed to work correctly.</p>
<p><strong>glibc version</strong>: To check the glibc version on a target device, run the following command:</p>
<blockquote>
<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>ldd --version
</pre></div>
</div>
</div></blockquote>
<p>Nsight Systems requires glibc 2.17 or more recent.</p>
<p><strong>CUDA</strong>: See above for supported CUDA versions in this release. Use the deviceQuery command to determine the CUDA driver and runtime versions on the system. the deviceQuery command is available in the CUDA SDK. It is normally installed at:</p>
<blockquote>
<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>/usr/local/cuda/samples/1_Utilities/deviceQuery
</pre></div>
</div>
</div></blockquote>
<p>Only pure 64-bit environments are supported. In other words, 32-bit systems or 32-bit processes running within a 64-bit environment are not supported.</p>
<p>Nsight Systems requires write permission to the <code class="docutils literal notranslate"><span class="pre">/var/lock</span></code> directory on the target system.</p>
<p><strong>Docker</strong>: See Collecting Data within a Docker section of the User Guide for more information.</p>
</section>
<section id="x86-64-windows-target-device-requirements">
<h3>x86_64 Windows Target Device Requirements<a class="headerlink" href="#x86-64-windows-target-device-requirements" title="Permalink to this heading"></a></h3>
<p><strong>DX12 Requires</strong>:</p>
<ul class="simple">
<li><p>Windows 10 with NVIDIA Driver 411.63 or higher for DX12 trace</p></li>
<li><p>Windows 10 April 2018 Update (version 1803, AKA Redstone 4) with NVIDIA Driver 411.63 or higher for DirectX Ray Tracing, and tracing DX12 Copy command queues.</p></li>
</ul>
</section>
<section id="host-application-requirements">
<h3>Host Application Requirements<a class="headerlink" href="#host-application-requirements" title="Permalink to this heading"></a></h3>
<p>The Nsight Systems host application runs on the following host platforms:</p>
<ul class="simple">
<li><p>Windows 10, Windows Server 2019. Only 64-bit versions are supported.</p></li>
<li><p>Linux Ubuntu 14.04 and higher are known to work, running on other modern distributions should be possible as well. Only 64-bit versions are supported.</p></li>
<li><p>OS X 10.10 “Yosemite” and higher.</p></li>
</ul>
</section>
</section>
<section id="getting-started-guide">
<h2>Getting Started Guide<a class="headerlink" href="#getting-started-guide" title="Permalink to this heading"></a></h2>
<section id="finding-the-right-package">
<h3>Finding the Right Package<a class="headerlink" href="#finding-the-right-package" title="Permalink to this heading"></a></h3>
<p>Nsight Systems is available for multiple targets and multiple host OSs. To choose the right package, first consider the target system to be analyzed.</p>
<ul class="simple">
<li><p>For Tegra target systems, select Nsight Systems Embedded Platforms Edition available as part of <a class="reference external" href="https://developer.nvidia.com/embedded/jetpack">NVIDIA JetPack SDK</a>.</p></li>
<li><p>For x86_64, IBM Power target systems, or Arm SBSA select from the target packages from Nsight Systems Workstation Edition, available from <a class="reference external" href="https://developer.nvidia.com/nsight-systems">https://developer.nvidia.com/nsight-systems</a>. This web release will always contain the latest and greatest Nsight Systems features.</p></li>
<li><p>The x86_64, IBM Power, and Arm SBSA target versions of Nsight Systems are also available in the <a class="reference external" href="https://developer.nvidia.com/cuda-downloads">CUDA Toolkit.</a></p></li>
</ul>
<p>Each package is limited to one architecture. For example, Tegra packages do not contain support for profiling x86 targets, and x86 packages do not contain support for profiling Tegra targets.</p>
<p>After choosing an appropriate target version, select the package corresponding to the host OS, the OS on the system where results will be viewed. These packages are in the form of common installer types: .msi for Windows; .run, .rpm, and .deb for x86 Linux; .deb and .rpm for Linux on IBM Power; and .dmg for the macOS installer.</p>
<p>Note: the IBM Power and Arm SBSA packages do not have a GUI for visualization of the result. If you wish to visualize your result, please download and install the GUI available for macOS, x86_64 Linux, or Windows systems.</p>
<p><strong>Tegra packages</strong></p>
<ul class="simple">
<li><p>Windows host - Install .msi on Windows machine. Enables remote access to Tegra device for profiling.</p></li>
<li><p>Linux host - Install .run on Linux system. Enables remote access to Tegra device for profiling.</p></li>
<li><p>macOS host - Install .dmg on macOS machine. Enables remote access to Tegra device for profiling.</p></li>
</ul>
<p><strong>x86_64 packages</strong></p>
<ul class="simple">
<li><p>Windows host - Install .msi on Windows machine. Enables remote access to Linux x86_64 or Windows devices for profiling as well as running on local system.</p></li>
<li><p>Linux host - Install .run, .rpm, or .deb on Linux system. Enables remote access to Linux x86_64 or Windows devices for profiling or running collection on localhost.</p></li>
<li><p>Linux CLI only - The Linux CLI is shipped in all x86 packages, but if you just want the CLI, we have a package for that. Install .deb on Linux system. Enables only CLI collection, report can be imported or opened in x86_64 host.</p></li>
<li><p>macOS host - Install .dmg on macOS machine. Enables remote access to Linux x86_64 device for profiling.</p></li>
</ul>
<p><strong>IBM Power packages</strong></p>
<ul class="simple">
<li><p>Power CLI only - The IBM Power support does not include a host GUI. Install .deb or .rpm on your Power system. Enables only CLI collection, report can be imported or opened in GUI on any supported host platform.</p></li>
</ul>
<p><strong>Arm SBSA packages</strong></p>
<ul class="simple">
<li><p>Arm SBSA CLI only - Arm SBSA support does not include a host GUI. Install .deb or .rpm on your Arm SBSA system. Enables only CLI collection, report can be imported or opened in GUI on any supported host platform.</p></li>
</ul>
</section>
<section id="installing-gui-on-the-host-system">
<h3>Installing GUI on the Host System<a class="headerlink" href="#installing-gui-on-the-host-system" title="Permalink to this heading"></a></h3>
<p>Copy the appropriate file to your host system in a directory where you have write and execute permissions. Run the install file, accept the EULA, and Nsight Systems will install on your system.</p>
<p>On Linux, there are special options to enable automated installation. Running the installer with the <code class="docutils literal notranslate"><span class="pre">--accept</span></code> flag will automatically accept the EULA, running with the <code class="docutils literal notranslate"><span class="pre">--accept</span></code> flag and the <code class="docutils literal notranslate"><span class="pre">--quiet</span></code> flag will automatically accept the EULA without printing to stdout. Running with <code class="docutils literal notranslate"><span class="pre">--quiet</span></code> without <code class="docutils literal notranslate"><span class="pre">--accept</span></code> will display an error.</p>
<p>The installation will create a Host directory for this host and a Target directory for each target this Nsight Systems package supports.</p>
<p>All binaries needed to collect data on a target device will be installed on the target by the host on first connection to the device. There is no need to install the package on the target device.</p>
<p>If installing from the CUDA Toolkit, see the <a class="reference external" href="https://docs.nvidia.com/cuda/">CUDA Toolkit documentation</a>.</p>
</section>
<section id="optional-setting-up-the-cli">
<h3>Optional: Setting up the CLI<a class="headerlink" href="#optional-setting-up-the-cli" title="Permalink to this heading"></a></h3>
<p>All Nsight Systems targets can be profiled using the CLI. IBM Power and Arm SBSA targets can only be profiled using the CLI. The CLI is especially helpful when scripts are used to run unattended collections or when access to the target system via ssh is not possible. In particular, this can be used to enable collection in a Docker container.</p>
<p>The CLI can be found in the Target directory of the Nsight Systems installation. Users who want to install the CLI as a standalone tool can do so by copying the files within the Target directory to the location of their choice.</p>
<p>If you wish to run the CLI without root (recommended mode) you will want to install in a directory where you have full access.</p>
<p>Once you have the CLI set up, you can use the <code class="docutils literal notranslate"><span class="pre">nsys</span> <span class="pre">status</span> <span class="pre">-e</span></code> command to check your environment.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="o">~</span><span class="n">$</span><span class="w"> </span><span class="n">nsys</span><span class="w"> </span><span class="n">status</span><span class="w"> </span><span class="o">-</span><span class="n">e</span><span class="w"></span>
<span class="n">Sampling</span><span class="w"> </span><span class="n">Environment</span><span class="w"> </span><span class="n">Check</span><span class="w"></span>
<span class="n">Linux</span><span class="w"> </span><span class="n">Kernel</span><span class="w"> </span><span class="n">Paranoid</span><span class="w"> </span><span class="n">Level</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="o">:</span><span class="w"> </span><span class="n">OK</span><span class="w"></span>
<span class="n">Linux</span><span class="w"> </span><span class="n">Distribution</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Ubuntu</span><span class="w"></span>
<span class="n">Linux</span><span class="w"> </span><span class="n">Kernel</span><span class="w"> </span><span class="n">Version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">4.15.0</span><span class="mi">-109</span><span class="o">-</span><span class="n">generic</span><span class="o">:</span><span class="w"> </span><span class="n">OK</span><span class="w"></span>
<span class="n">Linux</span><span class="w"> </span><span class="n">perf_event_open</span><span class="w"> </span><span class="n">syscall</span><span class="w"> </span><span class="n">available</span><span class="o">:</span><span class="w"> </span><span class="n">OK</span><span class="w"></span>
<span class="n">Sampling</span><span class="w"> </span><span class="n">trigger</span><span class="w"> </span><span class="n">event</span><span class="w"> </span><span class="n">available</span><span class="o">:</span><span class="w"> </span><span class="n">OK</span><span class="w"></span>
<span class="n">Intel</span><span class="p">(</span><span class="n">c</span><span class="p">)</span><span class="w"> </span><span class="n">Last</span><span class="w"> </span><span class="n">Branch</span><span class="w"> </span><span class="n">Record</span><span class="w"> </span><span class="n">support</span><span class="o">:</span><span class="w"> </span><span class="n">Available</span><span class="w"></span>
<span class="n">Sampling</span><span class="w"> </span><span class="n">Environment</span><span class="o">:</span><span class="w"> </span><span class="n">OK</span><span class="w"></span>
</pre></div>
</div>
<p>This status check allows you to ensure that the system requirements for CPU sampling using Nsight Systems are met in your local environment. If the Sampling Environment is not OK, you will still be able to run various trace operations.</p>
<p>Intel(c) Last Branch Record allows tools, including Nsight Systems to use hardware to quickly get limited stack information. Nsight Systems will use this method for stack resolution by default if available.</p>
<p>For information about changing these environment settings, see System Requirements section in the Installation Guide. For information about changing the backtrace method, see Profiling from the CLI in the User Guide.</p>
<p>To get started using the CLI, run <code class="docutils literal notranslate"><span class="pre">nsys</span> <span class="pre">--help</span></code> for a list of options or see Profiling Applications from the CLI in the User Guide for full documentation.</p>
</section>
<section id="launching-the-gui">
<h3>Launching the GUI<a class="headerlink" href="#launching-the-gui" title="Permalink to this heading"></a></h3>
<p>Depending on your OS, Nsight Systems will have installed an icon on your host desktop that you can use to launch the GUI. To launch the GUI directly, run the <code class="docutils literal notranslate"><span class="pre">nsys-ui</span></code> executable in the Host sub-directory of your installation.</p>
</section>
<section id="installing-multi-report-analysis-system">
<h3>Installing Multi Report Analysis System<a class="headerlink" href="#installing-multi-report-analysis-system" title="Permalink to this heading"></a></h3>
<p><strong>PREVIEW FEATURE</strong></p>
<p>The Nsight Systems multi-report analysis system can be located in the <code class="docutils literal notranslate"><span class="pre"><install-dir>/target-linux-x64/python/packages</span></code> directory. For this initial preview release, multi-node analysis is only available to run recipes on Linux targets, and only available to visualize on Linux or Windows hosts.</p>
<p><strong>Recipe Dependencies</strong></p>
<p>The system is written in Python and depends on a set of Python packages. The prerequisites are Python 3.6 or newer with pip and venv. If you don’t have Python, you can install it from python.org or your Linux package manager.</p>
<p><strong>Pip/venv on Ubuntu</strong></p>
<p>If pip/venv were not installed with Python, run:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get install python3-pip
$ sudo apt-get install python3-venv
</pre></div>
</div>
<p>On a fresh Ubuntu install, we will need to run the following before the above commands:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ sudo apt-get update
</pre></div>
</div>
<p>The dependent packages can either be installed automatically by an automated script or manually.</p>
<p><strong>Automated script</strong></p>
<p>The <code class="docutils literal notranslate"><span class="pre"><install-dir>/target-linux-x64/python/packages/nsys_recipe/install.py</span></code> script automates the installation of the recipe dependencies. You must select either the <code class="docutils literal notranslate"><span class="pre">--current</span></code> or <code class="docutils literal notranslate"><span class="pre">--venv</span> <span class="pre">PATH</span></code> option when you run the script.</p>
<p>Options:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">-h</span></code>: Display help</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--current</span></code>: Install packages in the current environment. If a venv is active, packages will be installed there. Otherwise, packages will be installed in the system site-packages directory. It enables usage of <code class="docutils literal notranslate"><span class="pre">nsys</span> <span class="pre">recipe</span></code> without having to source a virtual environment. However, new packages risk colliding with existing ones if different versions are required.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--venv</span> <span class="pre">PATH</span></code>: Install packages in a virtual environment. If it doesn’t already exist, it is created. It prevents risk of package collision in the current environment but requires the virtual environment to be activated before running <code class="docutils literal notranslate"><span class="pre">nsys</span> <span class="pre">recipe</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--tar</span></code>: download wheel packages online and tar them</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--untar</span></code>: untar the wheel packages and install</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--python</span></code>: change the python executable (default is python3)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--no-jupyter</span></code>: do not install requirements for the jupyter notebook</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--no-dask</span></code>: do not install requirements for Dask</p></li>
</ul>
<p>If <code class="docutils literal notranslate"><span class="pre">--tar</span></code> or <code class="docutils literal notranslate"><span class="pre">--untar</span></code> option wasn’t specified, the script will directly download the pip packages from the internet.</p>
<p><strong>Manual steps</strong></p>
<p>If you would rather install the dependencies manually, please follow the following steps:</p>
<ul>
<li><p>Create a virtual environment</p>
<p>We recommend creating a virtual environment to avoid installing packages directly into your system Python. The commands create the virtual environment in the current working directory.</p>
<p>See <a class="reference external" href="https://docs.python.org/3/library/venv.html">venv - python doc</a></p>
<p>To create a venv named recipe_env:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ python3 -m venv recipe_env
$ source recipe_env/bin/activate
</pre></div>
</div>
</li>
<li><p>List of dependencies</p>
<p>We have three files located in <code class="docutils literal notranslate"><span class="pre"><install-dir>/target-linux-x64/python/packages/nsys_recipe/requirements</span></code> for the dependencies:</p>
<ul class="simple">
<li><p>Common.txt (required): dependencies needed by all recipes</p></li>
<li><p>Dask.txt (optional): dependencies needed by the Dask mode</p></li>
<li><p>Jupyter.txt (optional): dependencies needed to open the Jupyter notebook</p></li>
</ul>
</li>
</ul>
<p><strong>One-step installation</strong></p>
<p>The following command will install all dependencies for CLI and GUI. Please note that you will want to activate your venv first as described above, otherwise the modules will not be available in the venv.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ python3 -m pip install -r nsys_recipe/requirements/dask.txt -r nsys_recipe/requirements/common.txt -r nsys_recipe/requirements/jupyter.txt
</pre></div>
</div>
<p><strong>Two-step installation (for machines without internet)</strong></p>
<p>If you wish to download the dependencies on a machine without internet, you can download the wheel packages on a machine with internet, transfer them to the target machine and install the packages there.</p>
<p>On the machine with internet:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ python3 -m pip download -r nsys_recipe/requirements/dask.txt -r nsys_recipe/requirements/common.txt -r nsys_recipe/requirements/jupyter.txt -d “recipe-deps”
$ tar -cvfz recipe-deps.tar.gz recipe-deps
</pre></div>
</div>
<p>On the machine with no internet:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ tar -xvfz recipe-deps.tar.gz
$ python3 -m pip install recipe-deps/* --no-index
</pre></div>
</div>
<p><strong>Jupyter Notebook</strong></p>
<p>The Nsight Systems UI has the ability to internally load a Jupyter notebook. It uses the Jupyter notebook installation associated with the Python on your $PATH, which is expected to be the Python installed into the virtual environment created in the earlier steps of this guide.</p>
<p>If Jupyter is installed in a different location, you can add a third variable to the config.ini file that will override the default path to Jupyter:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>JupyterPythonExe=“/path/to/recipe_env/bin/python”
</pre></div>
</div>
<p>This config.ini file should be placed in <code class="docutils literal notranslate"><span class="pre"><install_dir>/host-linux-x64</span></code></p>
<p>Note that on Windows, the path should use Windows slashes and they must be double slashes:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>JupyterPythonExe=“c:\\path\\to\\recipe_env\\bin\\python.exe”
</pre></div>
</div>
</section>
</section>
</section>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>© Copyright 2018-2023, NVIDIA Corporation & Affiliates. All rights reserved.
<span class="lastupdated">Last updated on Dec 20, 2023.
</span></p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
