From fbcb42c18fe3db3782028920bcf5985f89a99677 Mon Sep 17 00:00:00 2001
From: David Rifkin <50370157+davidlawrencer@users.noreply.github.com>
Date: Thu, 21 Nov 2024 09:29:50 -0600
Subject: [PATCH] Trace note object property (#88)

* Add note about trace as object property

* nit

* fix

* make span optional, fix nonsense code
---
 docs/ios/open-source/features/traces.md | 48 ++++++++++++++++++++++
 docs/ios/open-source/upgrade-guide.md   | 54 +++++++++++++++++++++++++
 2 files changed, 102 insertions(+)

diff --git a/docs/ios/open-source/features/traces.md b/docs/ios/open-source/features/traces.md
index 2e8f045c..8076a7de 100644
--- a/docs/ios/open-source/features/traces.md
+++ b/docs/ios/open-source/features/traces.md
@@ -185,3 +185,51 @@ let span = Embrace
                 errorCode: nil
 )
 ```
+
+### Spans as object properties
+
+To, for example, store a Span in object scope, you will need to import `Span` from the [OpenTelemetry API](https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/OpenTelemetryApi):
+
+
+
+```swift
+/* ******************************* */
+// Imports for new object
+import Foundation
+import EmbraceIO
+import OpenTelemetryApi
+
+// New object definition
+class MyClass {
+    
+    // Create a Span property that will be available across the object
+    var activitySpan: Span? = nil // Span here comes from `OpenTelemetryApi`, not `EmbraceIO`
+
+    func activityStart() {
+        // Something starts
+        // ...
+        // And we want to trace it
+        activitySpan = Embrace.client?.buildSpan(name: "activity")
+                .startSpan()
+    }
+
+    func activityChanged() {
+        // Something changed
+        // ...
+        // And we want to note it
+        activitySpan?.addEvent(name: "activity-changed")
+    }
+
+    func activitySuccessfully() {
+        // Something ended
+        // ...
+        activitySpan?.end()
+    }
+
+    func activityEnded(with failure: EmbraceIO.ErrorCode) {
+        // Something ended unsuccessfully
+        // ...
+        activitySpan?.end(errorCode: failure)
+    }
+}
+```
\ No newline at end of file
diff --git a/docs/ios/open-source/upgrade-guide.md b/docs/ios/open-source/upgrade-guide.md
index 2c81c91e..4eeb38ed 100644
--- a/docs/ios/open-source/upgrade-guide.md
+++ b/docs/ios/open-source/upgrade-guide.md
@@ -122,6 +122,60 @@ addCartSpan?.end()
 </TabItem>
 </Tabs>
 
+Finally, note that when building our Apple 6x SDK, we had to balance our goal of building on the OpenTelemetry specification while also doing our due diligence to avoid tightly-coupling to the existing OTel frameworks. The `EmbraceIO` framework exposes *methods* that create `Span` and `SpanBuilder`, but does not pass through the object types for reference.
+
+To, for example, store a Span in object scope, you will need to import Span's source, namely the [OpenTelemetry API](https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/OpenTelemetryApi):
+
+
+<Tabs groupId="ios-language" queryString="ios-language">
+<TabItem value="swift" label="Swift">
+
+```swift
+/* ******************************* */
+// Imports for new object
+import Foundation
+import EmbraceIO
+import OpenTelemetryApi
+
+// New object definition
+class MyClass {
+    
+    // Create a Span property that will be available across the object
+    var activitySpan: Span? = nil // Span here comes from `OpenTelemetryApi`, not `EmbraceIO`
+
+    func activityStart() {
+        // Something starts
+        // ...
+        // And we want to trace it
+        activitySpan = Embrace.client?.buildSpan(name: "activity")
+                .startSpan()
+    }
+
+    func activityChanged() {
+        // Something changed
+        // ...
+        // And we want to note it
+        activitySpan?.addEvent(name: "activity-changed")
+    }
+
+    func activitySuccessfully() {
+        // Something ended
+        // ...
+        activitySpan?.end()
+    }
+
+    func activityEnded(with failure: EmbraceIO.ErrorCode) {
+        // Something ended unsuccessfully
+        // ...
+        activitySpan?.end(errorCode: failure)
+    }
+}
+```
+
+</TabItem>
+</Tabs>
+
+
 ### Startup Moment
 
 We are working on a replacement for the `endAppStartup` Moment from prior versions, creating a trace-based measurement that will make better use of the device and system's signals. The prior implementation left much to be desired, and using OTel tracing will allow us to combine signals from libraries, both native and third-party, to more-accurately model the startup activity in apps.