diff --git a/CHANGELOG.md b/CHANGELOG.md index dbc5879f41..3417c8927e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,50 @@ +# 3.0.0 / 2025-09-04 + +This is the first official production version of SDK v3 containing the new architecture for tracing feature. See the [migration guide](https://github.com/DataDog/dd-sdk-android/blob/develop/MIGRATION.MD) for details. + +* [FEATURE] RUM: Create view attributes update methods. See [#2655](https://github.com/DataDog/dd-sdk-android/pull/2655) +* [IMPROVEMENT] Trace: Using `100%` instead of `20%` for the default network tracing sampling rate. Using `SAMPLED` instead of `ALL` as the default `TraceContextInjection` strategy. See [#2542](https://github.com/DataDog/dd-sdk-android/pull/2542) +* [IMPROVEMENT] Trace: Using session consistent trace sampling. See [#2544](https://github.com/DataDog/dd-sdk-android/pull/2544) +* [IMPROVEMENT] Core: Resolve batch file only during the actual write call. See [#2619](https://github.com/DataDog/dd-sdk-android/pull/2619) +* [IMPROVEMENT] Remove `forceNewBatch` API. See [#2621](https://github.com/DataDog/dd-sdk-android/pull/2621) +* [IMPROVEMENT] Core: Resolve file orchestrator for write operation from `DatadogContext`. See [#2624](https://github.com/DataDog/dd-sdk-android/pull/2624) +* [IMPROVEMENT] Introduce event processing thread. See [#2631](https://github.com/DataDog/dd-sdk-android/pull/2631) +* [IMPROVEMENT] Core: Push context changes from public API to the context thread. See [#2635](https://github.com/DataDog/dd-sdk-android/pull/2635) +* [IMPROVEMENT] Core: Make `getDatadogContext` read on the context thread. See [#2645](https://github.com/DataDog/dd-sdk-android/pull/2645) +* [IMPROVEMENT] RUM: Update RUM feature context only after event processing completion. See [#2650](https://github.com/DataDog/dd-sdk-android/pull/2650) +* [IMPROVEMENT] RUM: Align attribute propagation mechanism. See [#2654](https://github.com/DataDog/dd-sdk-android/pull/2654) +* [IMPROVEMENT] Trace: Perform lazy capture of `DatadogContext` at the span creation. See [#2662](https://github.com/DataDog/dd-sdk-android/pull/2662) +* [IMPROVEMENT] Trace: Remove deprecated `DatadogInterceptor` constructors. See [#2665](https://github.com/DataDog/dd-sdk-android/pull/2665) +* [IMPROVEMENT] Read RUM context in Session Replay in non-blocking manner. See [#2666](https://github.com/DataDog/dd-sdk-android/pull/2666) +* [IMPROVEMENT] RUM: Propagate `has_replay` flag to `RumContext` object. See [#2668](https://github.com/DataDog/dd-sdk-android/pull/2668) +* [IMPROVEMENT] RUM: Remove deprecated `startResource`. See [#2671](https://github.com/DataDog/dd-sdk-android/pull/2671) +* [IMPROVEMENT] RUM: Remove deprecated `userInfo` methods. See [#2672](https://github.com/DataDog/dd-sdk-android/pull/2672) +* [IMPROVEMENT] Custom endpoint URL are taken as is. See [#2685](https://github.com/DataDog/dd-sdk-android/pull/2685) +* [IMPROVEMENT] Logs: Don't send fatal errors to Logs, only send them to RUM. See [#2675](https://github.com/DataDog/dd-sdk-android/pull/2675) +* [IMPROVEMENT] Process feature context on the context thread. See [#2704](https://github.com/DataDog/dd-sdk-android/pull/2704) +* [IMPROVEMENT] Read feature context only when explicitly requested by the caller. See [#2716](https://github.com/DataDog/dd-sdk-android/pull/2716) +* [IMPROVEMENT] Avoid polling for `RumContext` in `VitalReaderRunnable`. See [#2728](https://github.com/DataDog/dd-sdk-android/pull/2728) +* [IMPROVEMENT] Remove feature name argument from APIs to set/remove feature context update listener. See [#2729](https://github.com/DataDog/dd-sdk-android/pull/2729) +* [IMPROVEMENT] Core: Mark `CoreFeature` properties used to create `DatadogContext` as volatile. See [#2738](https://github.com/DataDog/dd-sdk-android/pull/2738) +* [IMPROVEMENT] Core: Handle the case when `DatadogContext` is requested when SDK is getting deinitialized. See [#2740](https://github.com/DataDog/dd-sdk-android/pull/2740) +* [IMPROVEMENT] Core: Monitor backpressure of context executor. See [#2745](https://github.com/DataDog/dd-sdk-android/pull/2745) +* [IMPROVEMENT] Core: Remove default value for the `addAccountExtraInfo` call. See [#2759](https://github.com/DataDog/dd-sdk-android/pull/2759) +* [IMPROVEMENT] RUM: Make attributes argument optional in the event-related methods of RUM monitor. See [#2760](https://github.com/DataDog/dd-sdk-android/pull/2760) +* [IMPROVEMENT] Trace: Remove OpenTracing dependencies . See [#2783](https://github.com/DataDog/dd-sdk-android/pull/2783) +* [IMPROVEMENT] Trace: Update OpenTelemetry version. See [#2786](https://github.com/DataDog/dd-sdk-android/pull/2786) +* [IMPROVEMENT] Trace: Isolate implementation layer from integration modules. See [#2773](https://github.com/DataDog/dd-sdk-android/pull/2773) +* [IMPROVEMENT] Properties referencing support. See [#2793](https://github.com/DataDog/dd-sdk-android/pull/2793) +* [IMPROVEMENT] Use common-schema for common object generation. See [#2794](https://github.com/DataDog/dd-sdk-android/pull/2794) +* [IMPROVEMENT] Move session properties to `ddtags` over query parameters. See [#2812](https://github.com/DataDog/dd-sdk-android/pull/2812) +* [IMPROVEMENT] Trace: `TracingInterceptor` migration from OpenTracing to internal implementation. See [#2708](https://github.com/DataDog/dd-sdk-android/pull/2708) +* [IMPROVEMENT] Update Session Replay batch max age to 5h. See [#2842](https://github.com/DataDog/dd-sdk-android/pull/2842) +* [IMPROVEMENT] Core: Fix `clearUserInfo` API by adapting it to the context queue. See [#2847](https://github.com/DataDog/dd-sdk-android/pull/2847) +* [MAINTENANCE] Fix flaky `DatadogRumMonitor` tests. See [#2663](https://github.com/DataDog/dd-sdk-android/pull/2663) +* [MAINTENANCE] Minor cleanup. See [#2669](https://github.com/DataDog/dd-sdk-android/pull/2669) +* [MAINTENANCE] Update sample to use non-null user id. See [#2682](https://github.com/DataDog/dd-sdk-android/pull/2682) +* [MAINTENANCE] Bump Kotlin version used to `2.0.21`. See [#2766](https://github.com/DataDog/dd-sdk-android/pull/2766) +* [MAINTENANCE] Bump `minSdk` version to 23. See [#2844](https://github.com/DataDog/dd-sdk-android/pull/2844) + # 2.26.0 / 2025-08-27 * [FEATURE] RUM: Add battery and display attributes. See [#2815](https://github.com/DataDog/dd-sdk-android/pull/2815) diff --git a/MIGRATION.MD b/MIGRATION.MD index dcd78a1c33..07152d826b 100644 --- a/MIGRATION.MD +++ b/MIGRATION.MD @@ -1,3 +1,185 @@ +# Migration from 2.x to 3.0 + +The main changes introduced in SDK 3.0 compared to 2.x are: + +1. The `OpenTracing` dependency was removed because it is obsolete. + + +We replaced the `OpenTracing` classes with internal one. However we strongly encourage you to use the OTel version as the new tracing API standard. + + +### Trace product changes + +#### Migrating tracing from `OpenTracing` to `OpenTelemetry` (recommended) + +> [!WARNING] +> Note that the `OpenTelemetry` specification library [requires](https://github.com/open-telemetry/opentelemetry-java?tab=readme-ov-file#requirements) desugaring to be enabled for with projects that have a `minSdk` < 26. If this requirement cannot be met in your project see the following section. + + +1. Add the `OpenTelemetry` dependency to your `build.gradle.kts`: + +```kotlin +implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x")) +``` + +2. Replace the `OpenTracing` configuration: +```kotlin + GlobalTracer.registerIfAbsent( + AndroidTracer.Builder() + .setService(BuildConfig.APPLICATION_ID) + .build() + ) +``` + +with the `OpenTelemetry` configuration: +```kotlin + GlobalOpenTelemetry.set(object : OpenTelemetry { + private val tracerProvider = OtelTracerProvider.Builder() + .setService(BuildConfig.APPLICATION_ID) + .build() + + override fun getTracerProvider(): TracerProvider { + return tracerProvider + } + + override fun getPropagators(): ContextPropagators { + return ContextPropagators.noop() + } + }) +``` + +> [!NOTE] +> You can use the default configuration to make it even shorter in case if don't provide any additional parameters: +```kotlin + GlobalOpenTelemetry.set( + DatadogOpenTelemetry(BuildConfig.APPLICATION_ID) + ) +``` + +To access the tracer object for manual (custom) tracing, use `io.opentelemetry.api.GlobalOpenTelemetry.get()` instead of `io.opentracing.util.GlobalTracer.get()`. +For example: +```kotlin + val tracer: Tracer = GlobalOpenTelemetry + .get() + .getTracer("SampleApplicationTracer") + + val span = tracer + .spanBuilder("Executing operation") + .startSpan() + + // Code that should be instrumented + + span.end() +``` + +Refer to the official `OpenTelemetry` [documentation](https://opentelemetry.io/docs/) for more details. + +#### Migrating tracing from `OpenTracing` to `DatadogTracing` (transition period) + +> [!WARNING] +> This option has been added for compatibility and to simplify the transition from `OpenTracing` to `OpenTelemetry`, but it may not be available in future major releases. We recommend using `OpenTelemetry` as the standard for tracing tasks. However, if it is not possible to enable desugaring in your project for some reason, you can use this method. + +1. Add the `DatadogTracing` dependency to your `build.gradle.kts`: + +```kotlin +implementation(project("com.datadoghq:dd-sdk-android-trace-otel:x.x.x")) +``` + + +2.Replace the `OpenTracing` configuration: +```kotlin + GlobalTracer.registerIfAbsent( + AndroidTracer.Builder() + .setService(BuildConfig.APPLICATION_ID) + .build() + ) +``` + +with the `DatadogTracing` configuration: +```kotlin + GlobalDatadogTracer.registerIfAbsent( + DatadogTracing.newTracerBuilder() + .build() + ) +``` + + +For manual (custom) tracing use `com.datadog.android.trace.GlobalDatadogTracer.get()` instead of `io.opentracing.util.GlobalTracer.get()` to access the tracer object. +For example: +```kotlin + val tracer = GlobalDatadogTracer.get() + + val span = tracer + .buildSpan(operationName) + .start() + + // Code that should be instrumented + + span.finish() +``` +Refer to the Datadog [documentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/android?tab=kotlin) for more details. + +API changes: + +|`2.x`|`3.0` `OpenTelemetry`|`3.0` `DatadogTracing`| +|---|---|---| +|`io.opentracing.util.GlobalTracer`|`io.opentelemetry.api.GlobalOpenTelemetry`|`com.datadog.android.trace.GlobalDatadogTracer`| +|`com.datadog.android.trace.AndroidTracer`|`io.opentelemetry.api.trace.Tracer`|`com.datadog.android.trace.api.tracer.DatadogTracer`| +|`io.opentracing.Span`|`io.opentelemetry.api.trace.Span`|`com.datadog.android.trace.api.span.DatadogSpan`| +|`io.opentracing.Scope`|`io.opentelemetry.context.Scope`|`com.datadog.android.trace.api.scope.DatadogScope`| +|`io.opentracing.SpanContext`|`io.opentelemetry.api.trace.SpanContext`|`com.datadog.android.trace.api.span.DatadogSpanContext`| + +Replacement hints: + +|`2.x`|`3.0` `OpenTelemetry`|`3.0` `DatadogTracing`| +|---|---|---| +|`AndroidTracer.Builder().build()`||`DatadogTracing.newTracerBuilder().build()`| +|`AndroidTracer#setPartialFlushThreshold(Int)`|`OtelTracerProvider#setPartialFlushThreshold()`|`DatadogTracerBuilder#withPartialFlushMinSpans()`| +|`io.opentracing.SpanContext#toTraceId()`|`io.opentelemetry.api.trace.SpanContext#getTraceId()`|`DatadogSpanContext.traceId.toString()`| +|`io.opentracing.Span#setError()`|`io.opentelemetry.api.trace#recordException()`|`DatadogSpan#addThrowable()`| + +### OkHttp instrumentation changes + +The OkHttp instrumentation (`com.datadoghq:dd-sdk-android-okhttp:x.x.x`) doesn't require desugaring support. However few migration actions may be necessary. + + +API changes: + +|`2.x`|`3.0`| +|--|--| +|`TracingInterceptor(String, List, TracedRequestListener,Sampler)`| Use `TracingInterceptor.Builder()` instead.| +|`TracingInterceptor(String?,Map>, TracedRequestListener, Sampler)`| Use `TracingInterceptor.Builder()` instead.| +|`TracingInterceptor(String?,TracedRequestListener,Sampler)`|Use `TracingInterceptor.Builder()` instead.| +|`DatadogInterceptor(String?, Map>,TracedRequestListener, RumResourceAttributesProvider, Sampler)`|Use `DatadogInterceptor.Builder()` instead. | +|`DatadogInterceptor(String?,List,TracedRequestListener,RumResourceAttributesProvider,Sampler)`|Use `DatadogInterceptor.Builder()` instead.| +| `DatadogInterceptor(String?,TracedRequestListener,RumResourceAttributesProvider,Sampler) ` | Use `DatadogInterceptor.Builder()` instead. | + + +### Core product changes + +API changes: + +|`2.x`| `3.0` | +|--|------------------------------------------------------------------| +|`Datadog#setUserInfo(String?, ...)`| User info ID is now mandatory `Datadog.setUserInfo(String, ...)` | + + +### RUM product changes + +API changes: + +|`2.x`| `3.0` | +|--|-------------------------------------------------------------------------------------| +|`DatadogRumMonitor#startResource(String, String, String,Map)`| Use `startResource` method which takes `RumHttpMethod` as `method` parameter instead | +|`com.datadog.android.rum.GlobalRum`|`GlobalRum` object was renamed to `com.datadog.android.rum.GlobalRumMonitor` | +|`com.datadog.android.rum.RumMonitor#addAction()`| Parameter `attributes: Map` is now optional | +|`com.datadog.android.rum.RumMonitor#startAction()`| Parameter `attributes: Map` is now optional | +|`com.datadog.android.rum.RumMonitor#stopResource()`| Parameter `attributes: Map` is now optional | +|`com.datadog.android.rum.RumMonitor#addError()`| Parameter `attributes: Map` is now optional | +|`com.datadog.android.rum.RumMonitor#addErrorWithStacktrace()`| Parameter `attributes: Map` is now optional | +|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`| Parameter `attributes: Map` is now optional | +|`com.datadog.android.rum.internal.monitor.AdvancedNetworkRumMonitor#stopResource()`| Parameter `attributes: Map` is now optional | + # Migration from 1.x to 2.0 The main changes introduced in SDK 2.0 compared to 1.x are: