DatadogNet.Trace.Android 2.26.3.2

DatadogNet.Android

.NET for Android and .NET MAUI bindings for the native Datadog Android SDK (dd-sdk-android).

Enable Datadog Real User Monitoring, Logs, Trace, Session Replay, WebView tracking and native crash reporting from C#, in a net8.0-android, net9.0-android or net10.0-android app.

dotnet add package DatadogNet.RUM.Android

using Com.Datadog.Android;
using Com.Datadog.Android.Core.Configuration;
using Com.Datadog.Android.Privacy;
using Com.Datadog.Android.Rum;

var configuration = new Configuration.Builder(
        clientToken: "<CLIENT_TOKEN>", env: "production", variant: "", service: "my-app")
    .UseSite(DatadogSite.Us1)
    .Build();

Datadog.Initialize(context, configuration, TrackingConsent.Granted);
Rum.Enable(new RumConfiguration.Builder("<RUM_APPLICATION_ID>").Build());

Contents

• Packages
• Installing
• Usage
• Convenience API
• How this repository works
• Building locally
• Upgrading the Datadog SDK
• Releasing
• Troubleshooting
• Licence

Packages

Twelve packages. Versions are <dd-sdk-android version>.<binding revision> — 2.26.3.1 is dd-sdk-android 2.26.3, binding revision 1. The fourth component belongs to this repository and advances when the bindings or packaging change while the native artifacts stay put.

Most apps need one or two lines:

<PackageReference Include="DatadogNet.RUM.Android" Version="2.26.3.1" />
<PackageReference Include="DatadogNet.Logs.Android" Version="2.26.3.1" />

DatadogNet.Core.Android arrives transitively — you rarely reference it directly, though you will using Com.Datadog.Android; to reach Datadog.Initialize.

There is no façade package. The iOS bindings have DatadogNet.Objc.iOS, which re-exports the whole SDK, because dd-sdk-ios ships a DatadogObjc framework that does exactly that. dd-sdk-android has no equivalent, and inventing one would mean every app paying for Session Replay and NDK crash reporting to use RUM. Reference the features you actually enable.

Target frameworks: net8.0-android34.0, net9.0-android35.0, net10.0-android36.0 — except DatadogNet.SessionReplayCompose.Android, which is net9/net10 only. Compose's last net8 build pins an AndroidX SavedState old enough to collide with what a MAUI app resolves, and holding the whole repository back to match would have broken MAUI consumers of all twelve packages to keep net8 for the one that needs Compose.

Minimum API level: 23 (Android 6.0).

The .aar manifests declare 21, and earlier revisions of this README reported that. It is not reachable: those .aars depend on an AndroidX generation in which androidx.savedstate 1.4.0 declares minSdkVersion 23, and the manifest merger takes the maximum across the whole dependency graph. An app declaring 21 fails to build, not merely at runtime on Android 5:

uses-sdk:minSdkVersion 21 cannot be smaller than version 23 declared in library
… androidx.savedstate.savedstate-android.aar

So Android 5 support is not a reason to prefer the 2.x line over 3.x, whatever the manifests say. OpenTracing still is — see Usage. The tools:overrideLibrary escape the error suggests is not recommended: it forces the library in and, as the error itself says, may fail at runtime instead.

MAUI version: build with MAUI 10. See Building locally.

Installing

<ItemGroup>
  <PackageReference Include="DatadogNet.RUM.Android" Version="2.26.3.1" />
</ItemGroup>

<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">23</SupportedOSPlatformVersion>

The packages are Android-only. In a multi-targeted MAUI project, guard the reference so an iOS or Windows head does not try to restore them:

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">
  <PackageReference Include="DatadogNet.RUM.Android" Version="2.26.3.1" />
</ItemGroup>

Usage

The C# names are the Kotlin/Java ones projected into C#, so com.datadog.android.rum.Rum becomes Com.Datadog.Android.Rum.Rum and enable(...) becomes Enable(...).

