or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.mdparsers.mdprofile-model.mdvisualization.md
tile.json

tessl/pypi-gprof2dot

Generate a dot graph from the output of several profilers.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gprof2dot@2024.6.x

To install, run

npx @tessl/cli install tessl/pypi-gprof2dot@2024.6.0

index.mddocs/

gprof2dot

A Python script to convert the output from many profilers into GraphViz dot graphs. gprof2dot serves as a universal profiler output visualization tool, supporting 13+ different profiler formats and providing intelligent graph pruning, color-coding for performance hotspots, and cross-platform compatibility.

Package Information

  • Package Name: gprof2dot
  • Package Type: pypi
  • Language: Python
  • Installation: pip install gprof2dot
  • Requirements: Python ≥3.8, GraphViz

Core Imports

As a command-line tool:

gprof2dot -f callgrind callgrind.out.1234 | dot -Tpng -o output.png

As a Python module:

import gprof2dot

# Parse profiler output
profile = gprof2dot.PstatsParser().parse(file_handle)

# Generate dot graph  
dot_writer = gprof2dot.DotWriter(sys.stdout)
dot_writer.graph(profile, gprof2dot.TEMPERATURE_COLORMAP)

Basic Usage

Command Line Usage

# Parse Python pstats output
gprof2dot -f pstats profile.stats | dot -Tpng -o profile.png

# Parse Valgrind callgrind output
gprof2dot -f callgrind callgrind.out.1234 | dot -Tsvg -o profile.svg

# Parse Linux perf output with custom thresholds
gprof2dot -f perf -n 1.0 -e 0.5 perf.out | dot -Tpdf -o profile.pdf

# Use different color themes
gprof2dot -f callgrind -c pink callgrind.out | dot -Tpng -o profile.png

Programmatic Usage

import gprof2dot
import sys

# Create parser for specific format
parser = gprof2dot.PstatsParser()

# Parse profiler output
with open('profile.stats', 'rb') as f:
    profile = parser.parse(f)

# Apply graph transformations
profile.prune(0.005, 0.001)  # node_thres=0.5%, edge_thres=0.1%
profile.validate()

# Generate dot output
theme = gprof2dot.TEMPERATURE_COLORMAP
dot_writer = gprof2dot.DotWriter(sys.stdout)
dot_writer.graph(profile, theme)

Architecture

gprof2dot uses a multi-layered architecture for processing profiler data:

  • Model Layer: Core data structures (Profile, Function, Call, Cycle) representing the call graph
  • Parser Layer: Format-specific parsers for 13+ profiler output formats
  • Processing Layer: Graph analysis, cycle detection, pruning, and time propagation algorithms
  • Output Layer: DOT language generation with customizable themes and styling
  • CLI Layer: Command-line interface with extensive configuration options

This design enables universal profiler support while maintaining flexibility for both command-line and programmatic usage.

Capabilities

Profile Data Model

Core classes representing profiler data structures including profiles, functions, calls, and cycles. These provide the foundation for all profiler data manipulation and analysis.

class Profile:
    def add_function(self, function): ...
    def add_cycle(self, cycle): ...
    def prune(self, node_thres, edge_thres, paths, color_nodes_by_selftime): ...
    def validate(self): ...
    def find_cycles(self): ...

class Function:
    def add_call(self, call): ...
    def get_call(self, callee_id): ...
    def stripped_name(self): ...

class Call:
    def __init__(self, callee_id): ...

Profile Data Model

Parser System

Format-specific parsers for converting profiler output into gprof2dot's internal data model. Supports Linux perf, Valgrind callgrind, Python pstats, Java HPROF, and 9+ other formats.

class Parser:
    def parse(self): ...

class PstatsParser(Parser): ...
class CallgrindParser(Parser): ...
class PerfParser(Parser): ...
class HProfParser(Parser): ...

Parser System

Visualization System

DOT language generation with customizable themes, color schemes, and graph styling for creating publication-quality profiler visualizations.

class DotWriter:
    def graph(self, profile, theme): ...
    def node(self, node, **attrs): ...
    def edge(self, src, dst, **attrs): ...

class Theme:
    def node_bgcolor(self, weight): ...
    def edge_color(self, weight): ...
    def node_fontsize(self, weight): ...
    def edge_penwidth(self, weight): ...

Visualization System

Command Line Interface

Complete command-line interface with extensive options for format selection, threshold configuration, theming, and output control.

def main(argv=sys.argv[1:]):
    """
    Main entry point for command-line interface.
    
    Args:
        argv (list): Command line arguments
    """

Command Line Interface

Types

Event Types

CALLS: Event                # Call count events
SAMPLES: Event              # Sample count events  
SAMPLES2: Event             # Alternative sample count events
TOTAL_SAMPLES: Event        # Total samples for callstack method
TIME: Event                 # Time events
TIME_RATIO: Event           # Time ratio events  
TOTAL_TIME: Event           # Total time events
TOTAL_TIME_RATIO: Event     # Total time ratio events

Configuration Dictionaries

formats: dict         # Maps format names to parser classes (keys: 'prof', 'pstats', 'callgrind', etc.)
themes: dict          # Maps theme names to Theme objects
labels: dict          # Maps label names to Event objects

Predefined Themes

TEMPERATURE_COLORMAP: Theme    # Blue to red color scheme
PINK_COLORMAP: Theme          # Pink to red color scheme
GRAY_COLORMAP: Theme          # Grayscale color scheme
BW_COLORMAP: Theme            # Black and white scheme
PRINT_COLORMAP: Theme         # Print-friendly scheme