From dce3a10681d26a3407e782b53775fac64e0a08e5 Mon Sep 17 00:00:00 2001
From: Philipp Hofmann <philipp.hofmann@sentry.io>
Date: Thu, 30 Jan 2025 15:47:05 +0100
Subject: [PATCH] feat(apple): Attach data onto a span/transaction

Add docs for how to attach data onto span/transaction.

Fixes https://github.com/getsentry/sentry-cocoa/issues/4678.
---
 .../custom-instrumentation.mdx                |  2 +
 .../performance/improving-data/apple.mdx      | 51 +++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 platform-includes/performance/improving-data/apple.mdx

diff --git a/docs/platforms/apple/common/tracing/instrumentation/custom-instrumentation.mdx b/docs/platforms/apple/common/tracing/instrumentation/custom-instrumentation.mdx
index 74f9e8c3a1188..abdcb15057f35 100644
--- a/docs/platforms/apple/common/tracing/instrumentation/custom-instrumentation.mdx
+++ b/docs/platforms/apple/common/tracing/instrumentation/custom-instrumentation.mdx
@@ -17,3 +17,5 @@ To capture transactions and spans customized to your organization's needs, you m
 <PlatformContent includePath="performance/create-transaction-bound-to-scope" />
 
 <PlatformContent includePath="performance/connect-errors-spans" />
+
+<PlatformContent includePath="performance/improving-data" />
diff --git a/platform-includes/performance/improving-data/apple.mdx b/platform-includes/performance/improving-data/apple.mdx
new file mode 100644
index 0000000000000..fbfb15da0cdea
--- /dev/null
+++ b/platform-includes/performance/improving-data/apple.mdx
@@ -0,0 +1,51 @@
+## Improving Data on Transactions and Spans
+
+### Adding Data Attributes to Transactions
+
+You can add data attributes to your transactions. This data is visible in the trace explorer in Sentry. Data attributes can be of type `String`, `Number` or `Boolean`, as well as (non-mixed) arrays of these types:
+
+```swift {tabTitle:Swift}
+let transaction = SentrySDK.startTransaction(name: "processOrderBatch", operation: "task")
+transaction.setData(value: "value1", key: "my-data-attribute-1")
+transaction.setData(value: 42, key: "my-data-attribute-2")
+transaction.setData(value: true, key: "my-data-attribute-3")
+
+transaction.setData(value: ["value1", "value2", "value3"], key: "my-data-attribute-4")
+transaction.setData(value: [42, 43, 44], key: "my-data-attribute-5")
+transaction.setData(value: [true, false, true], key: "my-data-attribute-6")
+```
+```objc {tabTitle:Objective-C}
+id<SentrySpan> transaction = [SentrySDK startTransactionWithName:@"processOrderBatch" operation:@"task"];
+[transaction setDataValue:@"value1" forKey:@"my-data-attribute-1"];
+[transaction setDataValue:@(42) forKey:@"my-data-attribute-2"];
+[transaction setDataValue:@(YES) forKey:@"my-data-attribute-3"];
+
+[transaction setDataValue:@[@"value1", @"value2", @"value3"] forKey:@"my-data-attribute-4"];
+[transaction setDataValue:@[@(42), @(43), @(44)] forKey:@"my-data-attribute-5"];
+[transaction setDataValue:@[@(YES), @(NO), @(YES)] forKey:@"my-data-attribute-6"];
+```
+
+### Adding Data Attributes to Spans
+
+You can add data attributes to your spans. This data is visible in the trace explorer in Sentry. Data attributes can be of type `String`, `Number` or `Boolean`, as well as (non-mixed) arrays of these types:
+
+```swift {tabTitle:Swift}
+let span = parent.startChild(operation: "operation")
+span.setData(value: "value1", key: "my-data-attribute-1")
+span.setData(value: 42, key: "my-data-attribute-2")
+span.setData(value: true, key: "my-data-attribute-3")
+
+span.setData(value: ["value1", "value2", "value3"], key: "my-data-attribute-4")
+span.setData(value: [42, 43, 44], key: "my-data-attribute-5")
+span.setData(value: [true, false, true], key: "my-data-attribute-6")
+```
+```objc {tabTitle:Objective-C}
+id<SentrySpan> span = [transaction startChildWithOperation:@"task"];
+[span setDataValue:@"value1" forKey:@"my-data-attribute-1"];
+[span setDataValue:@(42) forKey:@"my-data-attribute-2"];
+[span setDataValue:@(YES) forKey:@"my-data-attribute-3"];
+
+[span setDataValue:@[@"value1", @"value2", @"value3"] forKey:@"my-data-attribute-4"];
+[span setDataValue:@[@(42), @(43), @(44)] forKey:@"my-data-attribute-5"];
+[span setDataValue:@[@(YES), @(NO), @(YES)] forKey:@"my-data-attribute-6"];
+```