diff --git a/docs/android/upgrading.md b/docs/android/upgrading.md
index ecc4f704..a0c4fc16 100644
--- a/docs/android/upgrading.md
+++ b/docs/android/upgrading.md
@@ -9,6 +9,33 @@
 - Only use OkHttp versions that are at least 4.0.0 (3.13.0+ supported as of 6.3.2)
 :::
 
+## Moments have been superseded by Traces
+
+[Traces](/docs/android/features/traces.md) serve the same purposes as [Moments](/docs/android/features/moments.md), 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 Android SDK does not have instrumentation for an object called a "trace". Instead, a trace is the root span for a given workflow.
+
+### Sample usage
+
+Here is an example of how spans and traces replace and enhance the existing Moment feature:
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
+<Tabs groupId="android-language" queryString="android-language">
+<TabItem value="kotlin" label="Kotlin">
+```kotlin
+val span = Embrace.getInstance().startSpan("my-identifier") // start span
+// add events and attributes to span
+span?.stop() // stop span
+```
+</TabItem>
+</Tabs>
+
+For more detail on the additional things you can do with spans please see the [Traces](/docs/android/features/traces.md) documentation.
+
 ## Remove deprecated properties from your build.gradle
 
 These 5 deprecated properties have been removed from our Gradle plugin. Please remove them from your `app/build.gradle` file.