协议扩展

本文档介绍了 SDK 基于自定义执行单元相关接口的使用及说明。

创建执行单元

注意：startSpanWithName:operation: 需和 finish或finishWithStatus: 成对调用。

Objective-C
Swift

接口

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

参数

参数	类型	说明
name	NSString	span 名称，不能为空，长度限制为1024个字符，超过截取前1024个字符
operation	NSString	span所属的operation名称，如websocket，不能为空，长度限制为128个字符，超过截取前128个字符

示例

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

接口

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

参数

参数	类型	说明
name	NSString	span 名称，不能为空，长度限制为1024个字符，超过截取前1024个字符
operation	NSString	span所属的operation名称，如websocket，不能为空，长度限制为128个字符，超过截取前128个字符

示例

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

完成执行单元

注意：startSpanWithName:operation: 需和 finish或finishWithStatus: 成对调用。

Objective-C
Swift

接口

- (void)finish;

- (void)finishWithStatus:(NBSSpanStatus)status;

说明

完成执行单元提供了两个方法 finish 和 finishWithStatus: ，调用 finish 完成执行单元时状态值默认为 NBSSpanStatusSuccess ，而 finishWithStatus: 可以设置完成执行单元时的状态；可根据需求调用相应完成执行单元接口。

参数

参数	类型	说明
status	NBSSpanStatus	status状态，值可为：NBSSpanStatusUndefined、 NBSSpanStatusSuccess、NBSSpanStatusFailed

示例

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

接口

finish()

finish(with: <NBSSpanStatus>)

说明

参数

参数	类型	说明
status	NBSSpanStatus	status状态，值可为：NBSSpanStatusUndefined、 NBSSpanStatusSuccess、NBSSpanStatusFailed

示例

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

创建子执行单元

注意：startChildWithName:operation: 需和 finish或finishWithStatus: 成对调用。

Objective-C
Swift

接口

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

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

参数

参数	类型	说明
name	NSString	名称；不能为空，长度限制为1024字符，超过截取前1024字符。
operation	NSString	类别；不能为空，长度限制为128字符，超过截取前128字符
description	NSString	描述；长度限制为1024字符，超过截取前1024字符

示例

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];

接口

startChild(withName: String, operation: String)

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

参数

参数	类型	说明
name	NSString	名称；不能为空，长度限制为1024字符，超过截取前1024字符。
operation	NSString	类别；不能为空，长度限制为128字符，超过截取前128字符
description	NSString	描述；长度限制为1024字符，超过截取前1024字符

示例

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)

设置 Data 数据

Objective-C
Swift

接口

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

参数

参数	类型	说明
value	id	data数据的value值
key	NSString	data数据的key值，key值相同时覆盖value值

示例

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

接口

setDataValue(value: Any?, forKey: String)

参数

参数	类型	说明
value	id	data数据的value值
key	NSString	data数据的key值，key值相同时覆盖value值

示例

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

设置 Tag 数据

Objective-C
Swift

接口

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

参数

参数	类型	说明
value	NSString	Tag数据的value值
key	NSString	Tag数据的key值，key值相同时覆盖value值

示例

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

接口

setTagValue(value: String, forKey: String)

参数

参数	类型	说明
value	NSString	Tag数据的value值
key	NSString	Tag数据的key值，key值相同时覆盖value值

示例

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

设置 Metric 数据

Objective-C
Swift

接口

- (void)setMetricValue:(NSNumber *)value forKey:(NSString *)key;

- (void)setMetricValue:(NSNumber *)value unit:(NSString *)unit forKey:(NSString *)key;

参数

参数	类型	说明
value	NSNumber	Metric数据的value值
unit	NSString	value的单位名称，比如毫秒“ms”，保留单位类型见NBSDefines.h中的NBSSpanMetricUnitNames[ ]，支持自定义单位
key	NSString	Metric数据的key值，key值相同时覆盖value值

示例

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
[span setMetricValue:@100 unit:@"ms" forKey:@"time"];
[span finishWithStatus:NBSSpanStatusSuccess];

接口

setMetricValue(value: NSNumber, forKey: String)

spn?.setMetricValue(value: NSNumber, unit: String, forKey: String)

参数

参数	类型	说明
value	NSNumber	Metric数据的value值
unit	NSString	value的单位名称，比如毫秒“ms”，保留单位类型见NBSDefines.h中的NBSSpanMetricUnitNames[ ]，支持自定义单位
key	NSString	data数据的key值，key值相同时覆盖value值

示例

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
span?.setMetricValue(100, unit: "ms", forKey: "time")
span?.finish(with: NBSSpanStatus.success)

移除 Data 数据

Objective-C
Swift

接口

- (void)removeDataForKey:(NSString *)key;

参数

参数	类型	说明
key	NSString	data数据的key值

示例

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

接口

removeData(forKey: String)

参数

参数	类型	说明
key	NSString	data数据的key值

示例

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

移除 Tag 数据

Objective-C
Swift

接口

- (void)removeTagForKey:(NSString *)key;

参数

参数	类型	说明
key	NSString	Tag数据的key值

示例

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

接口

removeTag(forKey: String)

参数

参数	类型	说明
key	NSString	Tag数据的key值

示例

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

移除 Metric 数据

Objective-C
Swift

接口

- (void)removeMetricForKey:(NSString *)key;

参数

参数	类型	说明
key	NSString	metric数据的key值

示例

id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
[span setMetricValue:@100 unit:@"ms" forKey:@"time"];
[span removeMetricForKey:@"time"];
[span finishWithStatus:NBSSpanStatusSuccess];

接口

removeMetric(forKey: String)

参数

参数	类型	说明
key	NSString	metric数据的key值

示例

let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
span?.setMetricValue(100, unit: "ms", forKey: "time")
span?.removeMetric(forKey: "time")
span?.finish(with: NBSSpanStatus.success)

设置 Status

Objective-C
Swift

接口

- (void)setStatus:(NBSSpanStatus)status;

参数

参数	类型	说明
status	NBSSpanStatus	设置span的状态

示例

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

接口

setStatus(status: NBSSpanStatus)

参数

参数	类型	说明
status	NBSSpanStatus	设置span的状态

示例

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

设置 Duration

Objective-C
Swift

接口

- (void)setDuration:(NSNumber *)value;

参数

参数	类型	说明
value	NSNumber	span执行耗时，默认耗时为startSpanWithName 到 finish。

示例

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

接口

setDuration(value: NSNumber)

参数

参数	类型	说明
value	NSNumber	span执行耗时，默认耗时为startSpanWithName 到 finish。

示例

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

设置 StatusCode

Objective-C
Swift

接口

- (void)setStatusCode:(NSString *)value;

参数

参数	类型	说明
value	NSString	span的statusCode，默认值为0

示例

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

接口

setStatusCode(value: String)

参数

参数	类型	说明
value	NSString	span的statusCode，默认值为0

示例

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

协议扩展

创建执行单元​

完成执行单元​

创建子执行单元​

设置 Data 数据​

设置 Tag 数据​

设置 Metric 数据​

移除 Data 数据​

移除 Tag 数据​

移除 Metric 数据​

设置 Status​

设置 Duration​

设置 StatusCode​