Skip to main content

Utility Classes

Utility Classes​

The Embrace SDK provides various utility classes to help with common tasks in your application. These utilities make it easier to work with the SDK's core functionality.

Span Management​

SpanBuilder​

The SpanBuilder class provides a fluent interface for creating and customizing spans.

class SpanBuilder {
    func setAttribute(_ key: String, value: Any) -> SpanBuilder
    func setAttributes(_ attributes: [String: Any]) -> SpanBuilder
    func startSpan() -> Span
}

Methods:

  • setAttribute(_:value:): Sets a single attribute on the span.
  • setAttributes(_:): Sets multiple attributes on the span.
  • startSpan(): Creates and starts the span with the configured attributes.

GitHub Source: Embrace Apple SDK Repository

Span​

The Span protocol defines the interface for working with spans.

protocol Span {
    var name: String { get }
    var type: SpanType { get }
    var traceId: String? { get }
    var spanId: String? { get }
    var startTime: Date { get }
    var endTime: Date? { get }

    func setAttribute(_ key: String, value: Any)
    func end(at time: Date?)
    func addEvent(_ name: String, attributes: [String: String]?)
}

Methods:

  • setAttribute(_:value:): Sets a single attribute on the span.
  • end(at:): Ends the span, optionally at a specific time.
  • addEvent(_:attributes:): Adds an event to the span with optional attributes.

SpanType​

Enum defining different types of spans.

enum SpanType {
    case performance
    case network
    case view
    case resource
    case error
    case crash
    case custom(String)
}

Logging​

LogSeverity​

Enum defining severity levels for logs.

enum LogSeverity: String {
    case info
    case warning
    case error
}

EmbraceLog​

Interface for working with logs created by the SDK.

protocol EmbraceLog {
    var message: String { get }
    var severity: LogSeverity { get }
    var timestamp: Date { get }
    var attributes: [String: String] { get }
}

Session Utilities​

SessionSpanUtils​

Utility for working with session spans.

class SessionSpanUtils {
    static func getSessionId(from span: Span) -> String?
    static func setSessionId(_ sessionId: String, on span: Span)
    static func getSessionProperties(from span: Span) -> [String: String]?
}

Methods:

  • getSessionId(from:): Extracts the session ID from a span.
  • setSessionId(_:on:): Sets the session ID on a span.
  • getSessionProperties(from:): Gets the session properties from a span.

Network Utilities​

HeaderFilterKeys​

Configuration for filtering HTTP headers.

struct HeaderFilterKeys {
    init(
        requestHeadersBlocklist: [String] = [],
        responseHeadersBlocklist: [String] = []
    )
}

Parameters:

  • requestHeadersBlocklist: List of request header keys to block from capture.
  • responseHeadersBlocklist: List of response header keys to block from capture.

OpenTelemetry Integration​

OpenTelemetryExport​

Configuration for exporting OpenTelemetry data.

struct OpenTelemetryExport {
    init(
        spanExporter: SpanExporter? = nil,
        logExporter: LogExporter? = nil
    )
}

Parameters:

  • spanExporter: Exporter for OpenTelemetry spans.
  • logExporter: Exporter for OpenTelemetry logs.

Crash Reporting​

CrashReporter​

Protocol for crash reporters.

protocol CrashReporter {
    func install() -> Bool
    func updateAppState(_ state: AppState)
    func updateAttributes(_ attributes: [String: String])
}

Methods:

  • install(): Installs the crash reporter.
  • updateAppState(_:): Updates the app state in the crash reporter.
  • updateAttributes(_:): Updates custom attributes in the crash reporter.

EmbraceCrashReporter​

Default implementation of the CrashReporter protocol.

class EmbraceCrashReporter: CrashReporter {
    init()
    func install() -> Bool
    func updateAppState(_ state: AppState)
    func updateAttributes(_ attributes: [String: String])
}

Symbolic Upload Utilities​

Utilities for working with debug symbols.

SymbolUpload​

struct SymbolUpload {
    static func uploadSymbols(
        appId: String,
        token: String,
        dsymURLs: [URL],
        baseURL: URL? = nil,
        completion: ((Result<Void, Error>) -> Void)? = nil
    )
}

Methods:

  • uploadSymbols(appId:token:dsymURLs:baseURL:completion:): Uploads debug symbols to the Embrace backend.

Code Examples​

Working with Spans​

// Create and customize a span
let span = EmbraceIO.shared.buildSpan(name: "checkout-process", type: .performance)
    .setAttribute("order_id", value: orderId)
    .setAttribute("total_amount", value: totalAmount)
    .startSpan()

// Perform the work
performCheckoutProcess()

// Add events during the span
span?.addEvent("payment-started", attributes: ["payment_provider": "stripe"])

// End the span when complete
span?.end()

Creating and Managing Logs​

// Log an informational message
try EmbraceIO.shared.log(
    "User completed checkout",
    severity: .info,
    attributes: [
        "order_id": orderId,
        "user_id": userId
    ]
)

// Log an error
do {
    try performRiskyOperation()
} catch let error {
    try EmbraceIO.shared.log(
        "Risky operation failed: \(error.localizedDescription)",
        severity: .error,
        attributes: [
            "operation": "risky-operation",
            "context": "checkout-flow"
        ]
    )
}

Custom Network Header Filtering​

let networkOptions = NetworkCaptureServiceOptions(
    captureRequestHeaders: true,
    captureResponseHeaders: true,
    headerKeys: .init(
        requestHeadersBlocklist: ["Authorization", "X-API-Key", "Cookie"],
        responseHeadersBlocklist: ["Set-Cookie"]
    ),
    requestHeaderFilter: { request in
        // Custom filtering logic for headers
        var safeHeaders: [String: String] = [:]
        request.allHTTPHeaderFields?.forEach { key, value in
            if key.contains("Token") || key.contains("Auth") {
                // Redact sensitive headers
                safeHeaders[key] = "***REDACTED***"
            } else {
                safeHeaders[key] = value
            }
        }
        return safeHeaders
    }
)

Uploading Debug Symbols​

// Find dSYM files
let dsymPaths: [URL] = findDsymFiles()

// Upload symbols to Embrace
SymbolUpload.uploadSymbols(
    appId: "YOUR_APP_ID",
    token: "YOUR_TOKEN",
    dsymURLs: dsymPaths
) { result in
    switch result {
    case .success:
        print("Successfully uploaded debug symbols")
    case .failure(let error):
        print("Failed to upload debug symbols: \(error)")
    }
}