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.
The name-only operations (Logger.IntervalBegin, Logger.IntervalEnd, Logger.Event) pass an empty format buffer. The Message variants attach a run-time string as a "%{public}s" argument, and the f variants (Logger.IntervalBeginf, Logger.IntervalEndf, Logger.Eventf) take an os_log format string with typed arguments; both build the argument buffer the C macros get from __builtin_os_log_format (shared with x/oslog). Instruments shows the result as the interval's message.
Signposts always emit and pair. Whether their names and messages decode in trace output depends on the strings being present in a loaded image's __TEXT,__oslogstring section (the log tools resolve them by offset from the on-disk image; heap strings render as "<missing name>"). The signpostnames tool (cmd/signpostnames) generates that pool, and the first unpooled emit prints a one-time warning. Measured build-mode matrix:
- CGO_ENABLED=1 (macOS default) + names_darwin.syso: decodes. The syso forces external linking, which lays the section out; no cgo source is required.
- CGO_ENABLED=0 + syso: does NOT decode. The internal linker drops the section. Use signpostnames -dylib and LoadNames instead, which works in every build mode.
- cgo builds of this package also pool the format strings automatically (oslogstrings_cgo.go), so Message output decodes without a syso.
Basic usage:
log := signpost.New("com.example.app", signpost.PointsOfInterest)
id := log.NewID()
log.IntervalBegin(id, "load")
// ... work ...
log.IntervalEnd(id, "load")
Index ¶
- Constants
- func LoadNames(path string) error
- type ID
- type Logger
- func (l *Logger) Enabled() bool
- func (l *Logger) Event(id ID, name string)
- func (l *Logger) EventMessage(id ID, name, msg string)
- func (l *Logger) Eventf(id ID, name, format string, args ...any)
- func (l *Logger) IntervalBegin(id ID, name string)
- func (l *Logger) IntervalBeginMessage(id ID, name, msg string)
- func (l *Logger) IntervalBeginf(id ID, name, format string, args ...any)
- func (l *Logger) IntervalEnd(id ID, name string)
- func (l *Logger) IntervalEndMessage(id ID, name, msg string)
- func (l *Logger) IntervalEndf(id ID, name, format string, args ...any)
- func (l *Logger) NewID() ID
- type Type
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.
Variables ¶
This section is empty.
Functions ¶
func LoadNames ¶ added in v0.6.17
LoadNames loads a names dylib built by signpostnames -dylib and makes its strings available for signpost decoding. It is the opt-in path for builds whose linker cannot carry a __TEXT,__oslogstring section (internal linking, CGO_ENABLED=0); externally linked builds get the same effect from a .syso with no runtime step. Names are resolved against the executable's own section first, then against loaded images in LoadNames order.
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 ¶
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 ¶
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) EventMessage ¶ added in v0.6.17
EventMessage emits a single point-in-time signpost with the given name, carrying msg as a public formatted message.
func (*Logger) Eventf ¶ added in v0.6.17
Eventf emits a point-in-time signpost with a formatted message as in Logger.IntervalBeginf.
func (*Logger) IntervalBegin ¶
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) IntervalBeginMessage ¶ added in v0.6.17
IntervalBeginMessage marks the start of a named interval identified by id, carrying msg as a public formatted message. Instruments groups intervals by name and shows the message as detail, so a small fixed set of names with a descriptive message yields one track per name rather than one per span.
func (*Logger) IntervalBeginf ¶ added in v0.6.17
IntervalBeginf begins a named interval whose message is built from an os_log format string and typed arguments (%d/%u/%x and l-prefixed 64-bit forms, %p, %f family, %s/%@; %{public}/%{private} set visibility). The format string must be a literal pooled by signpostnames for the message to decode; the arguments are serialized into the tracepoint at emit time.
func (*Logger) IntervalEnd ¶
IntervalEnd marks the end of the interval begun with the same id and name.
func (*Logger) IntervalEndMessage ¶ added in v0.6.17
IntervalEndMessage marks the end of the interval begun with the same id and name, carrying msg as a public formatted message.
func (*Logger) IntervalEndf ¶ added in v0.6.17
IntervalEndf ends the interval begun with the same id and name, with a formatted message as in Logger.IntervalBeginf.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
signpostnames
command
Command signpostnames generates a signpost string pool so names decode in trace output.
|
Command signpostnames generates a signpost string pool so names decode in trace output. |