1.**Launch & Profile the target application with the command line profiler**
The command line profiler launches the target application, calls the rocProfiler API, and collects profile results for the specified kernels, dispatches, and/or ipblock’s.
To collect the default set of data for all kernels in the target application, launch:
The app runs, each kernel is launched, and profiling results are generated. By default, results are written to ./workloads/\<name>. To collect all requested profile information, it may be required to replay kernels multiple times.
2. **Customize data collection**
Options are available to specify for which kernels data should be collected.
`-k`/`--kernel` enables filtering kernels by name. `-d`/`--dispatch` enables filtering based on dispatch ID. `-b`/`--ipblocks` enables profiling on one or more IP Block(s).
To view available metrics by IP Block you can always use `--list-metrics` to view a list of all available metrics organized by IP Block.
```shell
$ omniperf analyze --list-metrics <sys_arch>
```
Note that filtering can also be applied after the fact, at the analysis stage, however filtering at the profiling level will often speed up your overall profiling run time.
3. **Analyze at the command line**
After generating a local output folder (./workloads/\<name>), the command line tool can also be used to quickly interface with profiling results. View different metrics derived from your profiled results and get immediate access all metrics organized by IP block.
If no kernel, dispatch, or ipblock filters are applied at this stage, analysis will be reflective of the entirety of the profiling data.
To interact with profiling results from a different session, users just provide the workload path. `-p`/`--path` enables users to analyze existing profiling data in the Omniperf CLI.
4. **Analyze in the Grafana GUI**
To conduct a more in-depth analysis of profiling results we recommend users utilize the Omniperf Grafana GUI. To interact with profiling results, users must import their data to the MongoDB instance included in the Omniperf dockerfile.
To interact with Grafana GUI data, stored in the Omniperf DB, users can enter ***database*** mode. For example:
```shell
$ omniperf database --import [CONNECTION OPTIONS]
```
## Usage
### Modes
Modes change the fundamental behavior of the Omniperf command line tool. Depending on which mode is chosen, different command line options become available.
- **Profile**: Target application is launched on the local system utilizing AMD’s [ROC Profiler](https://github.com/ROCm-Developer-Tools/rocprofiler). Depending on the profiling options chosen, selected kernels, dispatches, and/or IP Blocks in the application are profiled and results are stored locally in an output folder (./workloads/\<name>).
```shell
$ omniperf profile --help
```
- **Analyze**: Profiling data from `-p`/`--path` directory is loaded into the Omniperf CLI analyzer where users have immediate access to profiling results and generated metrics. Metrics are quickly generated from the entirety of your profiled application or a subset you’ve identified through the Omniperf CLI analysis filters.
To gererate a lightweight GUI interface users can add the `--gui` flag to their analysis command.
This mode is designed to be a middle ground to the highly detailed Omniperf Grafana GUI and is great for users who want immediate access to an IP Block they’re already familiar with.
```shell
$ omniperf analyze --help
```
- **Database**: Our detailed Grafana GUI is built on a MongoDB database. `--import` profiling results to the DB to interact with the workload in Grafana or `--remove` the workload from the DB.
