signpost

Documentation

Overview

Package signpost emits os_signpost intervals and events for use with Instruments and the unified logging system.

The os_signpost interval and event operations are C macros in <os/signpost.h>, not exported functions, so applegen cannot generate bindings for them: there is no symbol to resolve at runtime. This package is a hand-written overlay that reproduces what the macros expand to, calling the underlying exported _os_signpost_emit_with_name_impl symbol directly through purego.

Signposts carry no formatted message here: the format buffer that the C macros build at compile time via __builtin_os_log_format is omitted. Names and interval pairing are preserved, which is what interval timing in Instruments and "log stream --signpost" rely on.

Basic usage:

log := signpost.New("com.example.app", signpost.PointsOfInterest)
id := log.NewID()
log.IntervalBegin(id, "load")
// ... work ...
log.IntervalEnd(id, "load")

Example

Emit a named interval around a unit of work. Run the program under "log stream --signpost" or record it with Instruments to see the interval.

package main

import (
	"github.com/tmc/apple/x/signpost"
)

func main() {
	log := signpost.New("com.example.app", signpost.PointsOfInterest)

	id := log.NewID()
	log.IntervalBegin(id, "load")
	// ... do work ...
	log.IntervalEnd(id, "load")
}

Index

• Constants
• type ID
• type Logger
  • func New(subsystem, category string) *Logger
  • func (l *Logger) Enabled() bool
  • func (l *Logger) Event(id ID, name string)
  • func (l *Logger) IntervalBegin(id ID, name string)
  • func (l *Logger) IntervalEnd(id ID, name string)
  • func (l *Logger) NewID() ID
• type Type

Examples

• Package
• Logger.Event

Constants

const (
	// PointsOfInterest is the category Instruments displays in the Points of
	// Interest track. It maps to OS_LOG_CATEGORY_POINTS_OF_INTEREST.
	PointsOfInterest = "PointsOfInterest"
	// DynamicTracing is a category whose signposts are disabled until a tool
	// such as Instruments enables them. It maps to
	// OS_LOG_CATEGORY_DYNAMIC_TRACING.
	DynamicTracing = "DynamicTracing"
)

Category names understood by Instruments and the logging system.

const IDExclusive = idExclusive

IDExclusive is a shared id usable when at most one interval with a given name is in flight at a time on a log, avoiding the need to thread an ID through the code between begin and end.

Types

type ID

type ID uint64

ID identifies a signpost so that a begin can be paired with its end. It mirrors os_signpost_id_t. The zero value is not usable; obtain one from Logger.NewID.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger emits signposts against a single os_log handle. It is created with New and is safe for concurrent use. The zero value is not usable.

func New

func New(subsystem, category string) *Logger

New returns a Logger that emits signposts under the given subsystem and category. Use PointsOfInterest as the category to have intervals appear in the Instruments Points of Interest track. New never returns nil; if the signpost symbols cannot be resolved the returned Logger's methods are no-ops and Logger.Enabled reports false.

func (*Logger) Enabled

func (l *Logger) Enabled() bool

Enabled reports whether signposts are being recorded for this log. Emitting while disabled is harmless but wasteful, so hot paths may check first.

func (*Logger) Event

func (l *Logger) Event(id ID, name string)

Event emits a single point-in-time signpost with the given name.

Example

A point-in-time event marks a moment of interest rather than a duration.

package main

import (
	"github.com/tmc/apple/x/signpost"
)

func main() {
	log := signpost.New("com.example.app", signpost.PointsOfInterest)
	log.Event(log.NewID(), "cache miss")
}

func (*Logger) IntervalBegin

func (l *Logger) IntervalBegin(id ID, name string)

IntervalBegin marks the start of a named interval identified by id. Pair it with an Logger.IntervalEnd call using the same id and name.

func (*Logger) IntervalEnd

func (l *Logger) IntervalEnd(id ID, name string)

IntervalEnd marks the end of the interval begun with the same id and name.

func (*Logger) NewID

func (l *Logger) NewID() ID

NewID returns an ID that is unique among signposts logged to this Logger. Pair the returned ID's begin and end to mark an interval.

type Type

type Type uint8

Type identifies a signpost operation. It mirrors os_signpost_type_t.