0
# Parser System
1
2
Format-specific parsers for converting profiler output into gprof2dot's internal data model. The parser system supports 13+ different profiler formats including Linux perf, Valgrind callgrind, Python pstats, Java HPROF, and many others.
3
4
## Capabilities
5
6
### Base Parser Interface
7
8
Abstract base classes that define the parsing interface and provide common functionality for format-specific parsers.
9
10
```python { .api }
11
class Parser:
12
def __init__(self):
13
"""Initialize parser base class."""
14
15
def parse(self):
16
"""
17
Parse profiler output (abstract method).
18
19
Returns:
20
Profile: Parsed profile data
21
22
Raises:
23
NotImplementedError: Must be overridden by subclasses
24
"""
25
26
class LineParser(Parser):
27
"""Base class for line-based format parsers."""
28
29
def __init__(self, stream):
30
"""
31
Initialize line parser.
32
33
Args:
34
stream: File-like object to read from
35
"""
36
37
def readline(self):
38
"""Read next line from stream and update internal state."""
39
40
def lookahead(self):
41
"""
42
Look at current line without consuming it.
43
44
Returns:
45
str: Current line content
46
"""
47
48
def consume(self):
49
"""
50
Consume and return current line, advancing to next.
51
52
Returns:
53
str: Current line content
54
"""
55
56
def eof(self):
57
"""
58
Check if end of file reached.
59
60
Returns:
61
bool: True if at end of file
62
"""
63
64
class XmlParser(Parser):
65
"""Base class for XML-based format parsers."""
66
67
def parse(self, file):
68
"""Parse XML profiler output."""
69
70
class ParseError(Exception):
71
"""Exception raised when parsing fails."""
72
73
def __init__(self, message, filename=None, lineno=None):
74
"""
75
Initialize parse error.
76
77
Args:
78
message (str): Error description
79
filename (str, optional): Source filename
80
lineno (int, optional): Line number where error occurred
81
"""
82
```
83
84
### Python Profiler Support
85
86
Parser for Python's built-in profiling tools (cProfile, profile, pstats).
87
88
```python { .api }
89
class PstatsParser(Parser):
90
"""Parser for Python pstats module output."""
91
92
def parse(self, file):
93
"""
94
Parse Python pstats data.
95
96
Args:
97
file: Binary file containing pstats data
98
99
Returns:
100
Profile: Parsed profile with function call data
101
"""
102
```
103
104
### Valgrind Callgrind Support
105
106
Parser for Valgrind's callgrind tool output, providing detailed instruction-level profiling data.
107
108
```python { .api }
109
class CallgrindParser(Parser):
110
"""Parser for Valgrind's callgrind tool output."""
111
112
def parse(self, file):
113
"""
114
Parse callgrind output format.
115
116
Args:
117
file: Text file containing callgrind data
118
119
Returns:
120
Profile: Parsed profile with instruction counts and call relationships
121
"""
122
```
123
124
### Linux Perf Support
125
126
Parser for Linux perf callgraph output, supporting both call stacks and call ratios methods.
127
128
```python { .api }
129
class PerfParser(LineParser):
130
"""Parser for Linux perf callgraph output."""
131
132
def parse(self, file):
133
"""
134
Parse perf script output.
135
136
Args:
137
file: Text file containing perf script data
138
139
Returns:
140
Profile: Parsed profile with sampling data
141
"""
142
```
143
144
### GNU gprof Support
145
146
Parser for traditional GNU gprof profiler output.
147
148
```python { .api }
149
class GprofParser(LineParser):
150
"""Parser for GNU gprof output."""
151
152
def parse(self, file):
153
"""
154
Parse gprof flat and call graph output.
155
156
Args:
157
file: Text file containing gprof data
158
159
Returns:
160
Profile: Parsed profile with timing and call data
161
"""
162
```
163
164
### Java HPROF Support
165
166
Parser for Java HPROF profiler output format.
167
168
```python { .api }
169
class HProfParser(LineParser):
170
"""Parser for Java HPROF output."""
171
172
def parse(self, file):
173
"""
174
Parse HPROF format data.
175
176
Args:
177
file: Text file containing HPROF data
178
179
Returns:
180
Profile: Parsed profile with Java method call data
181
"""
182
```
183
184
### Intel VTune Support
185
186
Parser for Intel VTune Amplifier XE gprof-compatible output.
187
188
```python { .api }
189
class AXEParser(LineParser):
190
"""Parser for VTune Amplifier XE gprof-cc output."""
191
192
def parse(self, file):
193
"""
194
Parse VTune gprof-cc format.
195
196
Args:
197
file: Text file containing VTune data
198
199
Returns:
200
Profile: Parsed profile with performance counter data
201
"""
202
```
203
204
### OProfile Support
205
206
Parser for OProfile callgraph output format.
207
208
```python { .api }
209
class OprofileParser(LineParser):
210
"""Parser for OProfile callgraph output."""
211
212
def parse(self, file):
213
"""
214
Parse OProfile data.
215
216
Args:
217
file: Text file containing OProfile callgraph data
218
219
Returns:
220
Profile: Parsed profile with sampling data
221
"""
222
```
223
224
### Sysprof Support
225
226
Parser for Sysprof XML output format.
227
228
```python { .api }
229
class SysprofParser(XmlParser):
230
"""Parser for Sysprof XML output."""
231
232
def parse(self, file):
233
"""
234
Parse Sysprof XML format.
235
236
Args:
237
file: XML file containing Sysprof data
238
239
Returns:
240
Profile: Parsed profile with system-wide profiling data
241
"""
242
```
243
244
### Windows XPerf Support
245
246
Parser for Windows XPerf CSV output format.
247
248
```python { .api }
249
class XPerfParser(LineParser):
250
"""Parser for XPerf CSV output."""
251
252
def parse(self, file):
253
"""
254
Parse XPerf CSV format.
255
256
Args:
257
file: CSV file containing XPerf data
258
259
Returns:
260
Profile: Parsed profile with Windows performance data
261
"""
262
```
263
264
### Very Sleepy Support
265
266
Parser for Very Sleepy profiler output format.
267
268
```python { .api }
269
class SleepyParser(LineParser):
270
"""Parser for Very Sleepy output."""
271
272
def parse(self, file):
273
"""
274
Parse Very Sleepy format.
275
276
Args:
277
file: Text file containing Very Sleepy data
278
279
Returns:
280
Profile: Parsed profile with function timing data
281
"""
282
```
283
284
### DTrace Support
285
286
Parser for DTrace profiler output format.
287
288
```python { .api }
289
class DtraceParser(LineParser):
290
"""Parser for DTrace output."""
291
292
def parse(self, file):
293
"""
294
Parse DTrace format.
295
296
Args:
297
file: Text file containing DTrace data
298
299
Returns:
300
Profile: Parsed profile with system call tracing data
301
"""
302
```
303
304
### FlameGraph Support
305
306
Parser for FlameGraph stackcollapse format.
307
308
```python { .api }
309
class CollapseParser(LineParser):
310
"""Parser for FlameGraph stackcollapse output."""
311
312
def parse(self, file):
313
"""
314
Parse stackcollapse format.
315
316
Args:
317
file: Text file containing collapsed stack traces
318
319
Returns:
320
Profile: Parsed profile optimized for flame graph visualization
321
"""
322
```
323
324
### JSON Format Support
325
326
Parser for gprof2dot's custom JSON profile format.
327
328
```python { .api }
329
class JsonParser(Parser):
330
"""Parser for custom JSON profile format."""
331
332
def parse(self, file):
333
"""
334
Parse JSON profile format.
335
336
Args:
337
file: JSON file containing profile data
338
339
Returns:
340
Profile: Parsed profile from JSON representation
341
"""
342
```
343
344
### XML Processing Support
345
346
Low-level XML processing utilities used by XML-based parsers.
347
348
```python { .api }
349
class XmlTokenizer:
350
"""Expat-based XML tokenizer for streaming XML parsing."""
351
352
def __init__(self, fp):
353
"""
354
Initialize XML tokenizer.
355
356
Args:
357
fp: File-like object containing XML data
358
"""
359
360
def get(self):
361
"""
362
Get the next XML token.
363
364
Returns:
365
XmlToken: Next token or XML_EOF
366
"""
367
368
class XmlToken:
369
"""Represents an XML token (element, text, etc.)."""
370
371
def __init__(self, type, name_or_data, attrs=None):
372
"""
373
Initialize XML token.
374
375
Args:
376
type: Token type (XML_ELEMENT_START, XML_ELEMENT_END, etc.)
377
name_or_data: Element name or character data
378
attrs (dict, optional): Element attributes
379
"""
380
381
class XmlTokenMismatch(Exception):
382
"""Exception for XML parsing mismatches."""
383
```
384
385
## Format Selection
386
387
The parser system uses a format registry to map format names to parser classes:
388
389
```python { .api }
390
formats = {
391
'axe': AXEParser,
392
'callgrind': CallgrindParser,
393
'collapse': CollapseParser,
394
'dtrace': DtraceParser,
395
'hprof': HProfParser,
396
'json': JsonParser,
397
'oprofile': OprofileParser,
398
'perf': PerfParser,
399
'prof': GprofParser,
400
'pstats': PstatsParser,
401
'sleepy': SleepyParser,
402
'sysprof': SysprofParser,
403
'xperf': XPerfParser
404
}
405
```
406
407
## Usage Examples
408
409
### Parsing Different Formats
410
411
```python
412
import gprof2dot
413
414
# Parse Python pstats file
415
parser = gprof2dot.PstatsParser()
416
with open('profile.stats', 'rb') as f:
417
profile = parser.parse(f)
418
419
# Parse Valgrind callgrind output
420
parser = gprof2dot.CallgrindParser()
421
with open('callgrind.out.1234', 'r') as f:
422
profile = parser.parse(f)
423
424
# Parse Linux perf output
425
parser = gprof2dot.PerfParser()
426
with open('perf.out', 'r') as f:
427
profile = parser.parse(f)
428
```
429
430
### Dynamic Parser Selection
431
432
```python
433
import gprof2dot
434
435
def parse_profile(filename, format_name):
436
"""Parse a profile file using the specified format."""
437
parser_class = gprof2dot.formats[format_name]
438
parser = parser_class()
439
440
mode = 'rb' if format_name == 'pstats' else 'r'
441
with open(filename, mode) as f:
442
return parser.parse(f)
443
444
# Usage
445
profile = parse_profile('callgrind.out.1234', 'callgrind')
446
profile = parse_profile('profile.stats', 'pstats')
447
```
448
449
### Error Handling
450
451
```python
452
import gprof2dot
453
454
try:
455
parser = gprof2dot.PstatsParser()
456
with open('corrupted.stats', 'rb') as f:
457
profile = parser.parse(f)
458
except gprof2dot.ParseError as e:
459
print(f"Parse error: {e}")
460
if e.filename:
461
print(f"File: {e.filename}")
462
if e.lineno:
463
print(f"Line: {e.lineno}")
464
```