Overview
This document contains instructions on how to set up OpenTelemetry instrumentation in your Flutter applications and view traces in SigNoz.
The package used here is an unofficial OpenTelemetry implementation.
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
Test the sample app for Flutter (replace the variables inside main.dart).
Step 1: Install the OpenTelemetry package
flutter pub add opentelemetry
Step 2: Initialize the tracer
Add imports to main.dart:
lib/main.dart
import 'package:opentelemetry/api.dart';
import 'package:opentelemetry/sdk.dart';
Configure the exporter and tracer provider:
lib/main.dart
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).
Set service.version to a per-build value, not a static string. SigNoz detects a deployment each time this value changes. Common sources:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes: inject from your Helm chart image tag or CI variable
Using self-hosted SigNoz? Most steps are identical. Update the endpoint and remove the ingestion key header as shown in Cloud → Self-Hosted.
Step 3: Create spans
lib/main.dart
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
- 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.
