diff --git a/docs/features/traces.md b/docs/features/traces.md index ac0c168a..2cee99e8 100644 --- a/docs/features/traces.md +++ b/docs/features/traces.md @@ -68,7 +68,7 @@ Once you click on a Slow Root Span, you can see specific instances of that span. ## Implementation Details 1. [**Android**](/android/features/traces) - 2. [**iOS**](/ios/open-source/traces) + 2. [**iOS**](/ios/open-source/features/traces) 3. [**Unity**](/unity/features/traces) 4. [**React Native**](/react-native/features/traces) 5. [**Flutter**](/flutter/features/traces) diff --git a/docs/flutter/features/traces.md b/docs/flutter/features/traces.md index b35ca817..5d126a1b 100644 --- a/docs/flutter/features/traces.md +++ b/docs/flutter/features/traces.md @@ -94,7 +94,7 @@ All telemetry in Embrace's Flutter SDK is routed through Embrace's Android/iOS S Please follow [this guide](/android/features/traces) to setup OpenTelemetry collectors on Android. ### iOS OTel export -Please follow [this guide](/ios/open-source/otel-exporter) to setup OpenTelemetry collectors on iOS. +Please follow [this guide](/ios/open-source/features/otel-exporter) to setup OpenTelemetry collectors on iOS. :::info Please note the OpenTelemetry-Swift repository does not support Cocoapods so you will be unable to import ready-made exporters directly. We recommend adding a new file that implements `SpanExporter` or `LogRecordExporter` directly, and using the ready-made exporters as reference implementations. diff --git a/docs/ios/5x/index.md b/docs/ios/5x/index.md index 673c9e1b..3cf420a3 100644 --- a/docs/ios/5x/index.md +++ b/docs/ios/5x/index.md @@ -6,7 +6,7 @@ sidebar_position: 2 # Getting Started -Embrace's 5.x SDK supports both the iOS and the Apple TV platform from a common codebase. All of the API you can use on iOS, is also available on Apple TV. The 5.x SDK is built on Objective-C and is closed-source. It will eventually be replaced by the [6.x SDK](./../open-source/) +Embrace's 5.x SDK supports both the iOS and the Apple TV platform from a common codebase. All of the API you can use on iOS, is also available on Apple TV. The 5.x SDK is built on Objective-C and is closed-source. It is no longer recommended for new and current users, who should upgrade to the [6.x SDK](/ios/open-source/). This documentation is split into two sections: @@ -17,4 +17,4 @@ If you are just starting out with Embrace, follow the [**Integration Guide**](./ Once you've completed that, browse through our [**Feature Reference**](./features/) guides to learn how to use some of the advanced features our SDK provides. -You can also view our [FAQ](/ios/faq/) and [Changelog](/ios/changelog/) \ No newline at end of file +You can also view our [FAQ](/ios/faq/) and [Changelog](/ios/changelog/) diff --git a/docs/ios/index.md b/docs/ios/index.md index 77ef3dea..1f2af9b7 100644 --- a/docs/ios/index.md +++ b/docs/ios/index.md @@ -10,33 +10,31 @@ sidebar_position: 0 The Embrace Apple SDK is designed to provide first class observability and diagnostic data collection to your mobile application. It supports multiple platforms including iOS, iPadOS, and tvOS. -## Major Versions Available +## Recommended Major Version - Apple 6.x -Presently there are __two__ major versions of the Apple SDK available: 5 and 6. +Our Apple 6.x SDK is recommended for all current and new customers. The 6.x SDK is our [open-source](https://github.com/embrace-io/embrace-apple-sdk) superset of [OpenTelemetry](https://opentelemetry.io) instrumentation, built in Swift for modern language (such as async/await) and mobile observability (spans, logs) features. It has all the latest Embrace features and semantics, and will continue to grow as Embrace helps expand the OTel ecosystem for mobile. -5.x is our stable, closed-source SDK that has been generally available since the year 2020. 6.x is our open-source SDK that features major enhancements to the previous SDK, and has most of the features that Embrace customers use today. +We recommend that customers use our version 6 SDK, as it contains OTel primitives, open-source support, and better use of modern Swift features like async/await. If you are upgrading from our older 5x SDK, a [migration guide](/docs/ios/open-source/upgrade-guide.md) is available to implement the new features and interface in the 6.x SDK. -Versions 5.x and 6.x are not compatible nor are they interoperable. The 6.x SDK is built on [OpenTelemetry](https://opentelemetry.io), and the features and signals that it provides have different semantics than previous versions. 6.x is also a rewrite of the SDK in the Swift programming language, so it does not include features that we won't support in the future, like Moments. +This documentation reflects information on the 6.x SDK. Current documentation for the 6.x SDK is split into three sections: -A [migration guide](/docs/ios/open-source/upgrade-guide.md) is available to implement the new features and interface in the 6.x SDK. We recommend that customers consider migrating to version 6, as it contains OTel primitives and better support for modern Swift features like async/await. +1. [**Integration Guide**](./open-source/integration/) for open-source SDK developers. +2. [**Getting Started**](./open-source/getting-started/) for users adding Embrace to your project. +3. [**Feature Reference**](./open-source/features/) for more details about Embrace features. -## 6.x SDK Documentation +## 5.x SDK Documentation -This documentation reflects information on the 6.x Open Source SDK. Current documentation for the 6.x SDK can be found in our [**6.x Apple SDK**](/ios/open-source) sections. You can begin your integration by [linking Embrace](/docs//ios/open-source/linking-embrace.md). +Embrace iOS 5.x is the closed-source SDK that has been generally available since the year 2020. It is not available for open-source developers, and is not recommended for new users. -## 5.x SDK Documentation +Versions 5.x and 6.x are not compatible nor are they interoperable. The 6.x SDK is built on [OpenTelemetry](https://opentelemetry.io), and the features and signals that it provides have different semantics and syntax than previous versions. 6.x is also a rewrite of the SDK in the Swift programming language, so it does not include features that Embrace does not intend to support in the future, like Moments. This documentation reflects information on the 5.x SDK. It is split into two sections: 1. [**Integration Guide**](./5x/integration/) 2. [**Feature Reference**](./5x/features/) -If you are just starting out with Embrace, follow the [**Integration Guide**](./5x/integration/) to learn the key steps to successfully using our product. - -Once you've completed that, browse through our [**Feature Reference**](./5x/features/) guides to learn how to use some of the advanced features our SDK provides. - ## Any questions -If you would like clarification on which SDK to use, please reach out to us on Slack or email us at [support@embrace.com](mailto:support@embrace.com). +If you would like clarification on which SDK to use, please reach out to us on the [community slack](https://community.embrace.io) or email us at [support@embrace.com](mailto:support@embrace.com). You can also view our [FAQ](/ios/faq/) and [Changelog](/ios/changelog/) diff --git a/docs/ios/open-source/features/index.md b/docs/ios/open-source/features/index.md new file mode 100644 index 00000000..760f3516 --- /dev/null +++ b/docs/ios/open-source/features/index.md @@ -0,0 +1,14 @@ +--- +title: 6x Feature Reference +description: Learn about the advanced ways Embrace can help your application +sidebar_position: 4 +--- + +# Apple SDK Reference + +The Embrace Apple SDK includes many advanced features that you can enable to help you understand more about how your application is performing in production. + +1. [Export your OpenTelemetry traces and logs](/ios/open-source/features/otel-exporter.md) using any compatible OTel Exporter. +1. Measure and prioritize performance in your app using [ Tracing](/ios/open-source/features/traces.md). +1. Dynamically segment users to understand variations and tailor diverse app experiences using [User Personas](/ios/open-source/features/metadata-personas.md). +1. Capture the vitals of any troublesome networking using [Network Body Capture](/ios/open-source/features/network-body-capture.md) diff --git a/docs/ios/open-source/metadata-personas.md b/docs/ios/open-source/features/metadata-personas.md similarity index 99% rename from docs/ios/open-source/metadata-personas.md rename to docs/ios/open-source/features/metadata-personas.md index a7105fff..09d10375 100644 --- a/docs/ios/open-source/metadata-personas.md +++ b/docs/ios/open-source/features/metadata-personas.md @@ -1,6 +1,6 @@ --- title: User Personas -sidebar_position: 9 +sidebar_position: 4 --- diff --git a/docs/ios/open-source/network-body-capture.md b/docs/ios/open-source/features/network-body-capture.md similarity index 99% rename from docs/ios/open-source/network-body-capture.md rename to docs/ios/open-source/features/network-body-capture.md index 647a140a..2b0a2e6d 100644 --- a/docs/ios/open-source/network-body-capture.md +++ b/docs/ios/open-source/features/network-body-capture.md @@ -1,7 +1,7 @@ --- title: Network Body Capture description: Embrace can capture network body requests and responses -sidebar_position: 4 +sidebar_position: 3 --- # Network Body Capture diff --git a/docs/ios/open-source/otel-exporter.md b/docs/ios/open-source/features/otel-exporter.md similarity index 93% rename from docs/ios/open-source/otel-exporter.md rename to docs/ios/open-source/features/otel-exporter.md index 2836c63b..54038182 100644 --- a/docs/ios/open-source/otel-exporter.md +++ b/docs/ios/open-source/features/otel-exporter.md @@ -1,13 +1,13 @@ --- title: OpenTelemetry Exporter -sidebar_position: 5 +sidebar_position: 2 --- # OpenTelemetry Exporter Because the 6.x iOS SDK is built on OpenTelemetry, it has the ability to export OpenTelemetry signals directly from the mobile code level, without any of the telemetry hitting our backend. -To send traces and logs from the SDK to your collector or vendor of choice, you will need to configure the SDK with an exporter capable of sending OTel signals to that destination. This will be done in the creation of the [`Embrace.Options`](./embrace-options.md), by adding an [`OpenTelemetryExport`](https://github.com/embrace-io/embrace-apple-sdk/blob/main/Sources/EmbraceCore/Public/OpenTelemetryExport.swift). +To send traces and logs from the SDK to your collector or vendor of choice, you will need to configure the SDK with an exporter capable of sending OTel signals to that destination. This will be done in the creation of the [`Embrace.Options`](/ios//open-source/integration/embrace-options.md), by adding an [`OpenTelemetryExport`](https://github.com/embrace-io/embrace-apple-sdk/blob/main/Sources/EmbraceCore/Public/OpenTelemetryExport.swift). ## Direct Exporters diff --git a/docs/ios/open-source/traces.md b/docs/ios/open-source/features/traces.md similarity index 99% rename from docs/ios/open-source/traces.md rename to docs/ios/open-source/features/traces.md index 16f0af40..2e8f045c 100644 --- a/docs/ios/open-source/traces.md +++ b/docs/ios/open-source/features/traces.md @@ -1,7 +1,7 @@ --- title: Traces description: Record spans to monitor the production performance and success rates of operations. -sidebar_position: 8 +sidebar_position: 1 --- # Traces diff --git a/docs/ios/open-source/crash-report.md b/docs/ios/open-source/getting-started/crash-report.md similarity index 93% rename from docs/ios/open-source/crash-report.md rename to docs/ios/open-source/getting-started/crash-report.md index 58de6f18..d0d5c289 100644 --- a/docs/ios/open-source/crash-report.md +++ b/docs/ios/open-source/getting-started/crash-report.md @@ -1,7 +1,7 @@ --- title: Crash Reporting description: Upload crash reports from your iOS application using the Embrace SDK -sidebar_position: 6 +sidebar_position: 1 --- # Crash Reporting @@ -14,7 +14,7 @@ Embrace can either use its own internal crash reporting logic or work alongside The first step in initializing crash reporting is configuring which mode you want Embrace to operate in. Embrace can be your primary crash reporter, or you can add Firebase Crashlytics as the crash reporter to send crashes to both Embrace ~and~ Firebase. If you choose to use Crashlytics, Embrace will mirror reports sent to Crashlytics so you will still have that data available in the Embrace Dashboard. -The crash reporter is added in the [SDK configuration step](/docs/ios//open-source/embrace-options.md). If you do not add another crash reporter, Embrace's will be used by default. If you wish to use Crashlytics, do the following: +The crash reporter is added in the [SDK configuration step](/docs/ios/open-source/integration/embrace-options.md). If you do not add another crash reporter, Embrace's will be used by default. If you wish to use Crashlytics, do the following: ```swift //import Embrace support module so that Embrace dashboard mirrors Crashlytics data diff --git a/docs/ios/open-source/getting-started/index.md b/docs/ios/open-source/getting-started/index.md new file mode 100644 index 00000000..41d3de9e --- /dev/null +++ b/docs/ios/open-source/getting-started/index.md @@ -0,0 +1,19 @@ +--- +title: Get Started With Embrace +description: Start integrating Embrace into your iOS application +sidebar_position: 3 +--- + +# Get Started With Embrace + +Once the Embrace Apple SDK is integrated into your mobile app, you can begin to send mobile signals to the Embrace backend for analysis. This section contains information on what you can expect from our commercial product. These features, such as [session reporting](/ios/open-source/getting-started/session-reporting.md) are also available for open-source users, but without the visualization provided by the Embrace dashboard. + +Read on to find out more about: + +- Adding [crash reporters](/ios/open-source/getting-started/crash-report.md) to your app. +- Making sense of [sessions](/ios/open-source/getting-started/session-reporting.md) in your app. +- Symbolicating [crash reports and dSYMs](/ios/open-source/getting-started/symbolicating-crash-reports.md) in your app. + +## Prerequisites + +To link the SDK to your Embrace dashboard, you will need an App ID. Register your app to get an App ID by [logging in to your Embrace Dashboard](/ios/5x/integration/login-embrace-dashboard.md). diff --git a/docs/ios/open-source/getting-started/session-reporting.md b/docs/ios/open-source/getting-started/session-reporting.md new file mode 100644 index 00000000..3648fb3a --- /dev/null +++ b/docs/ios/open-source/getting-started/session-reporting.md @@ -0,0 +1,23 @@ +--- +title: Session Reporting +description: Upload sessions from your mobile application using the Embrace SDK +sidebar_position: 2 +--- + +# Session Reporting + +## Create your first session + +Once Embrace is configured and started in your app, it automatically starts capturing user sessions. + +A session is any length of user experience that occurs while the app is in the foreground or background. Note that foreground sessions and background sessions behave differently, and so are recorded separately. This means that, for example, opening a push notification from your app will end a foreground session and start a background session. + +Sessions are recorded as OTel spans with Attributes and SpanEvents for various app lifecycle, user experience, and device information. Embrace always uploads sessions on subsequent launches or foregrounding/backgroundings of the app. + +You can learn more about moments and measuring performance yourself in the +[Moments](/ios/5x/features/moments) section. + +## Trigger a session upload to the dashboard + +To trigger a session upload, simply send the application to the background by pressing the simulators 'home' button or swipe up, depending on the simulator you're running, or press `Cmd+Shift+H` on your keyboard. +Typically the SDK will be given sufficient time to upload the session, but sometimes the app is not able to complete the upload in the background. To ensure the session was uploaded, launch the application again. Refresh the dashboard in your browser and you should now see that you've moved on to the next step. diff --git a/docs/ios/open-source/symbolicating-crash-reports.md b/docs/ios/open-source/getting-started/symbolicating-crash-reports.md similarity index 98% rename from docs/ios/open-source/symbolicating-crash-reports.md rename to docs/ios/open-source/getting-started/symbolicating-crash-reports.md index 43c768ec..66ddb692 100644 --- a/docs/ios/open-source/symbolicating-crash-reports.md +++ b/docs/ios/open-source/getting-started/symbolicating-crash-reports.md @@ -1,7 +1,7 @@ --- title: Symbolicating Crash Reports description: Upload your app's desymbolicated files to Embrace for readable stack traces. -sidebar_position: 7 +sidebar_position: 3 --- # Symbolicating Crash Reports diff --git a/docs/ios/open-source/index.md b/docs/ios/open-source/index.md index 8d1dede6..ee87b002 100644 --- a/docs/ios/open-source/index.md +++ b/docs/ios/open-source/index.md @@ -8,17 +8,25 @@ sidebar_position: 0 The Embrace 6.x Apple SDK is designed to provide first class observability and diagnostic data collection to your mobile application. It supports multiple platforms including iOS, iPadOS, and tvOS. +## What is in the Embrace Apple SDK? + Embrace's 6.x SDK is open-source and can be found on [GitHub](https://github.com/embrace-io/embrace-apple-sdk/). It has been designed so that any Apple developer can add the SDK to their app and transmit telemetry without using Embrace, or can use Embrace to gain the key mobile insights that we've cultivated in our [product](/docs/product/index.md). -The Embrace Apple SDK is built on OpenTelemetry signals like logs and spans, which allow you to [export the telemetry](/docs/ios/open-source/otel-exporter.md) captured in your app to other sources. We encourage you to add the SDK to your app and view the logs and traces that the SDK automatically captures, with the caveat that we can't guarantee you'll quickly make sense of it all. Embrace 6.x SDK is also built in Swift, which allows us to provide more support for modern language features like async/await. +The Embrace Apple SDK is built on OpenTelemetry signals like logs and spans, which allow you to [export the telemetry](/docs/ios/open-source/features/otel-exporter.md) captured in your app to other sources. We encourage you to add the SDK to your app and view the logs and traces that the SDK automatically captures, with the caveat that we can't guarantee you'll quickly make sense of it all. Embrace 6.x SDK is also built in Swift, which allows us to provide more support for modern language features like async/await. + +This documentation is split into three sections: + +1. [**Integration Guide**](./integration/) for open-source developers using the Embrace SDK. +2. [**Getting Started**](./getting-started/) for users adding Embrace to your project. +3. [**Feature Reference**](./features/) for more details about Embrace features. Please note that some prior functionality has been deprecated and that some method names or implementation details may differ. Further details are available in the [migration guide](/docs/ios/open-source/upgrade-guide.md). Please reach out to in the [Community Slack](https://community.embrace.io) if you have any questions. -# Built on OpenTelemetry +## Built on OpenTelemetry The 6.x iOS SDK has been rearchitected from the foundations to support and extend [OpenTelemetry](https://opentelemetry.io) for mobile. The new modular approach builds the Embrace event-based observability paradigm directly on OpenTelemetry signals, namely, [Traces](https://opentelemetry.io/docs/concepts/signals/traces/) and [Logs](https://opentelemetry.io/docs/concepts/signals/logs/). -## How we built it +### How we built it As an example, [Sessions](https://embrace.io/product/user-session-insights/) are the core of Embrace's reproduce-and-fix approach to insights. Sessions capture everything that your app is doing while foregrounded or backgrounded, until the user starts or stops using the app. Given that Sessions take place in a given time period, with different related activities occurring in that time, it shouldn't surprise anyone OTel-aware that we model Sessions as a **trace**. @@ -82,7 +90,7 @@ class SessionController { Our engineering and product teams have many ideas about Sessions and how they work within the OTel specification, or rather how they don't work presently. Despite this, we've created the tools to take this Embrace concept of Sessions and export it as opinion-free telemetry in the form of OpenTelemetry spans. -## Events mapped to OTel signals +### Events mapped to OTel signals If the prior section was too in-depth, here's a handy chart of the important Embrace SDK features and how they currently map to OpenTelemetry signals: diff --git a/docs/ios/open-source/integration/customizing-signals.md b/docs/ios/open-source/integration/customizing-signals.md new file mode 100644 index 00000000..17feee92 --- /dev/null +++ b/docs/ios/open-source/integration/customizing-signals.md @@ -0,0 +1,98 @@ +--- +title: Customizing Signals +description: Customize the Signals You Receive From Embrace +sidebar_position: 4 +--- + +# Customize the Signals You Receive From Embrace + +The Embrace Apple SDK is built to provide automatic instrumentation for the most important mobile signals, right out of the box. However, it is possible to customize the signals that you receive when you [set up](/ios/open-source/integration/embrace-options.md) the SDK. + +## Automatic Signals + +With the [convenience initializer](/ios/open-source/integration/embrace-options/#configuration-options) provided for initial setup, the SDK adds a default set of [CaptureServices](https://github.com/embrace-io/embrace-apple-sdk/blob/main/Sources/EmbraceCaptureService/CaptureService.swift) objects that instrument the app automatically. Each service is an extension of that base class, and so each service is instrumented to capture its signals and map them to OpenTelemetry spans. + +The services pre-configured by default in the [CaptureServiceBuilder](https://github.com/embrace-io/embrace-apple-sdk/blob/main/Sources/EmbraceIO/Capture/CaptureServiceBuilder.swift#L42) are: + +- `URLSessionCaptureService`: generates OpenTelemetry spans for network requests that use `URLSession`. +- `TapCaptureService`: generates OpenTelemetry span events for taps on the screen. +- `ViewCaptureService`: generates OpenTelemtry spans for `UIViewControllers`. +- `WebViewCaptureService`: generates OpenTelemetry span events when a `WKWebView` loads an URL or throws an error. +- `LowMemoryWarningCaptureService`: generates OpenTelemetry span events when the application receives a low memory warning. +- `LowPowerModeCaptureService`: generates OpenTelemetry spans when the phone is running in low power mode. + +## Customizing the Signals You Receive + +If you wish to add, remove, or change the CaptureServices that your SDK will make use of, you should explicitly add only the services that you want when initializing the SDK. When setting up the SDK using `Embrace.Options`, use the [`CaptureServiceBuilder`](https://github.com/embrace-io/embrace-apple-sdk/blob/main/Sources/EmbraceIO/Capture/CaptureServiceBuilder.swift) object to specify the services that you want before building the object: + +```swift +// in your App init, specify the CaptureServices +// Here, we add only the `URLSessionCaptureService`, `TapCaptureService`, and `ViewCaptureService` +let services = CaptureServiceBuilder() + .add(.urlSession()) + .add(.tap()) + .add(.view()) + .build() + +// then, initialize the SDK with these specified services + +try Embrace + .setup( + options: Embrace.Options( + appId: "APPID", + captureServices: services + //...other optiosn + ) + ) + .start() +``` + +## Extending `CaptureServices` to Add Your Own Instrumentation + +In addition to customizing the automatic instrumentation your app will receive from the SDK, you can add your own sets of signals that you wish to automatically extend. Adding your category of "automatic" signals extends the base class [CaptureServices](https://github.com/embrace-io/embrace-apple-sdk/blob/main/Sources/EmbraceCaptureService/CaptureService.swift) for whatever purposes you might need. After testing, you can then initialize your CaptureService with the others provided by Embrace. + +As a simple example, if you wished to automatically capture when a screenshot was taken in the app, you could extend the base CaptureService to add a span event to respond to the `UIApplication`'s `userDidTakeScreenshotNotification` notification. + +```swift +public class ScreenshotCaptureService: CaptureService { + + public var onScreenshotCaptured: (() -> Void)? + + @ThreadSafe var started = false + + deinit { + NotificationCenter.default.removeObserver(self) + } + + public override func onInstall() { + NotificationCenter.default.addObserver( + self, + selector: #selector(didTakeScreenshot), + name: NSNotification.Name.userDidTakeScreenshotNotification, + object: nil + ) + } + + @objc func didTakeScreenshot(notification: Notification) { + guard state == .active else { + return + } + + let event = RecordingSpanEvent( + name: MySemantics.ScreenshotTaken.name, + timestamp: Date(), + attributes: [ + MySemantics.keyEmbraceType: .string(MySemantics.screenshotTaken.rawValue) + ] + ) + + if add(event: event) { + onScreenshotCaptured?() + } + } +} +``` + +Additional configuration, especially to the [session span](/ios/open-source/#how-we-built-it), would be necessary to make this CaptureService useful, but you can see here how intuitive it is to add your own automatic instrumentation. + +Consider opening a pull request on the SDK's [GitHub repository](https://github.com/embrace-io/embrace-apple-sdk/) with any instrumentation you've found useful! diff --git a/docs/ios/open-source/embrace-client.md b/docs/ios/open-source/integration/embrace-client.md similarity index 99% rename from docs/ios/open-source/embrace-client.md rename to docs/ios/open-source/integration/embrace-client.md index 909e3c5c..54612445 100644 --- a/docs/ios/open-source/embrace-client.md +++ b/docs/ios/open-source/integration/embrace-client.md @@ -1,6 +1,6 @@ --- title: The Embrace Client -sidebar_position: 3 +sidebar_position: 2 --- # The Embrace Client diff --git a/docs/ios/open-source/embrace-options.md b/docs/ios/open-source/integration/embrace-options.md similarity index 99% rename from docs/ios/open-source/embrace-options.md rename to docs/ios/open-source/integration/embrace-options.md index 2428ee06..3f3c40fd 100644 --- a/docs/ios/open-source/embrace-options.md +++ b/docs/ios/open-source/integration/embrace-options.md @@ -1,6 +1,6 @@ --- title: Configuration using Embrace Options -sidebar_position: 4 +sidebar_position: 3 --- # Configuring the SDK diff --git a/docs/ios/open-source/integration/index.md b/docs/ios/open-source/integration/index.md new file mode 100644 index 00000000..3b8035a9 --- /dev/null +++ b/docs/ios/open-source/integration/index.md @@ -0,0 +1,28 @@ +--- +title: Open Source Integration +description: Add Embrace's Open Source Apple SDK to Your App +sidebar_position: 2 +--- + +# Open Source Integration + +The Embrace Apple SDK is built on OpenTelemetry and captures vital signals from mobile apps. It is available for open source developers to use, modify, and configure according the Apache-2.0 license. Adding the Embrace Apple SDK allows you to capture and export OTel spans and logs with Embrace's automatic and manual instrumentation. + +This section shows you how to set up Embrace in your app, without signing up for the Embrace commercial product. Commercial customers adding the Embrace Apple SDK for the first time should also use this section before proceeding. + +## Decisions You Need To Make + +Before you dive into integrating Embrace there are a few decisions you should make to help guide your process: + +1. Are you integrating a new App or an existing application? +1. Are you replacing an existing automated debugging SDK? +1. Do you plan to use multiple automated debugging SDKs? +1. What integration path makes sense for you? CocoaPods, SPM, or your own manual integration of the framework? + +## Integration Steps + +We recommend following these steps in order. + +- First, [link the Embrace SDK](/ios//open-source/integration/linking-embrace.md) to your Xcode project. +- Then, initialize the [Embrace Client](/ios/open-source/integration/embrace-client.md) as close to launch of your application code as possible. +- For configuration options in the SDK, read about the [`Embrace.Options`](/ios/open-source/integration/embrace-options.md) object that is used to initialize it. Also consider [customizing the signals](/ios/open-source/integration/customizing-signals.md) that the Embrace SDK automatically captures. diff --git a/docs/ios/open-source/linking-embrace.md b/docs/ios/open-source/integration/linking-embrace.md similarity index 91% rename from docs/ios/open-source/linking-embrace.md rename to docs/ios/open-source/integration/linking-embrace.md index bff5bf3e..5996d54e 100644 --- a/docs/ios/open-source/linking-embrace.md +++ b/docs/ios/open-source/integration/linking-embrace.md @@ -1,14 +1,14 @@ --- title: Linking Embrace -sidebar_position: 2 +sidebar_position: 1 --- # Linking Embrace Integrating the Embrace Apple SDK can be accomplished using either the Swift Package Manager or CocoaPods. The information below outlines the steps for both methods. Additionally, you can pull down the [open-source](https://github.com/embrace-io/embrace-apple-sdk) repository and integrate it manually if your app requires a custom setup. -1. [Swift Package Manager](/ios/open-source/linking-embrace/#swift-package-manager): Use Xcode to manage the Embrace dependency for you. -2. [CocoaPods](/ios/open-source/linking-embrace/#cocoapods): Simply add `EmbraceIO` to your Podfile to automate most of the integration process. +1. [Swift Package Manager](/ios/open-source/integration/linking-embrace/#swift-package-manager): Use Xcode to manage the Embrace dependency for you. +2. [CocoaPods](/ios/open-source/integration/linking-embrace/#cocoapods): Simply add `EmbraceIO` to your Podfile to automate most of the integration process. ## Swift Package Manager diff --git a/docs/ios/open-source/upgrade-guide.md b/docs/ios/open-source/upgrade-guide.md index ca88e4b6..0233fd6e 100644 --- a/docs/ios/open-source/upgrade-guide.md +++ b/docs/ios/open-source/upgrade-guide.md @@ -51,13 +51,13 @@ struct NewEmbraceApp: App { } ``` -For more information about starting the SDK in-code, please read [The Embrace Client](/docs/ios/open-source/embrace-client.md). For more information on configuration options, please read [Configuring the SDK](/docs/ios/open-source/embrace-options.md). +For more information about starting the SDK in-code, please read [The Embrace Client](/ios/open-source/integration/embrace-client.md). For more information on configuration options, please read [Configuring the SDK](/docs/ios/open-source/integration/embrace-options.md). ## Moments have been replaced by Traces [Moments](/docs/ios/5x/features/moments.md) have not been added to the Embrace Apple 6 SDK, and will not be available when upgrading from version 5 to version 6. We made this decision as part of our migration to build on top of OpenTelemetry APIs and to standardize the telemetry coming from our SDKs. -Luckily, [Traces](/docs/ios/open-source/traces.md) serve the same purposes as Moments, with greatly enhanced capabilities. Built on [OTel Spans](https://opentelemetry.io/docs/concepts/signals/traces/), Performance Traces capture end-to-end journeys made of multiple spans. Traces can contain many spans as "children", as well as attributes and events that offer flexibility on the client and numerous aggregation options on the backend. This instrumentation allows you trace an entire process by breaking it down into smaller units of work. +Luckily, [Traces](/docs/ios/open-source/features/traces.md) serve the same purposes as Moments, with greatly enhanced capabilities. Built on [OTel Spans](https://opentelemetry.io/docs/concepts/signals/traces/), Performance Traces capture end-to-end journeys made of multiple spans. Traces can contain many spans as "children", as well as attributes and events that offer flexibility on the client and numerous aggregation options on the backend. This instrumentation allows you trace an entire process by breaking it down into smaller units of work. A span is simply an operation occurring over a period of time. Using spans, you can track how long operations within the app take, and more. Note that, in building on existing OTel APIs, the Embrace Apple SDK does not have instrumentation for an object called a "trace". Instead, a trace is the root span for a given workflow. diff --git a/docs/open-telemetry/integration.md b/docs/open-telemetry/integration.md index bdb3a634..cdde9efe 100644 --- a/docs/open-telemetry/integration.md +++ b/docs/open-telemetry/integration.md @@ -125,7 +125,7 @@ Embrace.getInstance().addSpanExporter(grafanaCloudExporter); ### Apple -In the Embrace Apple SDK, exporters are configured at the same time that the SDK itself is configured. Any [Swift-language OTel exporter](https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters) can be attached as an optional value when the SDK is set up in [Embrace Options](/docs/ios/open-source/embrace-options.md). Multiple span exporters can be attached during configuration by using the [`otel-swift MultiSpanExporter`](https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Trace/Export/MultiSpanExporter.swift). +In the Embrace Apple SDK, exporters are configured at the same time that the SDK itself is configured. Any [Swift-language OTel exporter](https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters) can be attached as an optional value when the SDK is set up in [Embrace Options](/docs/ios/open-source/integration/embrace-options.md). Multiple span exporters can be attached during configuration by using the [`otel-swift MultiSpanExporter`](https://github.com/open-telemetry/opentelemetry-swift/blob/main/Sources/OpenTelemetrySdk/Trace/Export/MultiSpanExporter.swift). ```swift diff --git a/docs/react-native/integration/index.md b/docs/react-native/integration/index.md index db1bff27..4c48cbb3 100644 --- a/docs/react-native/integration/index.md +++ b/docs/react-native/integration/index.md @@ -27,7 +27,7 @@ This guide will walk you through integrating Embrace into your React Native appl * iOS 13.0 * Swift 5 * Known incompatibilities - * `@datadog/mobile-react-native`. More details [here](/ios/open-source/linking-embrace/#known-issues). + * `@datadog/mobile-react-native`. More details [here](/ios/open-source/integration/linking-embrace/#known-issues). ### Expo diff --git a/docs/react-native/integration/session-reporting.md b/docs/react-native/integration/session-reporting.md index c7113553..050ebcb8 100644 --- a/docs/react-native/integration/session-reporting.md +++ b/docs/react-native/integration/session-reporting.md @@ -129,7 +129,7 @@ import EmbraceIO :::warning Once the iOS SDK is being initialized in this way any configuration any parameters passed through the JS side with -`sdkConfig.ios` are ignored. Additional configuration can be applied when setting up the iOS SDK by following [these steps](/ios/open-source/embrace-options/). +`sdkConfig.ios` are ignored. Additional configuration can be applied when setting up the iOS SDK by following [these steps](/ios/open-source/integration/embrace-options/). ::: If your app delegate is in Swift you can then simply add a call `EmbraceInitializer.start()` to the start of the diff --git a/docs/react-native/integration/track-navigation-screens.md b/docs/react-native/integration/track-navigation-screens.md index 4638653b..4aa58492 100644 --- a/docs/react-native/integration/track-navigation-screens.md +++ b/docs/react-native/integration/track-navigation-screens.md @@ -129,7 +129,7 @@ Go to your embrace-config.json inside android/app/src/main and add the sdk_confi #### iOS: If you used the automated installation script or followed the manual steps for setting up the iOS SDK then you can -modify the setup in `EmbraceInitializer.swift` to remove the view capture service, see [Configurating the iOS SDK](/ios/open-source/embrace-options/) +modify the setup in `EmbraceInitializer.swift` to remove the view capture service, see [Configurating the iOS SDK](/ios/open-source/integration/embrace-options/) for more details: ```swift diff --git a/docs/unity/features/traces.md b/docs/unity/features/traces.md index bffedcd9..6f2f995e 100644 --- a/docs/unity/features/traces.md +++ b/docs/unity/features/traces.md @@ -31,7 +31,7 @@ There are also no limits to the number of child spans you can have per Root Span ### Limits -For limits pertaining to each platform, please see the Android limits [here](/android/features/traces/#limits), and the iOS limits [here](/ios/open-source/traces/#limits). +For limits pertaining to each platform, please see the Android limits [here](/android/features/traces/#limits), and the iOS limits [here](/ios/open-source/features/traces/#limits). :::warning Exceeding Limits If you exceed the listed limits, the operation with the limit-exceeding call will fail. See the API documentation for details. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 1f9a9558..552ecb80 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -199,7 +199,7 @@ const config: Config = { from: "/ios/5x/features/tracing", }, { - to: "/ios/open-source/traces", + to: "/ios/open-source/features/traces", from: "/ios/open-source/tracing", }, {