massif

README

massif

massif is a library for working with logs produced by massif, a tool contained in the Valgrind suite. This library can make it easy to do things like write an automated test to verify peak heap usage in a binary. The linked godoc contains usage examples.

Documentation

Overview

Package massif implements a basic (likely incomplete parser) for heap profiles generated by the Massif tool. Massif is part of the Valgrind suite of tools, more information can be found at: https://valgrind.org/docs/manual/ms-manual.html

See the examples for basic usage.

Example

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/joshkunz/massif"
)

func main() {
	// Load the example massif file off disk.
	f, err := os.Open("testdata/example.massif")
	if err != nil {
		log.Fatalf("failed to open testdata/example.massif: %v", err)
	}
	defer f.Close()

	parsed, err := massif.Parse(f)
	if err != nil {
		log.Fatalf("failed to parse testdata/example.massif: %v", err)
	}

	// Convert the Massif struct into JSON for display purposes only. This is
	// not required.
	display, err := json.MarshalIndent(parsed, "", "  ")
	if err != nil {
		log.Fatalf("failed to marshal Massif for display: %v", err)
	}

	fmt.Print(string(display))

}

Output:

{
  "Description": "--massif-out-file=./example.massif",
  "Binary": "example_binary",
  "Args": [
    "--option-one",
    "--option-two",
    "--flag=value"
  ],
  "TimeUnit": "i",
  "Snapshots": [
    {
      "Index": 0,
      "Time": "0",
      "MemoryHeap": 0,
      "MemoryHeapExtra": 0,
      "MemoryStack": 0,
      "HeapTree": ""
    },
    {
      "Index": 1,
      "Time": "103242501",
      "MemoryHeap": 8988696,
      "MemoryHeapExtra": 713576,
      "MemoryStack": 0,
      "HeapTree": "Note: This heap is snipped.\nn6: 1123587 (heap allocation functions) malloc/new/new[], --alloc-fns, etc.\n n0: 12558 in 28 places, all below massif's threshold (1.00%)"
    },
    {
      "Index": 2,
      "Time": "161677632",
      "MemoryHeap": 12931384,
      "MemoryHeapExtra": 1124552,
      "MemoryStack": 0,
      "HeapTree": "Note: This heap is snipped.\nn6: 1616423 (heap allocation functions) malloc/new/new[], --alloc-fns, etc.\n n0: 13839 in 28 places, all below massif's threshold (1.00%)"
    },
    {
      "Index": 3,
      "Time": "273947848",
      "MemoryHeap": 22066184,
      "MemoryHeapExtra": 1915064,
      "MemoryStack": 0,
      "HeapTree": ""
    }
  ]
}

Example (PeakUsage)

ExamplePeakUsage prints the peak memory usage found in the example massif run.

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/joshkunz/massif"
)

func main() {
	// Load the example massif file off disk.
	f, err := os.Open("testdata/example.massif")
	if err != nil {
		log.Fatalf("failed to open testdata/example.massif: %v", err)
	}
	defer f.Close()

	parsed, err := massif.Parse(f)
	if err != nil {
		log.Fatalf("failed to parse testdata/example.massif: %v", err)
	}

	var max *massif.Snapshot
	for _, snap := range parsed.Snapshots {
		if max == nil || snap.MemoryHeap > max.MemoryHeap {
			max = &snap
		}
	}

	fmt.Printf("Max memory usage of %.2f MiB in snapshot %d at time %s%s",
		max.MemoryHeap.Mebibytes(), max.Index, max.Time, parsed.TimeUnit)

}

Output:

Max memory usage of 2.63 MiB in snapshot 3 at time 273947848i

Index

• type Massif
  • func Parse(in io.Reader) (*Massif, error)
  • func (m *Massif) Serialize(out io.Writer) error
• type Snapshot

Examples

• Package
• Package (PeakUsage)

Types

type Massif

type Massif struct {
	Description string
	Binary      string
	Args        []string
	TimeUnit    string
	Snapshots   []Snapshot
}

Massif represents a parsed Massif output file. The fields in this struct correspond to the fields in the Massif file "header". Binary is the command that was run under Massif, and Args are any flags that were provided to the binary during analysis.

func Parse

func Parse(in io.Reader) (*Massif, error)

Parse parses a Massif file from the given reader, returning the parsed representation as a Massif structure, or an error if the input file could not be parsed.

func (*Massif) Serialize

func (m *Massif) Serialize(out io.Writer) error

Serialze writes this parsed Massif file into the given writer in the Massif file format. The written content should the be the same as the original file, modulo a trailing newline.

type Snapshot

type Snapshot struct {
	// Index is index of this snapshot in the Massif output file.
	Index int
	// Time is the raw repesentation of the time this snapshot was taken saved
	// in the Massif output file. The units of this file depend on
	// `Massif.TimeUnit`.
	Time            string
	MemoryHeap      unit.Datasize
	MemoryHeapExtra unit.Datasize
	MemoryStack     unit.Datasize
	// HeapTree is the raw representation of the "heap tree" included in the
	// output file.
	HeapTree string
}

Snapshot is the type of a "heap snapshot". Massif files are basically a sequence of these taken over the life of the program being analyzed.