Summary

indragiek/uniprof is a universal CPU profiler simplifying performance analysis for developers and AI agents. It provides a unified interface across diverse runtimes, enabling profiling without code changes or added dependencies, and automatically identifies performance bottlenecks.

How It Works

This tool acts as a meta-profiler, abstracting platform-specific tools by automatically detecting runtimes (Python, Node.js, Ruby, JVM, .NET, etc.) and selecting appropriate profilers (e.g., py-spy, 0x, async-profiler). It defaults to using pre-configured Docker containers for consistent, isolated environments, simplifying setup. An alternative --mode host allows using locally installed profilers. Outputs are normalized, and statistical analysis pinpoints bottlenecks.

Quick Start & Requirements

• Installation: npm install -g uniprof
• Requirements: macOS or Linux with Docker. WSL2 is supported on Windows, but native Windows executables cannot be profiled.
• Primary Command: npx uniprof <language> <script> (e.g., npx uniprof python app.py).
• Visualization: uniprof --visualize <language> <script> for immediate flamegraph viewing.
• Native Profiling: Requires applications compiled with DWARF debug info and frame pointers.

Highlighted Details

• Broad Language Support: Integrates profilers for Python, Node.js, Ruby, PHP, JVM, .NET, BEAM, and native Linux/macOS executables.
• Containerized Execution: Defaults to Docker for simplified setup and isolation.
• Host Mode: Option to use locally installed profiling tools.
• Flamegraph Visualization: Built-in capability to generate and display flamegraphs.
• AI Agent Compatibility: Designed for automated analysis by AI agents.

Maintenance & Community

The README credits underlying profilers but provides no details on active maintainers, community channels, or roadmaps.

Licensing & Compatibility

The uniprof core tooling is MIT licensed. Docker images bundle third-party profilers with their own licenses (MIT, Apache 2.0, GPL). Compatibility is primarily for macOS and Linux.

Limitations & Caveats

Windows hosts are not supported, nor is profiling native Windows executables via WSL2. Native macOS Mach-O binaries require host mode. Accurate native profiling depends on applications being compiled with debug symbols and frame pointers.