Flutter OpenTelemetry Instrumentation Guide

Overview

This document contains instructions on how to set up OpenTelemetry instrumentation in your Flutter applications and view traces in SigNoz.

Prerequisites

• A Flutter application (Android and/or iOS targets).
• Flutter SDK installed; see the Flutter install guide.
• Access to a SigNoz Cloud account or self-hosted SigNoz instance.

Send traces to SigNoz

Step 1: Install the OpenTelemetry package

flutter pub add opentelemetry

Step 2: Initialize the tracer

Add imports to main.dart:

import 'package:opentelemetry/api.dart';
import 'package:opentelemetry/sdk.dart';

Configure the exporter and tracer provider:

final headers = {
  'signoz-ingestion-key': '<your-ingestion-key>', // Cloud only: paste your ingestion key
};
 
final exporter = CollectorExporter(
  Uri.parse('ingest.<region>.signoz.cloud:443/v1/traces'), // Cloud endpoint (keep https)
  headers: headers,
);
 
final processor = BatchSpanProcessor(exporter);
final provider = TracerProviderBase(
  processors: [processor],
  resource: Resource([
    Attribute.fromString('service.name', '<service_name>'),
    Attribute.fromString('service.version', '<service_version>'),
  ]), // set your service name and version
);
 
registerGlobalTracerProvider(provider);

Verify these values:

• <your-ingestion-key>: Your SigNoz ingestion key
• <region>: Your SigNoz Cloud region
• <service_name>: service name that will show up under Traces Explorer in SigNoz.
• <service_version> (optional): Your release version, image tag, or git SHA (e.g., 1.4.2, a01dbef8).

Step 3: Create spans

final _tracer = provider.getTracer('flutter-example');
 
void createSpan(String inputText) {
  final rootSpan = _tracer.startSpan('root-span');
  try {
    final childSpan = _tracer.startSpan('child-span', kind: SpanKind.client); // child span example
    try {
      childSpan.setAttribute(Attribute.fromString('input.name', inputText));
      // add your work here
      childSpan.addEvent('Processed input: $inputText');
    } finally {
      childSpan.end();
    }
  } finally {
    rootSpan.end();
  }
}

Step 4: Run the app

Run from Android Studio or an iOS simulator.

Validate

• In SigNoz, go to Traces Explorer and confirm that the traces for your service (for example <service_name>) are present.
• Open a recent trace and verify that spans from your Flutter app are present with the attributes you set.

Troubleshooting

Still not seeing data in SigNoz? Work through Debug missing traces, logs, and metrics, which covers SDK diagnostics, Collector connectivity, and the common ingestion errors for all three signals.

• If spans do not show up, verify the exporter endpoint (Cloud or your self-hosted collector endpoint) and confirm the device/emulator can reach it over the configured protocol (HTTP/HTTPS).

Next steps

• Explore your mobile traces in the Trace Explorer.
• Create latency and error alerts for your service using Alert Management.