Protocol Extension

This document introduces the usage and explanation of SDK interfaces related to custom execution units.

Create Execution Unit (Span)

Note

startSpanWithName:operation: must be paired with finish or finishWithStatus:.

Objective-C

Objective-C

• API

+ (id<NBSSpan>)startSpanWithName:(NSString *)name operation:(NSString *)operation;

• Parameters

Parameter	Type	Description
name	NSString	Span name, cannot be empty, max length 1024 characters, truncated if exceeded
operation	NSString	Operation name the span belongs to, e.g., websocket, cannot be empty, max length 128 characters, truncated if exceeded

• Example

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
[span finish];

Swift

Swift

• API

startSpan(withName: String!, operation: String!)

• Parameters

Parameter	Type	Description
name	NSString	Span name, cannot be empty, max length 1024 characters, truncated if exceeded
operation	NSString	Operation name the span belongs to, e.g., websocket, cannot be empty, max length 128 characters, truncated if exceeded

• Example

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
span?.finish()

Finish Execution Unit (Span)

Note

startSpanWithName:operation: must be paired with finish or finishWithStatus:.

Objective-C

Objective-C

• API

- (void)finish;

- (void)finishWithStatus:(NBSSpanStatus)status;

• Description

Finishing an execution unit provides two methods: finish and finishWithStatus:. Calling finish sets the status to NBSSpanStatusSuccess by default, while finishWithStatus: allows you to set the status. Use the appropriate method as needed.

• Parameters

Parameter	Type	Description
status	NBSSpanStatus	Status value: NBSSpanStatusUndefined, NBSSpanStatusSuccess, NBSSpanStatusFailed

• Example

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
[span finishWithStatus:NBSSpanStatusSuccess];

Swift

Swift

• API

finish()

finish(with: <NBSSpanStatus>)

• Description

Finishing an execution unit provides two methods: finish and finishWithStatus:. Calling finish sets the status to NBSSpanStatusSuccess by default, while finishWithStatus: allows you to set the status. Use the appropriate method as needed.

• Parameters

Parameter	Type	Description
status	NBSSpanStatus	Status value: NBSSpanStatusUndefined, NBSSpanStatusSuccess, NBSSpanStatusFailed

• Example

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
span?.finish(with: NBSSpanStatus.success)

Create Child Execution Unit (Span)

Note

startChildWithName:operation: must be paired with finish or finishWithStatus:.

Objective-C

Objective-C

• API

- (id<NBSSpan>)startChildWithName:(NSString *)name operation:(NSString *)operation;

- (id<NBSSpan>)startChildWithName:(NSString *)name operation:(NSString *)operation description:(nullable NSString *)description;

• Parameters

Parameter	Type	Description
name	NSString	Name; cannot be empty, max length 1024 characters, truncated if exceeded.
operation	NSString	Category; cannot be empty, max length 128 characters, truncated if exceeded
description	NSString	Description; max length 1024 characters, truncated if exceeded

• Example

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
id<NBSSpan> sub = [span startChildWithName:@"sub_name" operation:@"sub_operation"];
[sub finishWithStatus:NBSSpanStatusSuccess];
[span finishWithStatus:NBSSpanStatusSuccess];

Swift

Swift

• API

startChild(withName: String, operation: String)

startChild(withName: String, operation: String, description: String?)

• Parameters

Parameter	Type	Description
name	NSString	Name; cannot be empty, max length 1024 characters, truncated if exceeded.
operation	NSString	Category; cannot be empty, max length 128 characters, truncated if exceeded
description	NSString	Description; max length 1024 characters, truncated if exceeded

• Example

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
let sub = span!.startChild(withName: "sub_name", operation: "sub_operation")
sub.finish(with: NBSSpanStatus.success)
span!.finish(with: NBSSpanStatus.success)

Set Data

Objective-C

Objective-C

• API

- (void)setDataValue:(nullable id)value forKey:(NSString *)key;

• Parameters

Parameter	Type	Description
value	id	Value of the data
key	NSString	Key of the data; if the key is the same, the value is overwritten

• Example

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
[span setDataValue:@"dataValue" forKey:@"dataKey"];
[span finishWithStatus:NBSSpanStatusSuccess];

Swift

Swift

• API

setDataValue(value: Any?, forKey: String)

• Parameters

Parameter	Type	Description
value	id	Value of the data
key	NSString	Key of the data; if the key is the same, the value is overwritten

• Example

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
span?.setDataValue("dataValue", forKey: "dataKey")
span?.finish(with: NBSSpanStatus.success)

Set Tag

Objective-C

Objective-C

• API

- (void)setTagValue:(NSString *)value forKey:(NSString *)key;

• Parameters

Parameter	Type	Description
value	NSString	Value of the tag
key	NSString	Key of the tag; if the key is the same, the value is overwritten

• Example

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
[span setTagValue:@"tagValue" forKey:@"tagKey"];
[span finishWithStatus:NBSSpanStatusSuccess];

Swift

Swift

• API

setTagValue(value: String, forKey: String)

• Parameters

Parameter	Type	Description
value	String	Value of the tag
key	String	Key of the tag; if the key is the same, the value is overwritten

• Example

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
span?.setTagValue("tagValue", forKey: "tagKey")
span?.finish(with: NBSSpanStatus.success)