Profiling

NYRA Framework GO Project

Use gperftools to profile your GO program’s CPU usage and heap memory usage. Below is how to set up the environment, run gperftools to collect performance data, and then analyze that data.

Installing gperftools

On Ubuntu, install gperftools with:

apt update && apt install -y google-perftools

ln -s /usr/lib/x86_64-linux-gnu/libtcmalloc.so.4 /usr/lib/libtcmalloc.so
ln -s /usr/lib/x86_64-linux-gnu/libprofiler.so.0 /usr/lib/libprofiler.so

Profiling CPU Usage with gperftools

  1. Preload tcmalloc

    export LD_PRELOAD=/usr/lib/libtcmalloc.so
export CPUPROFILE=/.../cpu

exec /.../program

    When /.../program exits, it writes CPU performance data to /.../cpu.0001.prof.

  2. Periodic CPU Profiling If you want to generate CPU performance data every 30 seconds:

    LD_PRELOAD=/usr/lib/libtcmalloc.so CPUPROFILE=/.../cpu CPUPROFILE_FREQUENCY=30 exec /.../program

Analyzing CPU Performance Data

google-pprof --text /.../program /.../cpu.0001.prof > /.../cpu.0001.prof.txt

google-pprof --text --base=/.../cpu.0001.prof /.../program /.../cpu.0002.prof > /.../diff.txt

  • The first command converts /.../cpu.0001.prof to a human-readable text file.

  • The second command compares /.../cpu.0001.prof and /.../cpu.0002.prof, saving the diff to /.../diff.txt.

Profiling Heap Memory Usage with gperftools

  1. Preload tcmalloc

    export LD_PRELOAD=/usr/lib/libtcmalloc.so
export HEAPPROFILE=/.../heap
export HEAP_PROFILE_TIME_INTERVAL=30

exec /.../program

    • HEAP_PROFILE_TIME_INTERVAL=30 instructs the runtime to capture heap data every 30 seconds.

    • All .heap data is saved under the path specified in HEAPPROFILE.

Analyzing Heap Memory Performance Data

Each .heap file contains heap usage snapshots. Convert them to a readable format:

google-pprof --text /.../program /.../heap.0001.heap > /.../heap.0001.heap.txt

Example output (truncated):

Total: 19.7 MB
16.0  81.3%  81.3%     16.0  81.3% lws_zalloc
2.9   14.6%  95.9%      3.3  16.7% setAgoraStreamChannelParameters
...

You can also convert .heap files to PDF or SVG for graphical analysis:

google-pprof --pdf /.../program /.../heap.0001.heap > /.../heap.0001.heap.pdf

Comparing Two Heap Snapshots

google-pprof --pdf --base=/.../heap.0001.heap /.../program /.../heap.0002.heap > /.../diff.pdf

Generates a PDF showing differences in heap usage between the two snapshots.

Analyzing Multiple Heap Files

If you periodically generate heap .heap files, you can run:

python3 tools/profiler/gperftools/dump_heap_info_to_excel.py -heap_dir=/.../heap -bin=/.../program -output=/.../heap.xlsx -sample_interval=30

This script:

  • Generates raw performance data in /.../raw/

  • Converts data to human-readable text in /.../text/

  • Produces an Excel file (/.../heap.xlsx)

You can then plot a line chart showing heap trends:

python3 tools/profiler/gperftools/draw_line_chart.py -excel_file=/.../heap.xlsx -output_file=/.../heap_line_chart.png -title=HEAP_MEM -x=time/s -y=total_heap_size/MB

Profiling with pprof (Go-Specific)

We recommend using pprof for Go-based NYRA programs. The easiest way is to use pprof_app_go as your NYRA application. When activated, it reads these environment variables:

export NYRA_HEAP_DUMP_DIR=/data/prof
export HEAP_PROFILE_TIME_INTERVAL=30
export NYRA_PROFILER_SERVER_PORT=6060

  • NYRA_HEAP_DUMP_DIR – Directory to store heap dumps.

  • HEAP_PROFILE_TIME_INTERVAL – Interval for snapshots.

  • NYRA_PROFILER_SERVER_PORT – Port for the pprof server.

Analyzing pprof Performance Data

  1. Convert heap data to text:

    python3 tools/profiler/pprof/dump_heap_files_to_text.py -heap_dir=/data/prof -text_dir=/data/text

  2. Generate an Excel summary:

    python3 tools/profiler/pprof/dump_heap_info_to_excel.py -heap_dir=/data/prof -output=/data/heap.xlsx

  3. Plot a line chart:

    python3 tools/profiler/gperftools/draw_line_chart.py -excel_file=/data/heap.xlsx -output_file=/data/heap_line_chart.png -title=HEAP_MEM -x=time/s -y=total_heap_size/MB

This will produce a visual representation of Go heap usage trends, helping you pinpoint memory bottlenecks or leaks.

PreviousDebuggingNextDependencies

Last updated