gpufl 0.1.0.dev0__tar.gz → 0.1.0.dev7__tar.gz

gpufl-0.1.0.dev7/.github/workflows/release.yml

@@ -0,0 +1,193 @@
+name: Build and Release Wheels
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set package version from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: python
+        run: |
+          import os
+          import re
+          from pathlib import Path
+
+          ref_name = os.environ.get("GITHUB_REF_NAME", "")
+          if not ref_name.startswith("v"):
+              raise SystemExit(f"Expected tag starting with 'v', got: {ref_name}")
+          version = ref_name[1:]
+          print(f"Using version from tag: {version}")
+
+          pyproject = Path("pyproject.toml")
+          text = pyproject.read_text(encoding="utf-8")
+          text_new, n = re.subn(
+              r'(?m)^version\s*=\s*"[^\"]+"$',
+              f'version = "{version}"',
+              text,
+              count=1,
+          )
+          if n != 1:
+              raise SystemExit("Failed to update [project].version in pyproject.toml")
+          pyproject.write_text(text_new, encoding="utf-8")
+
+          init_py = Path("python/gpufl/__init__.py")
+          if init_py.exists():
+              init_text = init_py.read_text(encoding="utf-8")
+              init_new, _ = re.subn(
+                  r'(?m)^__version__\s*=\s*"[^\"]+"$',
+                  f'__version__ = "{version}"',
+                  init_text,
+              )
+              init_py.write_text(init_new, encoding="utf-8")
+
+      - name: Cache cibuildwheel downloads
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/cibuildwheel
+            ~/AppData/Local/pypa/cibuildwheel/Cache
+          key: cibw-${{ runner.os }}-${{ hashFiles('.github/workflows/release.yml') }}
+          restore-keys: |
+            cibw-${{ runner.os }}-
+
+      - name: Install CUDA (Windows)
+        if: runner.os == 'Windows'
+        uses: Jimver/cuda-toolkit@v0.2.30
+        with:
+          cuda: '13.1.0'
+          method: 'network'
+
+      - name: Prefetch virtualenv.pyz (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $version = "20.27.1"
+          $cacheDir = Join-Path $env:LOCALAPPDATA "pypa\cibuildwheel\Cache"
+          New-Item -ItemType Directory -Path $cacheDir -Force | Out-Null
+          $dest = Join-Path $cacheDir "virtualenv-$version.pyz"
+          if (Test-Path $dest) {
+            Write-Host "virtualenv.pyz already cached: $dest"
+            exit 0
+          }
+          $urls = @(
+            "https://raw.githubusercontent.com/pypa/get-virtualenv/$version/public/virtualenv.pyz",
+            "https://raw.githubusercontent.com/pypa/get-virtualenv/refs/tags/$version/public/virtualenv.pyz",
+            "https://bootstrap.pypa.io/virtualenv.pyz"
+          )
+          $max = 6
+          $ok = $false
+          foreach ($url in $urls) {
+            for ($i = 1; $i -le $max; $i++) {
+              try {
+                Write-Host "Downloading virtualenv.pyz from $url (attempt $i/$max)..."
+                Invoke-WebRequest -Uri $url -OutFile $dest -TimeoutSec 120 -Headers @{ "User-Agent" = "cibuildwheel-prefetch" }
+                if ((Get-Item $dest).Length -gt 0) {
+                  Write-Host "Downloaded: $dest"
+                  $ok = $true
+                  break
+                }
+              } catch {
+                if (Test-Path $dest) { Remove-Item $dest -Force -ErrorAction SilentlyContinue }
+                if ($i -eq $max) { break }
+                Start-Sleep -Seconds (5 * $i)
+              }
+            }
+            if ($ok) { break }
+          }
+          if (-not $ok) { throw "Failed to prefetch virtualenv.pyz from all sources." }
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.22.0
+        env:
+          CIBW_VIRTUALENV_VERSION: "20.27.1"
+          CIBW_ENVIRONMENT_LINUX: "CUDA_HOME=/usr/local/cuda PATH=/usr/local/cuda/bin:$PATH CMAKE_ARGS='-DGPUFL_ENABLE_NVIDIA=ON -DGPUFL_ENABLE_AMD=OFF -DBUILD_TESTING=OFF'"
+          CIBW_BEFORE_ALL_LINUX: >-
+            curl -fsSL https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/cuda-rhel8.repo > /etc/yum.repos.d/cuda.repo &&
+            dnf install -y --nogpgcheck cuda-nvcc-13-1 cuda-cudart-devel-13-1 cuda-cupti-13-1 cuda-driver-devel-13-1
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_BUILD: "cp312-manylinux_x86_64 cp313-manylinux_x86_64 cp312-win_amd64 cp313-win_amd64"
+          CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair --plat manylinux_2_28_x86_64 --exclude libcuda.so.1 -w {dest_dir} {wheel}"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set package version from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: python
+        run: |
+          import os
+          import re
+          from pathlib import Path
+
+          ref_name = os.environ.get("GITHUB_REF_NAME", "")
+          if not ref_name.startswith("v"):
+              raise SystemExit(f"Expected tag starting with 'v', got: {ref_name}")
+          version = ref_name[1:]
+          print(f"Using version from tag: {version}")
+
+          pyproject = Path("pyproject.toml")
+          text = pyproject.read_text(encoding="utf-8")
+          text_new, n = re.subn(
+              r'(?m)^version\s*=\s*"[^\"]+"$',
+              f'version = "{version}"',
+              text,
+              count=1,
+          )
+          if n != 1:
+              raise SystemExit("Failed to update [project].version in pyproject.toml")
+          pyproject.write_text(text_new, encoding="utf-8")
+
+          init_py = Path("python/gpufl/__init__.py")
+          if init_py.exists():
+              init_text = init_py.read_text(encoding="utf-8")
+              init_new, _ = re.subn(
+                  r'(?m)^__version__\s*=\s*"[^\"]+"$',
+                  f'__version__ = "{version}"',
+                  init_text,
+              )
+              init_py.write_text(init_new, encoding="utf-8")
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  upload_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

{gpufl-0.1.0.dev0 → gpufl-0.1.0.dev7}/CMakeLists.txt

@@ -47,7 +47,15 @@ target_compile_features(gpufl INTERFACE cxx_std_17)
 set_target_properties(gpufl PROPERTIES POSITION_INDEPENDENT_CODE ON)
 
 target_sources(gpufl PRIVATE
-    include/gpufl/core/logger.cpp
+    include/gpufl/core/logger/logger.cpp
+    include/gpufl/core/logger/log_rotator.cpp
+    include/gpufl/core/model/lifecycle_model.cpp
+    include/gpufl/core/model/kernel_event_model.cpp
+    include/gpufl/core/model/memcpy_event_model.cpp
+    include/gpufl/core/model/scope_event_model.cpp
+    include/gpufl/core/model/profile_sample_model.cpp
+    include/gpufl/core/model/perf_metric_model.cpp
+    include/gpufl/core/model/system_event_model.cpp
     include/gpufl/core/sampler.cpp
     include/gpufl/core/runtime.cpp
     include/gpufl/core/gpufl.cpp
@@ -61,6 +69,43 @@ set(GPUFL_HAS_CUDA 0)
 set(GPUFL_HAS_NVML 0)
 set(GPUFL_HAS_ROCM 0)
 set(GPUFL_HAS_CUPTI 0)
+set(GPUFL_HAS_PERFWORKS 0)
+# ZLIB — try system install first, fall back to FetchContent so every platform
+# (including Windows CI) always gets compression support and .gz output.
+find_package(ZLIB QUIET)
+if(ZLIB_FOUND)
+    message(STATUS "Found system ZLIB: ${ZLIB_LIBRARIES}")
+    target_link_libraries(gpufl PRIVATE ZLIB::ZLIB)
+else()
+    message(STATUS "ZLIB not found on system — fetching via FetchContent")
+    include(FetchContent)
+    # Suppress zlib's own example / test targets to keep the build clean
+    set(ZLIB_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+    FetchContent_Declare(
+        zlib
+        GIT_REPOSITORY https://github.com/madler/zlib.git
+        GIT_TAG        v1.3.1
+    )
+    FetchContent_MakeAvailable(zlib)
+    # zlib.h lives in the source dir; zconf.h is generated in the binary dir.
+    # Add both privately to gpufl — consumers never include zlib headers directly.
+    target_link_libraries(gpufl PRIVATE zlibstatic)
+    target_include_directories(gpufl PRIVATE
+        ${zlib_SOURCE_DIR}
+        ${zlib_BINARY_DIR}
+    )
+    # zlib's own CMakeLists sets INTERFACE_INCLUDE_DIRECTORIES on zlibstatic to
+    # build-directory paths, which CMake forbids in install exports.  Clear them:
+    # gpufl already propagates the paths privately, so consumers don't need them.
+    set_target_properties(zlibstatic PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "")
+    # zlibstatic must be in the same export set as gpufl — static lib consumers
+    # need to link it transitively, so CMake requires it to be exported too.
+    install(TARGETS zlibstatic
+        EXPORT   gpufl_clientTargets
+        ARCHIVE  DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    )
+endif()
+target_sources(gpufl PRIVATE include/gpufl/core/logger/file_compressor.cpp)
 
 # -----------------------
 # Backends
@@ -95,7 +140,10 @@ if(GPUFL_ENABLE_NVIDIA)
                 include/gpufl/backends/nvidia/kernel_launch_handler.cpp
                 include/gpufl/backends/nvidia/mem_transfer_handler.cpp
                 include/gpufl/cuda/monitor.cpp
-                include/gpufl/backends/nvidia/cupti_backend.cpp)
+                include/gpufl/backends/nvidia/cupti_backend.cpp
+                include/gpufl/backends/nvidia/engine/pc_sampling_engine.cpp
+                include/gpufl/backends/nvidia/engine/sass_metrics_engine.cpp
+                include/gpufl/backends/nvidia/engine/range_profiler_engine.cpp)
             target_link_libraries(gpufl PRIVATE CUDA::cudart CUDA::cuda_driver)
 
             # --------------------------------------------------------
@@ -124,6 +172,31 @@ if(GPUFL_ENABLE_NVIDIA)
                     message(STATUS "Found CUPTI manually: ${CUPTI_LIBRARY}")
                 endif()
             endif()
+
+            # --------------------------------------------------------
+            # NVPERF Support (for GFL_PERF_SCOPE hardware counters)
+            # --------------------------------------------------------
+            find_library(NVPERF_HOST_LIBRARY NAMES nvperf_host nvperf_host_static
+                HINTS "${CUDAToolkit_ROOT}/extras/CUPTI/lib64"
+                      "${CUDAToolkit_ROOT}/targets/x86_64-linux/lib"
+                      "$ENV{CUDA_PATH}/extras/CUPTI/lib64"
+                      "$ENV{CUDA_PATH}/targets/x86_64-linux/lib"
+            )
+            find_library(NVPERF_TARGET_LIBRARY NAMES nvperf_target
+                HINTS "${CUDAToolkit_ROOT}/extras/CUPTI/lib64"
+                      "${CUDAToolkit_ROOT}/targets/x86_64-linux/lib"
+                      "$ENV{CUDA_PATH}/extras/CUPTI/lib64"
+                      "$ENV{CUDA_PATH}/targets/x86_64-linux/lib"
+            )
+            if(NVPERF_HOST_LIBRARY AND NVPERF_TARGET_LIBRARY)
+                set(GPUFL_HAS_PERFWORKS 1)
+                target_link_libraries(gpufl PRIVATE
+                    ${NVPERF_HOST_LIBRARY} ${NVPERF_TARGET_LIBRARY})
+                message(STATUS "Found NVPERF: ${NVPERF_HOST_LIBRARY}")
+            else()
+                set(GPUFL_HAS_PERFWORKS 0)
+                message(WARNING "NVPERF not found — GFL_PERF_SCOPE disabled at runtime")
+            endif()
         endif()
     endif()
     #
@@ -178,10 +251,11 @@ if(GPUFL_ENABLE_NVIDIA)
     endif()
 
     # Apply definitions to public interface so tests inherit them
-    target_compile_definitions(gpufl PUBLIC 
+    target_compile_definitions(gpufl PUBLIC
         GPUFL_HAS_CUDA=${GPUFL_HAS_CUDA}
         GPUFL_HAS_NVML=${GPUFL_HAS_NVML}
         GPUFL_HAS_CUPTI=${GPUFL_HAS_CUPTI}
+        GPUFL_HAS_PERFWORKS=${GPUFL_HAS_PERFWORKS}
     )
 
     #

{gpufl-0.1.0.dev0 → gpufl-0.1.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: gpufl
-Version: 0.1.0.dev0
+Version: 0.1.0.dev7
 Summary: GPU Monitoring Client
 Author-Email: Myoungho Shin <myounghoshin84@gmail.com>
 Classifier: Development Status :: 3 - Alpha

{gpufl-0.1.0.dev0 → gpufl-0.1.0.dev7}/example/cuda/block_style_example.cu

@@ -36,12 +36,14 @@ int main() {
     // Initialize GFL
     gpufl::InitOptions opts;
     opts.app_name = "block_style_demo";
-    opts.log_path = "gfl_block.log";
+    opts.log_path = "gfl_block";
     opts.system_sample_rate_ms = 50;
     opts.kernel_sample_rate_ms = 50;
     opts.enable_kernel_details = true;
     opts.sampling_auto_start = true;
     opts.enable_debug_output = true;
+    opts.profiling_engine = gpufl::ProfilingEngine::SassMetrics;
+
     if (!gpufl::init(opts)) {
         std::cerr << "Failed to initialize gpufl" << std::endl;
         return 1;

{gpufl-0.1.0.dev0 → gpufl-0.1.0.dev7}/example/python/analyzer/01_analyzer_sample.py

@@ -7,4 +7,8 @@ analyzer.print_summary()
 
 analyzer.inspect_scopes()
 
-analyzer.inspect_hotspots()
+analyzer.inspect_hotspots()
+
+analyzer.inspect_profile_samples()
+
+analyzer.inspect_perf_metrics()

gpufl-0.1.0.dev7/include/gpufl/backends/nvidia/cupti_backend.cpp

@@ -0,0 +1,316 @@
+#include "gpufl/backends/nvidia/cupti_backend.hpp"
+
+#include <cupti_pcsampling.h>
+#include <cupti_profiler_target.h>
+#include <cupti_sass_metrics.h>
+#include <cupti_target.h>
+
+#if GPUFL_HAS_PERFWORKS
+#include <cupti_range_profiler.h>
+#endif
+
+#include <cstring>
+#include <exception>
+#include <set>
+
+#include "gpufl/backends/nvidia/cupti_utils.hpp"
+#include "gpufl/backends/nvidia/engine/pc_sampling_engine.hpp"
+#include "gpufl/backends/nvidia/engine/range_profiler_engine.hpp"
+#include "gpufl/backends/nvidia/engine/sass_metrics_engine.hpp"
+#include "gpufl/backends/nvidia/kernel_launch_handler.hpp"
+#include "gpufl/backends/nvidia/mem_transfer_handler.hpp"
+#include "gpufl/backends/nvidia/resource_handler.hpp"
+#include "gpufl/core/common.hpp"
+#include "gpufl/core/debug_logger.hpp"
+#include "gpufl/core/ring_buffer.hpp"
+#include "gpufl/core/trace_type.hpp"
+
+#include "gpufl/backends/nvidia/cuda_collector.hpp"
+#include "gpufl/core/scope_registry.hpp"
+#include "gpufl/core/stack_registry.hpp"
+#include "gpufl/core/stack_trace.hpp"
+
+namespace gpufl {
+std::atomic<gpufl::CuptiBackend*> g_activeBackend{nullptr};
+
+extern RingBuffer<ActivityRecord, 1024> g_monitorBuffer;
+
+void CuptiBackend::initialize(const MonitorOptions& opts) {
+    opts_ = opts;
+
+    DebugLogger::setEnabled(opts_.enable_debug_output);
+
+    // Create the engine (no CUDA context needed yet)
+    switch (opts_.profiling_engine) {
+        case ProfilingEngine::PcSampling:
+            engine_ = std::make_unique<PcSamplingEngine>();
+            GFL_LOG_DEBUG("[CuptiBackend] Engine: PcSampling");
+            break;
+        case ProfilingEngine::SassMetrics:
+            engine_ = std::make_unique<SassMetricsEngine>();
+            GFL_LOG_DEBUG("[CuptiBackend] Engine: SassMetrics");
+            break;
+        case ProfilingEngine::RangeProfiler:
+#if GPUFL_HAS_PERFWORKS
+            engine_ = std::make_unique<RangeProfilerEngine>();
+            GFL_LOG_DEBUG("[CuptiBackend] Engine: RangeProfiler");
+#else
+            GFL_LOG_ERROR("[CuptiBackend] RangeProfiler engine requires "
+                          "GPUFL_HAS_PERFWORKS; falling back to None");
+#endif
+            break;
+        case ProfilingEngine::None:
+        default:
+            GFL_LOG_DEBUG("[CuptiBackend] Engine: None (monitoring only)");
+            break;
+    }
+
+    g_activeBackend.store(this, std::memory_order_release);
+
+    // Internal handler registration
+    RegisterHandler(std::make_shared<ResourceHandler>(this));
+    RegisterHandler(std::make_shared<KernelLaunchHandler>(this));
+    RegisterHandler(std::make_shared<MemTransferHandler>(this));
+
+    GFL_LOG_DEBUG("Subscribing to CUPTI...");
+    CUPTI_CHECK_RETURN(
+        cuptiSubscribe(&subscriber_,
+                       reinterpret_cast<CUpti_CallbackFunc>(GflCallback), this),
+        "[GPUFL Monitor] ERROR: Failed to subscribe to CUPTI\n"
+        "[GPUFL Monitor] This may indicate:\n"
+        "  - CUPTI library not found or incompatible\n"
+        "  - Insufficient permissions\n"
+        "  - CUDA driver issues");
+    GFL_LOG_DEBUG("CUPTI subscription successful");
+
+    std::set<CUpti_CallbackDomain> domains;
+    std::set<std::pair<CUpti_CallbackDomain, CUpti_CallbackId>> callbacks;
+    {
+        std::lock_guard<std::mutex> lk(handler_mu_);
+        for (const auto& h : handlers_) {
+            for (auto d : h->requiredDomains()) domains.insert(d);
+            for (auto cb : h->requiredCallbacks()) callbacks.insert(cb);
+        }
+    }
+    for (auto d : domains) CUPTI_CHECK(cuptiEnableDomain(1, subscriber_, d));
+    for (auto& [domain, cbid] : callbacks)
+        CUPTI_CHECK(cuptiEnableCallback(1, subscriber_, domain, cbid));
+
+    CUptiResult resCb =
+        cuptiActivityRegisterCallbacks(BufferRequested, BufferCompleted);
+    if (resCb != CUPTI_SUCCESS) {
+        GFL_LOG_ERROR("FATAL: Failed to register activity callbacks.");
+        LogCuptiErrorIfFailed("CUPTI", "cuptiActivityRegisterCallbacks", resCb);
+        initialized_ = false;
+        return;
+    }
+
+    initialized_ = true;
+    GFL_LOG_DEBUG("Callbacks registered successfully.");
+}
+
+void CuptiBackend::shutdown() {
+    if (!initialized_) return;
+
+    // Delegate engine teardown first
+    if (engine_) {
+        engine_->stop();
+        engine_->shutdown();
+        engine_.reset();
+    }
+
+    LogCuptiErrorIfFailed("Perfworks", "cuptiActivityFlushAll",
+                          cuptiActivityFlushAll(1));
+
+    {
+        std::lock_guard<std::mutex> lk(handler_mu_);
+        std::set<CUpti_CallbackDomain> domains;
+        for (const auto& h : handlers_)
+            for (auto d : h->requiredDomains()) domains.insert(d);
+        for (auto d : domains) cuptiEnableDomain(0, subscriber_, d);
+    }
+
+    cuptiUnsubscribe(subscriber_);
+    g_activeBackend.store(nullptr, std::memory_order_release);
+    initialized_ = false;
+}
+
+CUptiResult (*CuptiBackend::get_value())(CUpti_ActivityKind) {
+    return cuptiActivityEnable;
+}
+
+void CuptiBackend::start() {
+    if (!initialized_) return;
+    kernel_activity_seen_.store(0, std::memory_order_relaxed);
+    kernel_activity_emitted_.store(0, std::memory_order_relaxed);
+    kernel_activity_throttled_.store(0, std::memory_order_relaxed);
+
+    CUPTI_CHECK(cuptiActivityEnable(CUPTI_ACTIVITY_KIND_SOURCE_LOCATOR));
+
+    // Enable activity kinds required by registered handlers (always on)
+    {
+        std::set<CUpti_ActivityKind> kinds;
+        {
+            std::lock_guard<std::mutex> lk(handler_mu_);
+            for (const auto& h : handlers_)
+                for (auto k : h->requiredActivityKinds()) kinds.insert(k);
+        }
+        for (auto k : kinds) CUPTI_CHECK(cuptiActivityEnable(k));
+    }
+
+    // Initialize and start the engine (requires CUDA context)
+    if (engine_) {
+        if (EnsureCudaContext(&ctx_)) {
+            cuptiGetDeviceId(ctx_, &device_id_);
+            chip_name_           = getChipName(device_id_);
+            cached_device_name_  = GetCurrentDeviceName();
+
+            EngineContext ectx{ctx_, device_id_, chip_name_,
+                               &cubin_mu_, &cubin_by_crc_};
+            engine_->initialize(opts_, ectx);
+            engine_->start();
+        } else {
+            GFL_LOG_ERROR("[CuptiBackend] Failed to get CUDA context; "
+                          "engine will not start.");
+        }
+    }
+
+    active_.store(true);
+    GFL_LOG_DEBUG("Backend started.");
+}
+
+void CuptiBackend::stop() {
+    if (!initialized_) return;
+    active_.store(false);
+
+    LogCuptiErrorIfFailed("Perfworks", "cuptiActivityFlushAll",
+                          cuptiActivityFlushAll(1));
+
+    {
+        std::set<CUpti_ActivityKind> kinds;
+        {
+            std::lock_guard<std::mutex> lk(handler_mu_);
+            for (const auto& h : handlers_)
+                for (auto k : h->requiredActivityKinds()) kinds.insert(k);
+        }
+        for (auto k : kinds) cuptiActivityDisable(k);
+    }
+
+    const uint64_t seen = kernel_activity_seen_.load(std::memory_order_relaxed);
+    const uint64_t emitted =
+        kernel_activity_emitted_.load(std::memory_order_relaxed);
+    const uint64_t throttled =
+        kernel_activity_throttled_.load(std::memory_order_relaxed);
+    GFL_LOG_DEBUG("[KernelLaunchHandler] activity summary seen=", seen,
+                  " emitted=", emitted, " throttled=", throttled);
+}
+
+void CuptiBackend::RegisterHandler(
+    const std::shared_ptr<ICuptiHandler>& handler) {
+    if (!handler) return;
+    std::lock_guard<std::mutex> lk(handler_mu_);
+    handlers_.push_back(handler);
+}
+
+// ---- Static callbacks ------------------------------------------------------
+
+void CUPTIAPI CuptiBackend::BufferRequested(uint8_t** buffer, size_t* size,
+                                            size_t* maxNumRecords) {
+    *size          = 64 * 1024;
+    *buffer        = static_cast<uint8_t*>(malloc(*size));
+    *maxNumRecords = 0;
+}
+
+void CUPTIAPI CuptiBackend::BufferCompleted(CUcontext context,
+                                            uint32_t streamId, uint8_t* buffer,
+                                            size_t size,
+                                            const size_t validSize) {
+    auto* backend = g_activeBackend.load(std::memory_order_acquire);
+    if (!backend) {
+        ::gpufl::DebugLogger::error("[CUPTI] ",
+                                    "BufferCompleted: No active backend!");
+        if (buffer) free(buffer);
+        return;
+    }
+
+    static int64_t  baseCpuNs   = detail::GetTimestampNs();
+    static uint64_t baseCuptiTs = 0;
+    if (baseCuptiTs == 0) cuptiGetTimestamp(&baseCuptiTs);
+
+    std::vector<std::shared_ptr<ICuptiHandler>> handlers;
+    {
+        std::lock_guard<std::mutex> lk(backend->handler_mu_);
+        handlers = backend->handlers_;
+    }
+
+    if (validSize > 0) {
+        CUpti_Activity* record = nullptr;
+        while (true) {
+            const CUptiResult st =
+                cuptiActivityGetNextRecord(buffer, validSize, &record);
+            if (st == CUPTI_SUCCESS) {
+                bool handled = false;
+                for (const auto& h : handlers) {
+                    if (h->handleActivityRecord(record, baseCpuNs,
+                                                baseCuptiTs)) {
+                        handled = true;
+                        break;
+                    }
+                }
+                if (!handled &&
+                    record->kind == CUPTI_ACTIVITY_KIND_PC_SAMPLING) {
+                    auto* pc =
+                        reinterpret_cast<CUpti_ActivityPCSampling3*>(record);
+                    ActivityRecord out{};
+                    out.type         = TraceType::PC_SAMPLE;
+                    out.corr_id      = pc->correlationId;
+                    std::snprintf(out.sample_kind, sizeof(out.sample_kind),
+                                  "%s", "pc_sampling");
+                    out.samples_count = pc->samples;
+                    out.stall_reason = pc->stallReason;
+                    out.device_id    =
+                        reinterpret_cast<const CUpti_ActivityKernel11*>(record)
+                            ->deviceId;
+                    g_monitorBuffer.Push(out);
+                }
+            } else if (st == CUPTI_ERROR_MAX_LIMIT_REACHED) {
+                break;
+            } else {
+                ::gpufl::DebugLogger::error("[CUPTI] ",
+                                            "Error parsing buffer: ", st);
+                break;
+            }
+        }
+    }
+
+    free(buffer);
+}
+
+void CuptiBackend::GflCallback(void* userdata, CUpti_CallbackDomain domain,
+                               CUpti_CallbackId cbid, const void* cbdata) {
+    if (!cbdata) return;
+
+    auto* backend = static_cast<CuptiBackend*>(userdata);
+    if (!backend) return;
+
+    std::vector<std::shared_ptr<ICuptiHandler>> handlers;
+    {
+        std::lock_guard<std::mutex> lk(backend->handler_mu_);
+        handlers = backend->handlers_;
+    }
+
+    bool apiHandled = false;
+
+    for (const auto& handler : handlers) {
+        if (handler->shouldHandle(domain, cbid)) {
+            if (domain == CUPTI_CB_DOMAIN_RUNTIME_API ||
+                domain == CUPTI_CB_DOMAIN_DRIVER_API) {
+                if (apiHandled) continue;
+                apiHandled = true;
+            }
+            handler->handle(domain, cbid, cbdata);
+        }
+    }
+}
+
+}  // namespace gpufl