Metrix

Metrix#

Metrix translates raw hardware counters into clean, human-readable metrics for AMD GPUs.

Features#

Metrix provides the following capabilities.

Modern Python API
Human-readable metrics instead of raw counters
Unit tested and reliable
20 metrics across memory, cache, compute, and GPU utilization (availability varies by GPU architecture)
Multi-run profiling supporting automatic aggregation with min/max/avg statistics
Kernel filtering with efficient regex filtering at the rocprofv3 level
Multiple output formats, including text, JSON, and CSV

Requirements#

Metrix requires the following.

Python >= 3.10
ROCm 7.2.x with rocprofv3
pandas >= 1.5.0

Installation#

Run the following commands from the metrix directory:

pip install -e .

Quick start#

Use the CLI for quick profiling, or the Python API for programmatic access.

CLI#

# Profile with all metrics (architecture auto-detected)
metrix ./my_app

# Time only (fast)
metrix --time-only -n 10 ./my_app

# Filter kernels by name
metrix --kernel matmul ./my_app

# Custom metrics
metrix --metrics memory.l2_hit_rate,memory.coalescing_efficiency ./my_app

# Save to JSON
metrix -o results.json ./my_app

Python API#

from metrix import Metrix

# Architecture is auto-detected
profiler = Metrix()
results = profiler.profile("./my_app", num_replays=5)

for kernel in results.kernels:
    print(f"{kernel.name}: {kernel.duration_us.avg:.2f} us")
    for metric, stats in kernel.metrics.items():
        print(f"  {metric}: {stats.avg:.2f}")

Available metrics#

Metrix provides 20 metrics organized by category. Availability varies by GPU architecture.

Compute#

Metric	Description
`compute.gpu_utilization`	GPU utilization (%). gfx1201/gfx1151 only.
`compute.total_flops`	Total floating-point operations performed
`compute.hbm_gflops`	Compute throughput (GFLOP/s)
`compute.hbm_arithmetic_intensity`	Ratio of FLOPs to HBM bytes (FLOPs/Byte)
`compute.l2_arithmetic_intensity`	Ratio of FLOPs to L2 bytes (FLOPs/Byte)
`compute.l1_arithmetic_intensity`	Ratio of FLOPs to L1 bytes (FLOPs/Byte)

Memory bandwidth#

Metric	Description
`memory.hbm_read_bandwidth`	HBM read bandwidth (GB/s)
`memory.hbm_write_bandwidth`	HBM write bandwidth (GB/s)
`memory.hbm_bandwidth_utilization`	% of peak HBM bandwidth
`memory.bytes_transferred_hbm`	Total bytes through HBM
`memory.bytes_transferred_l2`	Total bytes through L2 cache
`memory.bytes_transferred_l1`	Total bytes through L1 cache

Cache performance#

Metric	Description
`memory.l1_hit_rate`	L1 cache hit rate (%)
`memory.l2_hit_rate`	L2 cache hit rate (%)
`memory.l2_bandwidth`	L2 cache bandwidth (GB/s)

Memory access patterns#

Metric	Description
`memory.coalescing_efficiency`	Memory coalescing efficiency (%)
`memory.global_load_efficiency`	Global load efficiency (%)
`memory.global_store_efficiency`	Global store efficiency (%)

Atomic operations#

Metric	Description
`memory.atomic_latency`	Atomic operation latency (cycles)

CLI reference#

The Metrix CLI supports the following commands and options.

metrix [--version] <command> ...

metrix profile [options] <target>

  --profile, -p      Metric profile: quick | memory | memory_bandwidth |
                     memory_cache | compute (default: all metrics if omitted)
  --metrics, -m      Comma-separated list of metrics
  --time-only        Only collect timing, no hardware counters
  --kernel, -k       Filter kernels by name (regex, passed to rocprofv3)
  --num-replays, -n  Replay the application N times and aggregate (default: 10)
  --aggregate        Aggregate metrics by kernel name across replays
  --top K            Show only top K slowest kernels
  --output, -o       Output file (.json, .csv, .txt)
  --timeout SECONDS  Profiling timeout in seconds (default: 60)
  --log, -l          Logging level: debug | info | warning | error
  --quiet, -q        Quiet mode
  --no-counters      Omit raw counter values from output

metrix list <metrics|profiles|devices> [--category CAT]

metrix info <metric|profile> <name>

GPU architecture is auto-detected using rocminfo.