Skip to main content

Protocol Extension

This document introduces the SDK's interfaces for creating custom execution units.

Create an Execution Unit​

Note: The startSpanWithName:operation: method must be used in pairs with either finish or finishWithStatus:.

  • Related Interface

    /**
     * @brief Creates an independent span, known as an execution unit.
     * @param name The name of the span, which cannot be nil and is limited to 1024 characters. Excess characters will be truncated from the start.
     */
     + (id<NBSSpan>)startSpanWithName:(NSString *)name operation:(NSString *)operation;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span finish];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.finish()

Complete an Execution Unit​

Note：The startSpanWithName:operation: method must be used in pairs with either finish or finishWithStatus:.

  • Related Interface

    /**
     * @brief Completes a span and sets the completion time. The default status is NBSSpanStatusSuccess.
     */
    - (void)finish;

    /**
     * @brief Completes a span and sets the completion time and status.
     * @param status The status can be NBSSpanStatusUndefined, NBSSpanStatusSuccess, or NBSSpanStatusFailed.
     */
    - (void)finishWithStatus:(NBSSpanStatus)status;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.finish(with: NBSSpanStatus.success)

Create a Sub Execution Unit​

Note：he startChildWithName:operation: method must be used in pairs with either finish or finishWithStatus:.

  • Related Interface
/**
 * @brief Creates a child span with a description.
 * @param name The name, which cannot be nil and is limited to 1024 characters. Excess characters will be truncated from the start.
 * @param operation The category, which cannot be nil and is limited to 128 characters. Excess characters will be truncated from the start.
 * @param description The description, limited to 1024 characters. Excess characters will be truncated from the start.
 */
- (id<NBSSpan>)startChildWithName:(NSString *)name operation:(NSString *)operation;
- (id<NBSSpan>)startChildWithName:(NSString *)name operation:(NSString *)operation description:(nullable NSString *)description;

  • Code Example

    • Objective-C
    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
    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​

  • Related Interface
/**
 * @brief Sets the value for a data key.
 */
- (void)setDataValue:(nullable id)value forKey:(NSString *)key;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setDataValue:@"dataValue" forKey:@"dataKey"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setDataValue("dataValue", forKey: "dataKey")
    span?.finish(with: NBSSpanStatus.success)

Set Tag Data​

  • Related Interface
/**
 * @brief Sets the value for a tag key.
 * @warning The value must be a string type.
 */
- (void)setTagValue:(NSString *)value forKey:(NSString *)key;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setTagValue:@"tagValue" forKey:@"tagKey"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swfit
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setTagValue("tagValue", forKey: "tagKey")
    span?.finish(with: NBSSpanStatus.success)

Set Metric Data​

  • Related Interface
/**
 * @brief Sets the value for a metric key.
 * @param unit The unit of the value, such as "ms" for milliseconds. See NBSDefines.h for reserved unit types and support for custom units.
 * @warning The value must be of type NSNumber, and the unit must be a string.
 * @discussion When the span's operation is "websocket", if the values set are for sendSize, sendCount, receiveSize, receiveCount, or pingpongCount, the SDK will automatically accumulate these values.
 */
- (void)setMetricValue:(NSNumber *)value forKey:(NSString *)key;
- (void)setMetricValue:(NSNumber *)value unit:(NSString *)unit forKey:(NSString *)key;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setMetricValue:@100 unit:@"ms" forKey:@"time"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setMetricValue(100, unit: "ms", forKey: "time")
    span?.finish(with: NBSSpanStatus.success)

Remove Data​

  • Related Interface
/**
 * @brief Removes a data entry.
 */
- (void)removeDataForKey:(NSString *)key;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setDataValue:@"dataValue" forKey:@"dataKey"];
    [span removeDataForKey:@"dataKey"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setDataValue("dataValue", forKey: "dataKey")
    span?.removeData(forKey: "dataKey")
    span?.finish(with: NBSSpanStatus.success)

Remove Tag​

  • Related Interface
/**
 * @brief Removes a tag entry.
 */
- (void)removeTagForKey:(NSString *)key;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setTagValue:@"tagValue" forKey:@"tagKey"];
    [span removeTagForKey:@"tagKey"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setTagValue("tagValue", forKey: "tagKey")
    span?.removeTag(forKey: "tagKey")
    span?.finish(with: NBSSpanStatus.success)

Remove Metric​

  • Related Interface
/**
 * @brief Removes a metric entry.
 */
- (void)removeMetricForKey:(NSString *)key;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setMetricValue:@100 unit:@"ms" forKey:@"time"];
    [span removeMetricForKey:@"time"];
    [span finishWithStatus:NBSSpanStatusSuccess];
    • Swift
    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)

Set Status​

  • Related Interface
/**
 * @brief Sets the status of the span.
 */
- (void)setStatus:(NBSSpanStatus)status;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setStatus:NBSSpanStatusSuccess];
    [span finish];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setStatus(NBSSpanStatus.success)
    span?.finish()

Set Duration​

  • Related Interface
/**
 * @brief Sets the duration of the span's execution time. The default duration is from the startSpanWithName to the finish.
 * @param value The duration of the span's execution.
 */
- (void)setDuration:(NSNumber *)value;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setDuration:@100];
    [span finish];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setDuration(100)
    span?.finish()

Set StatusCode​

  • Related Interface
/**
 * @brief Sets the statusCode, with a default of 0.
 */
- (void)setStatusCode:(NSString *)value;

  • Code Example

    • Objective-C
    id<NBSSpan> span = [NBSAppAgent startSpanWithName:@"span_name" operation:@"span_operation"];
    [span setStatusCode:@"200"];
    [span finish];
    • Swift
    let span = NBSAppAgent.startSpan(withName: "span_name", operation: "span_operation")
    span?.setStatusCode("200")
    span?.finish()