Skip to content
Docs
Main site, archipelago.banuacoder.com
Back to archipelago.banuacoder.com

Monitoring Implementations

How to add New Relic to a Flutter app with monitoring_sdk ​

Free Reference for newrelic_monitoring_impl: every variable, option and package it generates. Command: archipelago generate newrelic_monitoring_impl

Generate the New Relic vendor, get and set a per-platform app token, and enable crash reporting, interaction tracing and distributed tracing.

What you'll learn ​

  • Generating the New Relic monitoring implementation brick
  • Obtaining and configuring a per-platform app token
  • Enabling crash reporting, interaction tracing, and distributed tracing

Prerequisites ​

  • monitoring_sdk generated first (see Monitoring SDK)
  • The native agent setup from the newrelic_mobile package guide. The brick generates only the Dart side.
  • A New Relic account with a mobile application created

Step 1: Generate the Brick ​

bash
archipelago generate newrelic_monitoring_impl

Skip this step if you chose newrelic in monitoringVendors at project creation.

The prompts are:

  • appName: your app name, for example MyApp
  • isForMonorepo: leave this as true

The brick generates in infrastructure/newrelic_monitoring_impl/.

Step 2: Retrieve Your App Token ​

In the New Relic dashboard, navigate to Mobile → (your app) → Settings → Application token.

New Relic issues separate tokens per platform (iOS vs Android). Pass the correct token at build time with --dart-define:

bash
# Android
flutter build apk --dart-define=NEW_RELIC_APP_TOKEN=<android-token>

# iOS
flutter build ipa --dart-define=NEW_RELIC_APP_TOKEN=<ios-token>

Expose the value in your Env class via String.fromEnvironment('NEW_RELIC_APP_TOKEN').

Step 3: Override NewrelicRegisterModule ​

The default newRelicConfig throws UnimplementedError. You must override it.

dart
// apps/<appName>/lib/di/app_newrelic_module.dart
@module
abstract class AppNewRelicModule extends NewrelicRegisterModule {
  @override
  @lazySingleton
  NewRelicConfig get newRelicConfig => NewRelicConfig(
    appToken: Env.newRelicAppToken,
    enableCrashReporting: true,
    enableInteractionTracing: true,
    enableDistributedTracing: true,
    enableLogging: true,
  );
}

Available NewRelicConfig fields and their defaults:

FieldDefault
appTokenrequired
enableCrashReportingtrue
enableInteractionTracingtrue
enableDistributedTracingtrue
enableLoggingtrue
collectorAddressnull (New Relic default)
crashCollectorAddressnull (New Relic default)

Set collectorAddress / crashCollectorAddress only when routing through a private data center or EU endpoint.

Step 4: Check the Registration ​

You register nothing by hand. The post-generation hook adds the package to the host app pubspec.yaml. It registers NewrelicMonitoringImplPackageModule in lib/di/injector.dart.

The monitoring_impl fanout builds its vendor list when AppMonitoring is first resolved. Every vendor module must run before that. Install order does not decide the injector order. The hook rebuilds the entries from the package manifests in dependency order. Generate monitoring_sdk first when you install standalone, because the vendor imports monitoring_api.

Run the composition-root test to confirm the wiring:

bash
cd apps/<appName>
flutter test test/di/injector_test.dart

The vendor registers as an AppMonitoringVendor named MonitoringInjectorKey.newrelic.

initialize() takes no parameters. It always calls NewrelicMobile.instance.startAgent with the config. AppMonitoring starts the vendor only after diagnostics consent. Log levels map to logDebug, logInfo, logWarning and logError. recordTransaction uses startInteraction and endInteraction inside try/finally, so the interaction always closes.

Limits to know:

  • setUserContext forwards only the user ID and the email and token extras. Other keys are dropped.
  • dispose() does not stop the native agent.
  • When diagnostics consent is withdrawn, the vendor calls shutDown() and stops the agent. A later grant calls startAgent again, but the native agent may only collect again from the next app launch.

Step 5: Verify in New Relic Dashboard ​

Run the app and navigate between screens. After a few minutes, interaction traces appear under New Relic → Mobile → (your app) → Interactions. Crashes appear under Crash analysis.

Next Steps ​