GPUFlight Docs
Deep GPU kernel diagnostics for development. Continuous, low-overhead profiling for production.
Switch modes with one environment variable. Supports NVIDIA CUDA and AMD ROCm.
Quick start
1. Add to your build
CMakeLists.txt
# CMakeLists.txt
include(FetchContent)
FetchContent_Declare(gpufl
GIT_REPOSITORY https://github.com/gpu-flight/gpufl-client.git
GIT_TAG main)
FetchContent_MakeAvailable(gpufl)
target_link_libraries(my_app PRIVATE gpufl::gpufl)
2. Pick how data reaches the dashboard
- Direct HTTP (in-process)
- gpufl-agent (sidecar)
Your application uploads telemetry live via a background thread — HttpLogSink. Best for local dev, SSH, and Jupyter. One process, no daemon.
main.cpp
#include "gpufl/gpufl.hpp"
int main() {
gpufl::InitOptions opts;
opts.app_name = "my_app";
opts.log_path = "/tmp/runs/my_app";
opts.backend_url = "https://api.gpuflight.com";
opts.api_key = std::getenv("GPUFL_API_KEY");
gpufl::init(opts);
// ... your CUDA / HIP work ...
gpufl::shutdown();
// Deferred upload — post-shutdown, never during the workload.
gpufl::UploadOptions uopts;
uopts.log_path = opts.log_path;
uopts.backend_url = opts.backend_url;
uopts.api_key = opts.api_key;
gpufl::uploadLogs(uopts);
}
Your application writes NDJSON files only; gpufl-agent is a JVM (Java 25) sidecar that tails those files and publishes them via HTTP or Kafka. Best for production, multi-process workloads, durable delivery across restarts, and Kafka-based pipelines.
main.cpp
#include "gpufl/gpufl.hpp"
int main() {
gpufl::InitOptions opts;
opts.app_name = "my_app";
opts.log_path = "/var/log/gpuflight/my_app.system.log";
gpufl::init(opts); // gpufl-agent will tail the log file
// ... your CUDA / HIP work ...
gpufl::shutdown();
}
Option A — Docker (zero JDK install)
docker run gpufl-agent
# Once per host (or as a Kubernetes DaemonSet)
docker run -d --name gpufl-agent \
-v /var/log/gpuflight:/var/log/gpuflight \
-e GPUFL_SOURCE_FOLDERS=/var/log/gpuflight \
-e GPUFL_PUBLISHER_TYPE=http \
-e GPUFL_HTTP_HOST=https://api.gpuflight.com \
-e GPUFL_HTTP_TOKEN=$GPUFL_API_KEY \
ghcr.io/gpu-flight/gpufl-agent:latest
Option B — Java directly (no Docker)
java -jar gpufl-agent
# Build the fat JAR (Java 25 required — Gradle auto-downloads)
git clone https://github.com/gpu-flight/gpufl-agent
cd gpufl-agent
./gradlew shadowJar
# → build/libs/gpuflight-agent-1.0-SNAPSHOT-all.jar
# Run it (foreground; use systemd / nohup for production)
java -jar build/libs/gpuflight-agent-1.0-SNAPSHOT-all.jar \
--folders=/var/log/gpuflight \
--type=http \
--host=https://api.gpuflight.com \
--token=$GPUFL_API_KEY