splunk_otel_flutter 1.0.0-dev.1

Splunk Flutter Agent

Splunk Distribution of OpenTelemetry for Flutter

Important

Splunk Flutter instrumentation distribution is in alpha state and subject to the terms at https://www.splunk.com/en_us/legal/pre-release-agreement-for-hosted-services.html.

Overview

The Splunk Distribution of OpenTelemetry for Flutter provides automatic instrumentation for Flutter applications running on Android and iOS devices. This library captures telemetry data including:

• Application lifecycle events
• Network request instrumentation
• User interactions and navigation tracking
• App startup and performance metrics
• Crash reporting
• Slow rendering detection (Android)
• ANR (Application Not Responding) detection (Android)
• Custom event and workflow tracking

Requirements

• Flutter SDK: >=3.32.0
• Dart SDK: >=3.8.0 <4.0.0
• iOS: 15.0+
• Android: API level 24+ (minSdkVersion 24)

Installation

Add this package to your pubspec.yaml:

dependencies:
  splunk_otel_flutter: ^1.0.0-dev.1

Then run:

flutter pub get

Android Setup

Activate desugaring in your application

1. In your application module's build.gradle file, update the compileOptions and dependencies sections:

android {
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        // If this setting is present, jvmTarget must be "1.8"
        jvmTarget = "1.8"
    }
}

dependencies {
    // For AGP 7.4+
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.3'
    // For AGP 7.3
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.2.3'
    // For AGP 4.0 to 7.2
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.9'
}

2. Ensure minSdkVersion is 24 or higher in your build.gradle:

android {
    defaultConfig {
        minSdkVersion 24
    }
}

3. Save and sync your project.

iOS Setup

Enable Swift Package Manager

Enable Swift Package Manager for your Flutter project:

flutter config --enable-swift-package-manager

For more information, see the official Flutter documentation on Swift Package Manager.

Quick Start

1. Initialize the SDK

Initialize the SDK in your app's main() function before running your app:

import 'package:splunk_otel_flutter/splunk_otel_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await SplunkRum.instance.install(
    agentConfiguration: AgentConfiguration(
      endpointConfiguration: EndpointConfiguration.forRum(
        realm: 'us0',
        rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
      ),
      appName: 'MyApp',
      deploymentEnvironment: 'production',
    ),
  );

  runApp(MyApp());
}

Configuration

Module Configuration

Control which features are enabled by passing module configurations:

await SplunkRum.instance.install(
  agentConfiguration: AgentConfiguration(
    endpointConfiguration: EndpointConfiguration.forRum(
      realm: 'us0',
      rumAccessToken: 'YOUR_RUM_ACCESS_TOKEN',
    ),
    appName: 'MyApp',
    deploymentEnvironment: 'production',
  ),
  moduleConfigurations: [
    NavigationModuleConfiguration(isEnabled: true),
    SlowRenderingModuleConfiguration(
      isEnabled: true,
      interval: const Duration(seconds: 1),
    ),
    AnrModuleConfiguration(isEnabled: true),
    CrashReportsModuleConfiguration(isEnabled: true),
  ],
);

Global Attributes

Add custom attributes to all telemetry:

import 'package:splunk_otel_flutter/splunk_otel_flutter.dart';

// Set a single attribute
await SplunkRum.instance.globalAttributes.setString(
  key: 'user.id',
  value: '12345',
);

// Set multiple attributes
await SplunkRum.instance.globalAttributes.setAll(
  attributes: MutableAttributes(
    attributes: {
      'app.version': MutableAttributeString(value: '1.2.3'),
      'user.isPremium': MutableAttributeBool(value: true),
    },
  ),
);

User Tracking

Control user session tracking:

import 'package:splunk_otel_flutter/splunk_otel_flutter.dart';

// Set tracking mode
await SplunkRum.instance.user.preferences.setTrackingMode(
  userTrackingMode: UserTrackingMode.anonymousTracking,
);

Custom Events

Track custom events:

import 'package:splunk_otel_flutter/splunk_otel_flutter.dart';

// Track a simple event
await SplunkRum.instance.customTracking.trackCustomEvent(
  name: 'purchase_completed',
  attributes: MutableAttributes(
    attributes: {
      'product.id': MutableAttributeString(value: 'abc123'),
      'product.price': MutableAttributeDouble(value: 99.99),
    },
  ),
);

// Track a workflow with duration
final workflow = await SplunkRum.instance.customTracking.startWorkflow(
  name: 'checkout',
);
// ... perform checkout steps ...
await workflow.end();

Navigation Tracking

Manually track screen navigation events:

import 'package:splunk_otel_flutter/splunk_otel_flutter.dart';

// Track a screen view
await SplunkRum.instance.navigation.track(
  screenName: 'HomeScreen',
);

Testing

For unit tests, you can mock the SDK by creating a test implementation or using dependency injection to provide a testable interface.

Troubleshooting

Common Issues

1. Build errors on Android

   • Ensure minSdkVersion is 24 or higher
   • Verify desugaring is properly configured
   • Clean build: flutter clean && flutter pub get

2. Build errors on iOS

   • Ensure you're using iOS 15.0+ as minimum deployment target
   • Verify Swift Package Manager is enabled: flutter config --enable-swift-package-manager
   • Clean build: flutter clean && flutter pub get

3. SDK not initializing

   • Ensure WidgetsFlutterBinding.ensureInitialized() is called before install()
   • Verify your RUM access token and realm are correct
   • Check that the SDK is installed before accessing SplunkRum.instance

Contributing

Contributions are welcome! See the Contributing Guide.

Support

• GitHub Issues
• Splunk Observability Documentation
• Flutter Instrumentation Guide

License

Copyright 2025 Splunk Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

ℹ️ SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.