Build Custom Instruments with os_signpost

WHY IT EXISTS: Standard Instruments shows you what the system is doing, but it is blind to your apps internal semantics. You can see a CPU spike, yet you cannot tell whether it came from a model hydration pass, a texture upload, or a background sync. os_signpost was created to bridge that observability gap by letting you emit lightweight, structured interval markers from your own code that Instruments can render as first-class visual tracks.

THE MENTAL MODEL: Think of it as installing custom gauges on a car dashboard. You place sensors at key points in your engine, then build a faceplate that displays those readings in a way a mechanic understands. The sensors are the signpost begin and end calls in your Swift or Objective-C code. The faceplate is the custom instrument package you author in Xcode, which tells Instruments how to turn those raw markers into graphs, intervals, and counters.

HOW IT WORKS: You create an OSLog object with a custom subsystem and category, then wrap sections of code with os_signpost begin and end calls. Each interval can carry metadata such as an identifier or a byte count. Next, you create a custom instrument using the Instruments Package template in Xcode. Inside the package, you define an instrument schema that subscribes to your subsystem and category, mapping signpost events to UI elements like interval tracks or numeric graphs. When you profile your app, your custom tracks appear alongside built-in metrics. The signposts are cheap enough to leave in shipping code, though the custom visualization is only active during profiling.

WHEN TO USE IT: Reach for custom signpost instruments when you are optimizing multi-stage pipelines, diagnosing async work that crosses queue boundaries, or correlating user actions with resource usage. It is especially powerful when multiple subsystems interact and you need to see their relative timing on a shared timeline.

WHEN NOT TO USE IT: Do not use os_signpost as a general logging replacement for os_log, because its purpose is profiling visualization, not persistent diagnostics. Avoid it if you only need a one-off timer in a unit test, or if your team will not invest the time to build and maintain the custom instrument package. It is also the wrong tool for production analytics; the data is local to the profiling session.

ONE CANONICAL EXAMPLE: Imagine a photo editing app that downloads a raw asset, decodes it, applies a filter on a background queue, and then renders the result. You emit os_signpost begin and end at each stage using the same log handle but different event names. In your custom instrument, you define four interval tracks: Download, Decode, Filter, and Render. During a trace, you immediately see that the decode interval overlaps with a memory pressure event, while the filter queue is idle. That insight tells you to move decoding onto a lower-priority queue or stream the decode in chunks rather than guessing from aggregate CPU numbers.