samples/DatadogNet.Android.Example is a working MAUI app that does all of the below; Datadog.cs is the setup in one file.

Initialize

Once, as early as possible. In MAUI that means MauiProgram.CreateMauiApp, or better still your Application subclass — crash reporting only covers what happens after it is enabled, and startup crashes are the ones worth catching.

using Com.Datadog.Android;
using Com.Datadog.Android.Core.Configuration;
using Com.Datadog.Android.Privacy;

var configuration = new Configuration.Builder(
        clientToken: "<CLIENT_TOKEN>", env: "production", variant: "", service: "my-app")
    .UseSite(DatadogSite.Us1)          // Us1, Us3, Us5, Eu1, Ap1, Ap2, Uk1, Us1Fed, Us2Fed
    .SetBatchSize(BatchSize.Medium)
    .SetUploadFrequency(UploadFrequency.Average)
    .Build();

Datadog.Initialize(context, configuration, TrackingConsent.Granted);
Datadog.Verbosity = (int)Android.Util.LogPriority.Warn;   // SDK problems to logcat

Configuration.Builder takes all four arguments — Kotlin's defaults for variant and service do not survive into C#, so pass "" and your service name explicitly.

RUM

using Com.Datadog.Android.Rum;
using Com.Datadog.Android.Rum.Tracking;

var rum = new RumConfiguration.Builder("<RUM_APPLICATION_ID>")
    .SetSessionSampleRate(100f)
    .TrackUserInteractions()
    .UseViewTrackingStrategy(new ActivityViewTrackingStrategy(true))
    .Build();

Rum.Enable(rum);

TrackUserInteractions(), not TrackInteractions(). Datadog's own documentation still shows the latter; it does not exist in 3.x.

MAUI renders every page into a single Activity, so ActivityViewTrackingStrategy reports one view for the whole app. Report pages yourself instead:

var monitor = GlobalRumMonitor.Get();

using (monitor.StartView("checkout", "Checkout"))
{
    monitor.AddAction(RumActionType.Tap, "pay", new Dictionary<string, object?>
    {
        ["cart.total"] = 42.50m,
    });

    try { /* ... */ }
    catch (Exception exception) { monitor.AddError(exception); }
}

StartView, AddAction and AddError above are from the convenience API.

Logs

using Com.Datadog.Android.Log;

Logs.Enable(new LogsConfiguration.Builder().Build());

var logger = new Logger.Builder()
    .SetName("app")
    .SetBundleWithRumEnabled(true)
    .Build();

logger.Log(LogLevel.Info, "user signed in");
logger.Log(LogLevel.Error, "payment failed", exception, new Dictionary<string, object?>
{
    ["order.id"] = orderId,
});

Trace

using Com.Datadog.Android.Trace;
using IO.Opentracing.Util;

// Trace collides with Android.OS.Trace, so alias it.
using DdTrace = Com.Datadog.Android.Trace.Trace;

DdTrace.Enable(new TraceConfiguration.Builder().Build());

var tracer = new AndroidTracer.Builder().SetService("my-app").Build();
GlobalTracer.RegisterIfAbsent(tracer);

var span = tracer.BuildSpan("checkout").Start();
span.SetTag("cart.items", new Java.Lang.Integer(3));

using (tracer.ActivateSpan(span))
{
    // work attributed to the span
}

span.Finish();

2.x tracing is OpenTracing. AndroidTracer implements io.opentracing.Tracer, so spans, scopes and the GlobalTracer registry all come from DatadogNet.OpenTracing.Android, which arrives with DatadogNet.Trace.Android.

This is the sharpest difference from the 3.x line, which removed OpenTracing and AndroidTracer outright in favour of DatadogTracing.NewTracerBuilder and GlobalDatadogTracer. Tracing code does not port between the two lines unchanged.

The numeric SetTag overload is setTag(String, java.lang.Number), so pass new Java.Lang.Integer(3) rather than a bare 3 — a C# int binds to the generic setTag(Tag<T>, T) overload instead and will not compile.

