uniprof

uniprof

uniprof を使うと、人や AI エージェント向けの CPU プロファイリングを簡単に行えます。コードの変更や依存関係の追加なしに、あらゆるアプリケーションをプロファイリングできます。

# Profile and analyze any app in one step
npx uniprof python script.py

目次

• 対応プラットフォーム
• システム要件
• インストール
  • MCP サーバー
• クイックスタート
  • ホストモードとコンテナモード
• デバッグ情報を付けたコンパイル
• ドキュメント
• クレジット
• ライセンス

対応プラットフォーム

uniprof は、異なるプラットフォームやランタイムに特化した複数のプロファイラーに対して、共通のインターフェイスを実装しています。実行するコマンドに基づいて使用するプロファイラーを自動検出し、プロファイラーを実行して、形式の異なる出力を単一の形式に変換し、データの統計分析を行ってホットスポットを特定します。

プラットフォーム	プロファイラー	コンテナ	ホスト	最小バージョン
Python	py-spy	✅	✅	Python 3.7+
Node.js	0x	✅	✅	Node 14+
Ruby	rbspy	✅	✅	Ruby 2.5+
PHP	Excimer	✅	✅	PHP 7.2+
JVM	async-profiler	✅	✅	Java 8+
.NET	dotnet-trace	✅	✅	.NET 5+
BEAM	perf	✅	✅*	OTP 24+
ネイティブ（macOS）	Instruments	❌	✅	Xcode 14.3+
ネイティブ（Linux）	perf	✅	✅	Linux 2.6.31+

* ホストモードは Linux のみ

システム要件

要約： Docker がインストールされた macOS または Linux

uniprof は macOS と Linux で動作するように設計されていますが、主に macOS で開発・テストされています。Linux で実行中にバグを見つけた場合は、報告してください。Windows ホストでの実行は現在サポートされていませんが、WSL2 を使って Windows 上にインストールした Linux で実行できます。WSL2 経由で uniprof を使用する場合、ネイティブの Windows 実行ファイルのプロファイリングはサポートされていません。ただし、Python や Node.js などの高級言語ランタイム向けのプロファイラーは引き続き使用できます。

プロファイリングツールは、正しくセットアップするのが難しい場合が多く、昇格された権限が必要になることもあります。セットアップを簡単にし、プロファイリング対象のコードをより適切に分離するため、uniprof は各ランタイム向けに特定のプロファイリングツールを実行するよう事前設定された Docker コンテナをデフォルトで使用します。uniprof は作業領域をコンテナにマウントし、プロファイラーを接続した状態でプログラムを実行します。また、ホストシステムにプロファイリングツールがインストールされている場合は、--mode host フラグを指定してコンテナ外でプロファイリングすることもできます。コンテナ内での実行がサポートされないのは、macOS 上でネイティブの Mach-O バイナリをプロファイリングする場合のみです。Apple Instruments はコンテナ内で実行できないためです。

インストール

npm install -g uniprof

MCP サーバー

# Install uniprof MCP server automatically
uniprof mcp install claudecode
uniprof mcp install cursor
uniprof mcp install vscode

自動インストールに対応しているクライアント： amp、claudecode、codex、cursor、gemini、vscode、zed

お使いのクライアントで自動インストールがサポートされていない場合は、stdio トランスポートを使用する MCP サーバーを、コマンド npx -y uniprof mcp run で追加してください。

MCP の詳細なドキュメントについては、docs/mcp.md を参照してください。

クイックスタート

プロファイリングと分析を一度に実行する場合：

# Profile most languages and get immediate analysis
uniprof python app.py
uniprof node server.js
uniprof ruby script.rb
uniprof java -jar myapp.jar
uniprof dotnet MyApp.dll
uniprof ./my-native-app

# Profile and visualize flamegraph in browser
uniprof --visualize python app.py

後から分析・可視化するためにプロファイルを保存する場合：

# 1. Check environment (optional)
uniprof bootstrap

# 2. Record a profile
uniprof record -o profile.json -- python app.py
uniprof record -o profile.json -- node server.js
uniprof record -o profile.json -- ruby script.rb
uniprof record -o profile.json -- php script.php
uniprof record -o profile.json -- java -jar myapp.jar
uniprof record -o profile.json -- ./gradlew run
uniprof record -o profile.json -- ./mvnw spring-boot:run
uniprof record -o profile.json -- dotnet MyApp.dll
uniprof record -o profile.json -- elixir script.exs
uniprof record -o profile.json -- mix run
uniprof record -o profile.json -- ./my-native-app
uniprof record -o profile.json -- /Applications/MyApp.app

# 3. Analyze profile data to find hotspots
uniprof analyze profile.json

# 4. Visualize flamegraph in the browser
uniprof visualize profile.json

