0
# gprof2dot
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: gprof2dot
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install gprof2dot`
10
- **Requirements**: Python ≥3.8, GraphViz
11

12
## Core Imports
13

14
As a command-line tool:
15
```bash
16
gprof2dot -f callgrind callgrind.out.1234 | dot -Tpng -o output.png
17
```
18

19
As a Python module:
20
```python
21
import gprof2dot
22

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

26
# Generate dot graph  
27
dot_writer = gprof2dot.DotWriter(sys.stdout)
28
dot_writer.graph(profile, gprof2dot.TEMPERATURE_COLORMAP)
29
```
30

31
## Basic Usage
32

33
### Command Line Usage
34

35
```bash
36
# Parse Python pstats output
37
gprof2dot -f pstats profile.stats | dot -Tpng -o profile.png
38

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

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

45
# Use different color themes
46
gprof2dot -f callgrind -c pink callgrind.out | dot -Tpng -o profile.png
47
```
48

49
### Programmatic Usage
50

51
```python
52
import gprof2dot
53
import sys
54

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

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

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

66
# Generate dot output
67
theme = gprof2dot.TEMPERATURE_COLORMAP
68
dot_writer = gprof2dot.DotWriter(sys.stdout)
69
dot_writer.graph(profile, theme)
70
```
71

72
## Architecture
73

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

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

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

84
## Capabilities
85

86
### Profile Data Model
87

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

90
```python { .api }
91
class Profile:
92
    def add_function(self, function): ...
93
    def add_cycle(self, cycle): ...
94
    def prune(self, node_thres, edge_thres, paths, color_nodes_by_selftime): ...
95
    def validate(self): ...
96
    def find_cycles(self): ...
97

98
class Function:
99
    def add_call(self, call): ...
100
    def get_call(self, callee_id): ...
101
    def stripped_name(self): ...
102

103
class Call:
104
    def __init__(self, callee_id): ...
105
```
106

107
[Profile Data Model](./profile-model.md)
108

109
### Parser System
110

111
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.
112

113
```python { .api }
114
class Parser:
115
    def parse(self): ...
116

117
class PstatsParser(Parser): ...
118
class CallgrindParser(Parser): ...
119
class PerfParser(Parser): ...
120
class HProfParser(Parser): ...
121
```
122

123
[Parser System](./parsers.md)
124

125
### Visualization System
126

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

129
```python { .api }
130
class DotWriter:
131
    def graph(self, profile, theme): ...
132
    def node(self, node, **attrs): ...
133
    def edge(self, src, dst, **attrs): ...
134

135
class Theme:
136
    def node_bgcolor(self, weight): ...
137
    def edge_color(self, weight): ...
138
    def node_fontsize(self, weight): ...
139
    def edge_penwidth(self, weight): ...
140
```
141

142
[Visualization System](./visualization.md)
143

144
### Command Line Interface
145

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

148
```python { .api }
149
def main(argv=sys.argv[1:]):
150
    """
151
    Main entry point for command-line interface.
152
    
153
    Args:
154
        argv (list): Command line arguments
155
    """
156
```
157

158
[Command Line Interface](./cli.md)
159

160
## Types
161

162
### Event Types
163

164
```python { .api }
165
CALLS: Event                # Call count events
166
SAMPLES: Event              # Sample count events  
167
SAMPLES2: Event             # Alternative sample count events
168
TOTAL_SAMPLES: Event        # Total samples for callstack method
169
TIME: Event                 # Time events
170
TIME_RATIO: Event           # Time ratio events  
171
TOTAL_TIME: Event           # Total time events
172
TOTAL_TIME_RATIO: Event     # Total time ratio events
173
```
174

175
### Configuration Dictionaries
176

177
```python { .api }
178
formats: dict         # Maps format names to parser classes (keys: 'prof', 'pstats', 'callgrind', etc.)
179
themes: dict          # Maps theme names to Theme objects
180
labels: dict          # Maps label names to Event objects
181
```
182

183
### Predefined Themes
184

185
```python { .api }
186
TEMPERATURE_COLORMAP: Theme    # Blue to red color scheme
187
PINK_COLORMAP: Theme          # Pink to red color scheme
188
GRAY_COLORMAP: Theme          # Grayscale color scheme
189
BW_COLORMAP: Theme            # Black and white scheme
190
PRINT_COLORMAP: Theme         # Print-friendly scheme
191
```