beginInterval(_:id:_:)

Begins a signposted interval and attaches the specified message.

Declaration

func beginInterval(_ name: StaticString, id: OSSignpostID = .exclusive, _ message: SignpostMetadata) -> OSSignpostIntervalState

Parameters

name:
The signpost’s name.
id:
The signpost’s identifier. The default value is Exclusive.
message:
The interpolated string that the signposter attaches to the signpost. Each of the message’s interpolations can specify individual formatting and privacy options. For more information, see Message Argument Formatters.

Return Value

The interval state that the signposter derives from the specified id parameter.

Discussion

The signposter uses a signpost ID to pair the beginning and the end of a signposted interval, which is necessary because multiple intervals with the same configuration and scope can be in-flight simultaneously. If only one interval with a specific configuration can execute at any particular time, use exclusive for the id parameter. Otherwise, use the makeSignpostID() and makeSignpostID(from:) methods to generate a signpost identifier.

To end a signposted interval, pass the return value to one of the endInterval(_:_:) or endInterval(_:_:_:) methods. If you don’t have access to the returned interval state when you want to end the signposted interval, recreate it by passing the same signpost ID to the beginState(id:) method.

If you need to pass the returned interval state across process boundaries, you must encode it first. For more information, see OSSignpostIntervalState.

The following example shows how to use a signpost ID and interval state to signpost the beginning and the end of an interval, and also demonstrates the use of message interpolation:

let accountNumber = "12345678"
        
// Create a signposter that uses the default subsystem.
let signposter = OSSignposter()
        
// Generate a signpost ID to associate with the signposted interval.
let signpostID = signposter.makeSignpostID()
        
// Create a name that the signposter uses, along with the 
// signpost ID, to disambiguate the begin call and end call. 
// The type must be StaticString.
let name: StaticString = "Account Reconciliation"
        
// Begin a signposted interval and attach a message that securely
// interpolates sensitive data.
let state = signposter.beginInterval(name, id: signpostID,
    "Account: \(accountNumber, privacy: .sensitive(mask: .hash))")
        
// Perform the related tasks you want to measure.
processTransactions()
updateBalance()
        
// Use the interval state from the begin call to end the
// corresponding signposted interval.
signposter.endInterval(name, state)