Session Replay

using Com.Datadog.Android.Sessionreplay;

SessionReplay.Enable(new SessionReplayConfiguration.Builder(100f)
    .SetTextAndInputPrivacy(TextAndInputPrivacy.MaskAll)
    .SetImagePrivacy(ImagePrivacy.MaskAll)
    .SetTouchPrivacy(TouchPrivacy.Hide)
    .Build());

Requires RUM. The three privacy levels decide what is redacted on the device, before anything is uploaded. Loosen them deliberately. The older single SessionReplayPrivacy is deprecated upstream and still bound, but prefer the three.

Enable is static; StartRecording and StopRecording are not — they are SessionReplay.Instance.StartRecording(sdkCore). That asymmetry is upstream's, not the binding's.

Add DatadogNet.SessionReplayMaterial.Android or DatadogNet.SessionReplayCompose.Android and register the extension when your app draws Material or Compose content:

.AddExtensionSupport(new MaterialExtensionSupport())

Native crash reporting

Add DatadogNet.Ndk.Android, then enable it after initializing the SDK:

using Com.Datadog.Android.Ndk;

NdkCrashReports.Enable();

Crashes are reported on the next launch, as RUM errors and logs. Upload your native symbols to Datadog for symbolication.

Network instrumentation

Add DatadogNet.OkHttp.Android. This is what makes HTTP calls visible in RUM:

using Com.Datadog.Android.Okhttp;

var client = new OkHttpClient.Builder()
    .AddInterceptor(new DatadogInterceptor.Builder(hosts).Build())
    .EventListenerFactory(new DatadogEventListener.Factory())
    .Build();

HttpClient in .NET does not route through OkHttp unless you configure AndroidMessageHandler, so a MAUI app using HttpClient will not report resources automatically.

WebView tracking

using Com.Datadog.Android.Webview;

WebViewTracking.Enable(webView, new List<string> { "example.com" });

User info and consent

Datadog.SetUserInfo(userId: "user-123", name: "Ada Lovelace", email: "ada@example.com");
Datadog.SetTrackingConsent(TrackingConsent.Pending);

Pending collects events but holds them on the device until consent is granted or refused — which is what a prompt-on-first-launch flow wants.

Convenience API

The generated binding is a faithful projection of Kotlin, which makes some things clumsy in C#. Each package adds a small hand-written layer over it. The generated members are all still there; nothing is hidden or renamed.

The view scope is the one worth adopting everywhere: the raw API is a StartView / StopView pair matched by key, and a view left open by an early return or an exception captures every later action and error in the session.

Attribute values may be strings, any numeric type, bool, DateTime, DateTimeOffset, Guid, enums, Java.Lang.Objects, arrays and nested dictionaries. Anything else throws ArgumentException rather than being silently dropped.

What is not bound

Three groups of members are deliberately absent, each for a reason recorded next to the rule that removes it in the relevant Transforms/Metadata.xml:

• Session Replay wireframe mappers (...recorder.mapper). The hierarchy is generic and its single member erases to map(Object, …), which the generator cannot bind. The types still ship in the .aar and still run, so recording is unaffected — including through the Material and Compose extensions. What you cannot do is author a custom mapper in C#.
• The vendored dd-trace-java engine under com.datadog.trace.**, plus DDSpan, DDSpanContext and ContinuableScope from com.datadog.opentracing. In 3.x this code lives in a separate artifact that ships unbound; 2.x fuses it into dd-sdk-android-trace alongside the public API, so it is pruned by rule instead. AndroidTracer and the whole com.datadog.android.trace package bind without a single rule, and the pruned classes still ship and still run.
• A handful of internal types — EvictingQueue, SessionRebasedSampler, OkHttpRequestInfoBuilder — plus the ExecutorService members of FlushableExecutorService and the abstract build() on TracingInterceptor.BaseBuilder. All are generator failures on erased generics or covariant returns, and none is reachable from a documented API.