コマンドラインオプションの詳細なドキュメントについては、docs/cli.md を参照してください。

ホストモードとコンテナーモード

--mode オプションを使用して、プロファイリングの実行方法を制御します。

• auto（デフォルト）：Docker が利用可能な場合はコンテナーモードを優先し、それ以外の場合はホストモードを使用します。
  • 言語ランタイム（Python／Node.js／Ruby／PHP／BEAM／JVM／.NET）では、セットアップ不要のコンテナーモードがデフォルトです。
  • macOS 上で Mach-O バイナリを使用するネイティブコードの場合は、ホスト（Instruments）を使用します。macOS 上の ELF バイナリはコンテナーモードでサポートされています。
  • Linux 上のネイティブコードでは、コンテナーモードがデフォルトです。ローカルの perf セットアップを使用したい場合は、ホストモードも使用できます。
• host：ホストにインストールされたプロファイラーを強制的に使用します。
• container：Docker コンテナーを強制的に使用します（macOS Instruments／Mach-O バイナリではサポートされていません）。

# Auto mode (default)
uniprof record -o profile.json -- python script.py

# Force host profilers
uniprof record --mode host -o profile.json -- python script.py

# Force container mode
uniprof record --mode container -o profile.json -- ./my-linux-app

デバッグ情報を含めたコンパイル

ネイティブプロファイリングで有意義な結果を得るには、デバッグ情報が必要です。デバッグシンボルを使用すると、プロファイラーがメモリアドレスを関数名に対応付け、16 進数のアドレスだけでなく、読みやすい出力を表示できます。また、フレームポインターを使用すると、特に最適化されたコードでコールスタックの精度が向上します。

コンパイラー	DWARF デバッグ情報	フレームポインター	備考
gcc	gcc -g -o myapp main.c	gcc -fno-omit-frame-pointer -o myapp main.c	最大限のデバッグ情報には -g3、GDB 固有の拡張機能には -ggdb を使用します
clang	clang -g -o myapp main.cpp	clang -fno-omit-frame-pointer -o myapp main.cpp	macOS で完全なデバッグ情報を含めるには -gfull を使用します
swift	swiftc -g main.swift	swiftc -Xcc -fno-omit-frame-pointer main.swift	swift build では、デバッグビルドにシンボルがデフォルトで含まれます
cargo	cargo build（デバッグモード） cargo build --release + [profile.release] debug = true	RUSTFLAGS="-C force-frame-pointers=yes" cargo build	デバッグビルドにはデフォルトで DWARF が含まれます。リリースビルドでは、Cargo.toml に debug = true を追加します
go	go build -gcflags=all="-N -l"	組み込みで常に有効	Go にはデフォルトでデバッグ情報が含まれます。デバッグを改善するには、-gcflags で最適化を無効にします
zig	zig build-exe -O Debug main.zig	zig build-exe -fno-omit-frame-pointer main.zig	シンボルを含む最適化済みビルドには、デバッグ情報付きで -O ReleaseSafe を使用します
ghc	ghc -g -rtsopts main.hs	ghc -fno-omit-frame-pointer main.hs	プロファイリングビルドには -prof を使用します。-rtsopts は実行時のプロファイリングオプションを有効にします

ドキュメント

• CLI リファレンス
• 高度な使い方
• プラットフォームガイド
• MCP サーバー

クレジット

• py-spy（MIT）は、Python のプロファイリングに使用されています。uniprof-python イメージに含まれています。
• 0x（MIT）は、Node.js のプロファイリングに使用されています。uniprof-nodejs イメージに含まれています。
• rbspy（MIT）は、Ruby のプロファイリングに使用されています。uniprof-ruby イメージに含まれています。
• Excimer（Apache 2.0）は、PHP のプロファイリングに使用されています。uniprof-php イメージに含まれています。
• async-profiler（Apache 2.0）は、JVM のプロファイリングに使用されています。uniprof-jvm イメージに含まれています。
• dotnet-trace（MIT）は、.NET のプロファイリングに使用されています。uniprof-dotnet イメージに含まれています。
• perf（GPL）は、Linux 上でのネイティブプロファイリングに使用されています。uniprof-native および uniprof-beam イメージに含まれています。
• speedscope（MIT）は uniprof にバンドルされており、フレームグラフの可視化に使用されています。

ライセンス

このリポジトリ内の uniprof のすべてのソースコードは、MIT License の下でライセンスされています。LICENSE を参照してください。

uniprof は、サードパーティ製ソフトウェアをバンドルした Docker イメージ をダウンロードして実行します。これらのイメージのビルドに使用される Dockerfile は containers/ にあります。これらのイメージとその内容は MIT ライセンスの対象ではなく、それぞれ独自のライセンスが適用されます。uniprof はこれらのコンポーネントに対する権利を付与せず、再ライセンスもしません。