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
```