Merge pull request #4 from embrace-io/flutter-docs

Update flutter docs for 3.0.0

docs/flutter/changelog.md

@@ -6,6 +6,12 @@ sidebar_position: 4
 
 # Flutter SDK Changelog
 
+# 3.0.0
+*Sep 17, 2024*
+* Updated Embrace Android SDK to 6.13.0.
+* Updated Embrace iOS SDK to 6.4.0.
+* Added Tracing API for capturing spans/events
+
 ## 2.0.0
 *Mar 13, 2024*
 * Removed deprecated methods.

docs/flutter/features/identify-users.md

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 # Know Your Users
 
-Embrace offers two ways you can annotate sessions with information that will help developers and customer service agents find 
+Embrace offers two methods of annotating sessions with information that will help developers and customer service agents find
 sessions for an unhappy user.
 
 1. [**User Personas**](/flutter/features/identify-users/#user-personas). This is data you can set and update about the user of a session.

docs/flutter/features/index.md

@@ -6,10 +6,10 @@ sidebar_position: 2
 
 # Flutter Feature Reference
 
-Embrace's SDK includes many advanced features that you can enable to help you understand more about
+Embrace's SDK includes many advanced features that help you understand more about
 how your application is performing in production.
 
-1. [**Moments.**](/flutter/features/moments/) In this section you will learn how you can use Embrace to go beyond logging and crashes and start to examine critical user flows within your application. Measure performance, completion and abandonment easily and consistently.
+1. [**Tracing.**](/flutter/features/tracing/) In this section you will learn how you can use Embrace to go beyond logging and crashes and start to examine critical user flows within your application. Measure performance, completion and abandonment easily and consistently.
 1. [**Know your users.**](/flutter/features/identify-users/) Add your own custom identifiers to users and sessions to make sure you can aggregate and find sessions correctly.
 1. [**Capture network requests.**](/flutter/features/network-requests/) Automatically capture network requests made by your application.
 1. [**Push Notifications.**](/flutter/features/push-notifications) Embrace can automatically capture push notifications received. Learn how to configure this feature.

docs/flutter/features/last-run-end-state.md

@@ -38,7 +38,7 @@ final didCrashLastRun = await Embrace.instance.getLastRunEndState() == LastRunEn
 
 - The API can only be called after the SDK has been started. If a call is made prior to starting the Embrace SDK you will get a response of `LastRunEndState.invalid`
 - It will return that a crash occurred if the app crashed any time since the app last came to the foreground. This includes if the app crashed while running in the background.
-- This feature only works with the Embrace crash reporter on iOS. It is **not** compatible if you use Crashlytics for crash reporting.
+- On iOS, this feature only works when the Embrace crash reporter is enabled. It is **not** compatible if you use Crashlytics for crash reporting.
 
 ### Version
 

docs/flutter/features/network-requests.md

@@ -6,11 +6,11 @@ sidebar_position: 3
 
 # Network Requests
 
-If you are using the [http package](https://pub.dev/packages/http) or the [Dio package](https://pub.dev/packages/dio) to perform your network operations, Embrace can capture that information with minimal modification to your codebase. Also, if you are using other method, network requests can be manually logged through the Embrace SDK.
+If you use the [http package](https://pub.dev/packages/http) or the [Dio package](https://pub.dev/packages/dio) to perform network operations, Embrace can capture that information with minimal modification to your codebase. If you are using other solutions, network requests can be manually logged through the Embrace SDK.
 
 ## Using the http package
 
-If you are using the [http package](https://pub.dev/packages/http), you should use an instance of `EmbraceHttpClient` to perform 
+If you use the [http package](https://pub.dev/packages/http), you should use an instance of `EmbraceHttpClient` to perform
 network operations, like this:
 
 ```dart
@@ -46,7 +46,7 @@ var dio = Dio();
 dio.interceptors.add(EmbraceInterceptor());
 ```
 
-Keep in mind that you will need to add the `embrace_dio` package to your `pubspec.yaml` to be able to use `EmbraceInterceptor`.
+Keep in mind that you will need to add the `embrace_dio` package to your `pubspec.yaml` to use `EmbraceInterceptor`.
 
 ## Manually logging network requests
 
@@ -71,5 +71,6 @@ void logNetworkRequest({
     required int statusCode,
     String? error,
     String? traceId,
+    String? w3cTraceParent,
 });
 ```

docs/flutter/features/push-notifications.md

@@ -24,11 +24,23 @@ If you want to capture data from inside the notifications then you can set the c
 
 ## iOS configuration
 
-Push notifications capture is controlled by the local config `PUSH_NOTIFICATIONS_CAPTURE_MODE` in the `Embrace-Info.plist` file. To enable this functionality, this config must be set to `automatic` (to disable it again, the config can be set to the default `manual`).
+Push notifications capture is controlled by supplying a `captureService` when initializing the iOS SDK. To enable this functionality, add the following to where Embrace is initialized in your `AppDelegate`:
 
-:::info
-If you want to prevent any data inside the notifications from being captured, you can set the local config `ENABLE_PUSH_NOTIFICATIONS_DATA_CAPTURE` to `NO`.
-:::
+```swift
+let builder = CaptureServiceBuilder().addDefaults()
+builder.add(.pushNotification())
+let services = builder.build()
+
+try Embrace
+    .setup(
+        options: Embrace.Options(
+            appId: "", // Your app ID
+            captureServices: services,
+            crashReporter: EmbraceCrashReporter()
+        )
+    )
+    .start()
+```
 
 ## Manually logging push notifications
 

docs/flutter/features/tracing.md

@@ -0,0 +1,101 @@
+---
+title: Performance Tracing
+description: Record traces to monitor the production performance and success rates of operations within your mobile app.
+sidebar_position: 2
+---
+
+# Performance Tracing
+
+## Overview
+
+Embrace’s Performance Tracing solution gives you visibility into any app operation you’d like to track, including duration, success rate, and any contextual metadata collected at runtime that helps debug the root cause of your mobile app's performance issues. With our tool, you can quickly spot any bottlenecks in your app’s architecture, pinpoint areas you need to troubleshoot with high precision, and ultimately deliver a truly optimized user experience.
+
+## API Usage Examples
+
+### Start and stop a span
+
+A span typically models the lifecycle operation in your app. You can start it, let the operation finish, then stop the span, and Embrace will record how long the span took.
+
+```dart
+final span = await Embrace.instance.startSpan('my-span');
+// some lengthy operation
+await span?.stop();
+```
+
+### Add attributes to a span
+
+If you have metadata values that relate to the entire span you can add these as attributes.
+
+```dart
+final span = await Embrace.instance.startSpan('my-span');
+await span?.addAttribute('my-key', 'my-value');
+```
+
+### Add events to a span
+
+If you have an event that happens at a point in time within a span, you can add a span event. This can contain optional attributes about the event.
+
+```dart
+final span = await Embrace.instance.startSpan('my-span');
+await span?.addEvent(
+    'my-event-name',
+    attributes: {
+        'my-event-attribute-key': 'my-event-attribute-value',
+    },
+);
+```
+
+### Record an operation that already happened
+
+If an operation already happened or you don't want to call start/stop individually, it's possible to record that a span happened via `recordCompletedSpan`.
+
+```dart
+final start = DateTime.now().millisecondsSinceEpoch - 1000;
+final end = start + 500;
+final result = await Embrace.instance.recordCompletedSpan(
+    'my-recorded-span',
+    start,
+    end,
+    attributes: {'my-span-key': 'my-span-value'},
+    events: [
+    EmbraceSpanEvent(
+        name: 'my-span-event',
+        attributes: {'my-event-key': 'my-event-value'},
+        timestampMs: DateTime.now().millisecondsSinceEpoch,
+    )
+    ],
+);
+```
+
+### Add child spans
+
+It's possible to create child spans. This can be useful if you want to record finer details about an operation, for example, a network request span might have a child span of JSON serialization to see how long it took.
+
+```dart
+final span = await Embrace.instance.startSpan('my-span');
+
+if (span != null) {
+    final childSpan =
+        await Embrace.instance.startSpan('child-span', parent: span);
+    await childSpan?.stop();
+    await span.stop();
+}
+```
+
+## Export to OpenTelemetry Collectors
+
+To send telemetry to any [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) directly from your app you can setup a [SpanExporter](https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-exporter) and [LogRecordExporter](https://opentelemetry.io/docs/specs/otel/logs/sdk/#logrecordexporter). When configured, telemetry will be sent to these exporters as soon as they are recorded. More than one exporter of each signal can be configured, but be aware of the performance impact of sending too many network requests if that is applicable.
+
+:::info
+All telemetry in Embrace's Flutter SDK is routed through Embrace's Android/iOS SDKs so it's necessary to configure Android/iOS code to send Dart telemetry to your desired destination.
+:::
+
+### Android OTel export
+Please follow [this guide](/android/features/tracing) to setup OpenTelemetry collectors on Android.
+
+### iOS OTel export
+Please follow [this guide](/ios/open-source/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.
+:::

docs/flutter/integration/add-embrace-sdk.md

@@ -8,98 +8,42 @@ sidebar_position: 3
 
 ## Add the Embrace Flutter SDK to the project
 
-Add the Embrace package to `pubspec.yaml` with the following command:
+Add the Embrace package to your `pubspec.yaml`:
 
 ```shell-session
 flutter pub add embrace
 ```
 
-## Automated integration
-
-You can use the `embrace-cli` Dart package to configure your Android and iOS projects to use the Embrace SDK. Alternatively, you can perform the configuration manually.
-
-To install the Embrace CLI, run the following command from any directory:
-
-```shell-session
-dart pub global activate embrace_cli
-```
-
-## Using the Embrace CLI
-
-```mdx-code-block
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-```
-
-Run the following command to configure your project:
-
-<Tabs groupId="platform" queryString="platform">
-<TabItem value="ios" label="iOS">
-
-```shell-session
-embrace_cli installIos YOUR_APP_ID YOUR_API_TOKEN
-```
-
-</TabItem>
-<TabItem value="android" label="Android">
-
-```shell-session
-embrace_cli installAndroid YOUR_APP_ID YOUR_API_TOKEN
-```
-
-</TabItem>
-</Tabs>
-
-You can use git to see the changes that the script made.
-
-```shell-session
-git diff
-```
-
 ## iOS setup
 
-:::info
-These steps can be performed automatically with the `installIos` command when using the [Embrace CLI.](#using-the-embrace-cli)
-:::
-
-### Add the Embrace App ID
-
-You'll need to add an `Embrace-Info.plist` file at the root of the iOS project.
-
-1. Create a file called `Embrace-Info.plist` with the following content (you can find your 5-character app ID and API token in the Embrace dashboard):
-
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>API_KEY</key>
-    <string>{YOUR_APP_ID}</string>
-    <key>API_TOKEN</key>
-  	<string>{YOUR_API_TOKEN}</string>
-    <key>CRASH_REPORT_ENABLED</key>
-    <true/>
-</dict>
-</plist>
+Firstly alter the AppDelegate to initialize Embrace in the `init` function:
+
+```swift
+@UIApplicationMain
+@objc class AppDelegate: FlutterAppDelegate {
+    override init() {
+        super.init()
+        do {
+            try Embrace
+                .setup(
+                    options: Embrace.Options(
+                        appId: "", // Your App ID from Embrace Dash
+                        platform: .flutter
+                    )
+                )
+                .start()
+        } catch let e {
+            print("Error starting Embrace \(e.localizedDescription)")
+        }
+    }
+}
 ```
 
-2. Identify your root iOS Project.
-<img src={require('@site/static/images/addEmbraceInfo-1.png').default} />
-
-3. Right click on that project and select `Add Files to YOUR_PROJECT`.
-<img src={require('@site/static/images/addEmbraceInfo-2.png').default} />
-
-4. Select `Embrace-Info.plist` and click on `Add`. Do not forget to select which `Targets` you are using.
-<img src={require('@site/static/images/addEmbraceInfo-3.png').default} />
-
-5. Check if the file appears inside YOUR_PROJECT.
-<img src={require('@site/static/images/addEmbraceInfo-4.png').default} />
-
-
 ### Uploading Symbol Files
 
-To make stack traces of native crashes readable, Embrace needs the dSym symbol files of your application. These can be uploaded with a script included in the Embrace iOS SDK.
+:::info
+Embrace uploads the dSYM symbol files of your application using a script bundled with the Embrace iOS SDK. This makes stacktraces from crashes human-readable.
+:::
 
 On the Xcode Build Phase tab, add a new run script. You can find your 5-character app ID and API token in the Embrace dashboard:
 
@@ -109,10 +53,6 @@ EMBRACE_ID={YOUR_APP_ID} EMBRACE_TOKEN={YOUR_API_TOKEN} "${PODS_ROOT}/EmbraceIO/
 
 ## Android setup
 
-:::info
-These steps can be performed automatically with the `installAndroid` command when using the [Embrace CLI.](#using-the-embrace-cli)
-:::
-
 In the root-level `build.gradle` file, add the `embrace-swazzler` dependency:
 
 ```gradle