Kotlin constructs that do not project into C# at all are a property of the language boundary, not of these bindings: extension functions (Session Replay's View.setSessionReplayHidden, the RUM resource helpers, everything in the coroutine and Rx integrations) land on synthetic …Kt classes, and inline functions taking lambdas are not callable. Default parameter values do not exist in C#; where upstream marked a member @JvmOverloads you get the arity ladder, and where it did not, you must pass every argument.

How this repository works

Maven Central: com.datadoghq:dd-sdk-android-*:2.26.3  +  io.opentracing:*:0.32.0
        │  @(AndroidMavenLibrary) — resolves the .aar and its .pom, cached under
        │  ~/.cache/dotnet-android/MavenCacheDirectory
        ▼
   src/DatadogNet.<Package>.Android/ — binding project + committed Transforms/Metadata.xml
        │  build/BuildNugets.sh — pack twice (net9 band, net10 band), then merge
        ▼
   artifacts/*.nupkg  ──►  nuget.org

Nothing is committed and nothing is compiled from source. There is no fetch script: the .NET Android SDK resolves each module from Maven Central, and — because it reads the .pom too — fails the build when an .aar links against Java types that no referenced package provides. That check is why this repository has no libs/ directory and why a missing Java dependency is a build error here rather than a NoClassDefFoundError in somebody's app.

Why the two-pass build. Each .NET SDK's Android workload ships reference packs for the current target framework and the previous one — the .NET 9 band builds net8 + net9, the .NET 10 band builds net9 + net10. No single SDK builds all three, so BuildNugets.sh packs twice and merge-packages.py grafts the net10 assets into the net9 packages, carrying the dependency group across with them.

Four Java dependencies have no .NET binding and are embedded as plain Java rather than left to fail at runtime: Kronos (Core), JCTools and RE2/J (Trace), and androidx.metrics (RUM). Each is embedded in exactly one package — the same classes contributed twice would be dexed twice and fail the consuming app's build.

Layout

The tests consume the packed .nupkgs from artifacts/ rather than referencing the projects, so they exercise what actually gets published — including the inter-package dependencies, which a ProjectReference would bypass entirely.

DatadogNet.sln deliberately contains the binding projects and the tests but not the sample, so dotnet build DatadogNet.sln does not require the MAUI workload.

Building locally

Requires the .NET 9 and .NET 10 SDKs with the android workload, a JDK, and the Android SDK with platforms 34, 35 and 36.

./build/BuildNugets.sh          # packs all twelve into artifacts/
dotnet test tests/DatadogNet.Android.PackageTests

Run the on-emulator smoke tests against the packed packages, with an emulator already booted:

./.github/scripts/run-emulator-tests.sh 2.26.3.1 net9.0-android35.0

Build and run the sample:

cd /tmp && dotnet new globaljson --sdk-version 10.0.301 --force
dotnet build <repo>/samples/DatadogNet.Android.Example/DatadogNet.Android.Example.csproj -t:Run

The sample targets net10.0-android36.0 and needs the .NET 10 SDK, which this repository's global.json does not select — hence the scratch directory. That is a constraint on the MAUI version you build the sample with, not on what the packages support: MAUI 9 cannot build against the AndroidX generation these packages depend on, and it is an SDK defect rather than anything the bindings do. A plain MAUI 9 app with nothing but Xamarin.AndroidX.AppCompat 1.7.1.1 added fails the same way, with no Datadog package present.

Upgrading the Datadog SDK

1. Bump DatadogNativeVersion in Directory.Build.props and reset DatadogBindingRevision to 1.

2. ./build/BuildNugets.sh — every module is resolved fresh from Maven Central.

3. Re-derive the dependencies. For each module, read the Gradle module metadata, not the .pom:

   curl -s https://repo1.maven.org/maven2/com/datadoghq/dd-sdk-android-core/3.13.0/dd-sdk-android-core-3.13.0.module \
     | python3 -c "import json,sys; [print(d['group']+':'+d['module'], d['version']['requires']) for v in json.load(sys.stdin)['variants'] if v['name']=='releaseVariantReleaseRuntimePublication' for d in v.get('dependencies',[])]"
   

   The .pom is wrong: Gradle flattens the test-fixtures variant into it, so it lists JUnit, Mockito, AssertJ, Elmyr, kotlin-reflect and a dd-sdk-android.tools:unit:unspecified that resolves nowhere. Those are neutralised by the @(AndroidIgnoredJavaDependency) block in src/Datadog.Binding.props; check that list still matches after an upgrade, because dropping an entry upstream stops shipping is how a real missing dependency gets silently ignored.

4. Re-check each Transforms/Metadata.xml — but do not trust BG8A00 to tell you which rules are stale. The warning fires for rules that are demonstrably still required: removing one such rule from DatadogNet.OpenTracing.Android and rebuilding produces six errors, in a build that had just reported it matched no nodes. Check the rule's target against obj/**/api.xml instead:

   grep -c 'name="OkHttpRequestInfoBuilder"' src/DatadogNet.OkHttp.Android/obj/Release/*/api.xml
   

   A rule whose target is genuinely absent can go; one whose target is present is load-bearing whatever the warning says.

5. Run both test suites.

If Datadog adds or removes a module, add or remove a row in build/packages.tsv and the matching project — the build script, the workflows and the package tests all follow from it.

Releasing

Tag it. v2.26.3.1 builds, tests, publishes all twelve packages to nuget.org via trusted publishing, and creates a GitHub release. The tag drives which native SDK is bound, so an older line can be released by tagging it.

Pull requests publish a -beta.<pr>.<run> prerelease of the whole set.

Both run the same build.yml: pack, package tests, and the emulator smoke tests. Pull requests additionally compile the MAUI sample against the packed packages; releases do not, since the commit being tagged has already been through that check and it would otherwise put a MAUI workload install between the packages being built and being published.

Curated notes in docs/release-notes/<version>.md replace the generated commit list when present.

Troubleshooting

Nothing appears in Datadog. Check UseSite matches your organisation's region — this is the most common cause. Call Datadog.SetVerbosity((int)LogPriority.Verbose) to see the SDK's own diagnostics in logcat.

NoClassDefFoundError at runtime. A Java dependency did not make it into the app. Usually a partially restored package; clear the cached copies and restore again: rm -rf ~/.nuget/packages/datadognet.*.

Duplicate class when building the app. Two packages are contributing the same Java classes. The four embedded third-party libraries are each owned by exactly one package for this reason — if you added a PackageReference for one of them yourself, remove it.

XA4241/XA4242 when building this repository. Java dependency verification found an unsatisfied dependency. Add the matching binding PackageReference to the project; the error names the Microsoft-maintained package when one exists.

'Trace' is an ambiguous reference. Com.Datadog.Android.Trace.Trace collides with Android.OS.Trace. Alias it: using DdTrace = Com.Datadog.Android.Trace.Trace;.

'Logs' does not exist in the namespace 'DatadogNet.Logs' — or the same for Trace or SessionReplay. Your app's own namespace starts with DatadogNet., and C# resolves a bare name outward through enclosing namespaces before looking at using directives. The bindings avoid creating DatadogNet.<Feature> namespaces for exactly this reason, so if you see it, something in your solution declares one. Rename it or fully qualify the call.

RUM records one view for the whole app. Expected in MAUI: every page renders into a single Activity. Report views yourself with monitor.StartView(...).

HTTP calls do not appear as RUM resources. HttpClient does not route through OkHttp by default. Use the OkHttp client directly, or configure AndroidMessageHandler.

Licence

The binding code in this repository is MIT. The native artifacts the packages ship are built and published by Datadog and are Apache-2.0, as are Kronos, JCTools and androidx.metrics; RE2/J is under the Go licence. Every package declares MIT AND Apache-2.0 and carries the MIT text, the Apache-2.0 text and Datadog's NOTICE under licenses/.