instruments

README

Instruments

A small golang library that allows you to send signals to Instruments.app to indicate interesting points or regions, modeled after the Ruby library by Alloy

For more info about Instruments and the ‘Points of Interest’ instrument, see these slides.

Note that this uses the kdebug_signpost API, which is only available since macOS 10.12.

Example

Consider the following process:

package main

import (
	"fmt"
	"time"

	"github.com/nicolai86/instruments"
)

func main() {
	fmt.Printf("Hello world\n")
	time.Sleep(10 * time.Second)

	go func() {
		<-time.After(1 * time.Second)
		instruments.Signpost(42)
	}()

	region := instruments.StartWithArguments(43, 0, 0, 0, instruments.ColorPurple)

	time.Sleep(5 * time.Second)

	region.End()
}

When attaching Instruments.app using the ‘Points of Interest’ instrument you’d get the following:

Documentation

Overview

Package instruments allows you to send signals to Instruments.app to indicate interesting points or regions

Index

• Constants
• func Signpost(action int32)
• func SignpostWithArguments(action, arg1, arg2, arg3, arg4 int32)
• type Region
  • func Start(action int32) Region
  • func StartWithArguments(action, arg1, arg2, arg3, arg4 int32) Region
  • func (r Region) End()

Constants

const (
	// ColorBlue allows Instruments to highlight a point or region in blue
	ColorBlue int32 = iota
	// ColorBlue allows Instruments to highlight a point or region in green
	ColorGreen int32 = 1
	// ColorBlue allows Instruments to highlight a point or region in purple
	ColorPurple int32 = 2
	// ColorBlue allows Instruments to highlight a point or region in orange
	ColorOrange int32 = 3
	// ColorBlue allows Instruments to highlight a point or region in red
	ColorRed int32 = 4
)

https://opensource.apple.com/source/xnu/xnu-3789.21.4/bsd/sys/kdebug_signpost.h.auto.html

Functions

func Signpost

func Signpost(action int32)

Signpost creates a single point of interest

func SignpostWithArguments

func SignpostWithArguments(action, arg1, arg2, arg3, arg4 int32)

SignpostWithArguments creates a single point of interest, allowing you to specifiy all arguments

Types

type Region

type Region struct {
	Action int32
	Arg1   int32
	Arg2   int32
	Arg3   int32
	Arg4   int32
}

Region describes an active region

func Start

func Start(action int32) Region

Start marks the beginning of a Region

func StartWithArguments

func StartWithArguments(action, arg1, arg2, arg3, arg4 int32) Region

StartWithArguments marks the beginning of a Region, allowing you to specifiy all arguments

func (Region) End

func (r Region) End()

End marks the ending of a Region