flamegraph-textual 0.1.0

Terminal flamegraph renderer built for Textual

flamegraph-textual

flamegraph-textual is an interactive flamegraph component for Textual.

It is the rendering library extracted from flameshow. Use it when you want to embed a terminal flamegraph inside your own Textual app instead of launching a standalone viewer.

Install

pip install flamegraph-textual

What It Does

• Renders flamegraphs as a Textual widget
• Parses profile input for you
• Supports keyboard and mouse navigation
• Supports multiple sample types when present in the profile
• Works with bundled demo data or your own files

Quick Start

FlameGraphView is the main entrypoint. Pass it raw profile data and a filename. The library parses the content internally.

from pathlib import Path

from textual.app import App, ComposeResult

from flamegraph_textual import FlameGraphView


class Demo(App):
    def compose(self) -> ComposeResult:
        profile_bytes = Path("profile.out").read_bytes()
        yield FlameGraphView(profile_bytes, filename="profile.out")


Demo().run()

For stackcollapse text input, passing str also works:

from pathlib import Path

from flamegraph_textual import FlameGraphView

profile_text = Path("stacks.txt").read_text(encoding="utf-8")
widget = FlameGraphView(profile_text, filename="stacks.txt")

Supported Input Formats

• pprof protobuf profiles
• stackcollapse text

The parser selection is automatic through: parse

Try It Immediately

This repo includes sample profiles under:

• tests/pprof_data
• tests/stackcollapse_data

Run the bundled examples with no setup:

python examples/pprof_binary.py
python examples/pprof_binary.py --sample goroutine
python examples/pprof_binary.py --sample heap

python examples/stackcollapse_text.py
python examples/stackcollapse_text.py --sample simple
python examples/stackcollapse_text.py --sample perf

You can still pass your own file path:

python examples/pprof_binary.py /path/to/profile.out
python examples/stackcollapse_text.py /path/to/stacks.txt

Main API

Most users only need:

• FlameGraphView
• parse

Other exports are available if you want lower-level control:

• FlameGraph
• FlameGraphScroll
• Frame
• Profile
• SampleType

See: init.py

Controls

Inside the widget:

• j / k / h / l or arrow keys move selection
• Enter zooms in
• Esc zooms out
• Tab switches sample type
• i opens the detail screen when mounted inside a Textual app
• Mouse hover updates frame details
• Mouse click zooms into a frame

Regenerate Protobuf Bindings

The canonical pprof schema lives in: profile.proto

The generated Python module lives in: profile_pb2.py

Regenerate it with:

poetry add --group dev grpcio-tools
poetry run python -m grpc_tools.protoc \
  -I proto \
  --python_out=flamegraph_textual/parsers \
  proto/profile.proto

Development

Run tests with:

pytest -q