Flutter Monitoring API

Note: Flutter Monitoring is currently in open beta.

Instana Flutter agent API

The following section describes the usage of the Instana Flutter agent. Instana's Flutter agent can be used via the InstanaAgent class methods explained below.


We recommend initializing Instana in initState() of app state class, as early as possible:

static Future<void> setup({ String key,  String reportingUrl}) async


key (String) Instana monitoring configuration key
reportingURL (String) URL pointing to the Instana instance to which to the send monitoring data to


void initState() {
Future<void> setupInstana() async {
    await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL');

Error handling

All of the agent's interfaces return an asynchronous Future. Error are wrapped in an exception of the PlatformException type.

We advise developers to follow the common error-handling techniques for Futures and to log possible errors.

For example:

InstanaAgent.setup(key: 'KEY', reportingUrl: 'REPORTING_URL')
    .catchError((e) => 
            log("Captured PlatformException during Instana setup: $e")

Or similarly in async functions:

try {
  var result = await InstanaAgent.setup(key: 'KEY', reportingUrl: 'REPORTING_URL');
} catch (e) {
  log("Captured PlatformException during Instana setup: $e");

Session Identifier

Each Instana agent instance has an unique session identifier you could use for other purposes in your app.

static Future<String> getSessionID() async




var sessionID = await Instana.getSessionID();

Manual HTTP monitoring

With Flutter HTTP sessions must be be captured manually. Please refer to the documentation specific to each platform for more details.

static Future<Marker> startCapture({ String url,  String method, String viewName}) async


url (URL) The URL to capture.
method (String) The HTTP method of the request.
viewName (String, optional) Optional name of the visible view related to this request




final url = 'http://www.example.com/album'
var marker = await InstanaAgent.startCapture(url: url, method: 'GET', viewName: 'Album');

Set response details

Once the reponse has been finished you can set the response size and the http response status code on the Marker.

Set response size

marker.responseSizeHeader = 50; // Size of the HTTP header
marker.responseSizeBody = 1000; // Size of the http body
marker.responseSizeBodyDecoded = 2400; // // Size of the decoded http body

Set http response status code

marker.responseStatusCode = 200; // The http status code 

Set Instana's backend tracing ID

Identifier to create a backend trace for the http request & response. This identifier is provided in the http header field server-timing like: server-timing: intid;desc=be01a91da80e33.

marker.backendTracingID = 'be01a91da80e33'; // the backend tracing id

For the sake of convenience, we provide you with the BackendTracingIDParser helper class which will you can use to extract a response's backend tracing ID:

var Map<String,String> headers = getResponseHeaders(); // You need to get this map from your `response` object
var backendTracingID = BackendTracingIDParser.fromHeadersMap(headers);

Set error message

For failing http request you can set an arbitrary error message.

marker.errorMessage = 'Download of album failed'; // the backend tracing id

Finish HTTP Capture

After setting the response details you must call finish on the Marker to finalize the capture.


Cancel HTTP Capture

You can also cancel pending Marker



Instana can segment mobile app insights by logical views. To do so, set the view name via the InstanaAgent.setView(String) method. The view will then be associated to all monitored beacons until the view changes once setView is called again.

We recommend not to use technical or generic names like the Class (e.g. WebViewActivity) to define views. We recommend the usage of readable names for views, for example product detail page or payment selection. Focusing on what users are experience will allow team members without intimate knowledge of the codebase to understand the insights provided.

Note: InstanaAgent.setView(String) should be called when a screen is presented to the user, rather than when a screen is created (as in a Fragment which could be created once but shown multiple times). Setting the view name will also enable Instana to track page transitions in addition to page loads.

static Future<void> setView(String name) async


name (String) The name of the view.


await InstanaAgent.setView('Webview: FitBit authorization');

Identifying Users

User-specific information can optionally be sent with data transmitted to Instana. This information can then be used to unlock additional capabilities such as:

  • calculate the number of users affected by errors,
  • to filter data for specific users and
  • to see which user initiated a view change or HTTP request.

By default, Instana will not associate any user-identifiable information to beacons. Please be aware of the respective data protection laws when choosing to do so. We generally recommend identification of users via a user ID. For Instana this is a completely transparent String that is only used to calculate certain metrics. userName and userEmail can also be used to have access to more filters and a more pleasant presentation of user information.

In cases in which you are handling anonymous users and thus don't have access to user IDs you could alternatively use session IDs. Session IDs are not as helpful as user IDs when filtering data but they are a good indicator to calculate affected/unique user metrics. We recommend setting a user name such as Anonymous to have a clear differentiation between authenticated and unauthenticated users. Session IDs can be sensitive data (depending on the framework/platform used). Please consider hashing session IDs to avoid transmitting data to Instana that can grant access.

It is important to note that data already transmitted to Instana's server cannot be retroactively updated. For this reason it is important to call this API as early as possible in the app launch process.

static Future<void> setUserID(String userID) async
static Future<void> setUserName(String name) async
static Future<void> setUserEmail(String email) async


id (String) An identifier for the user.
email (String) The user's email address.
name (String) The user's name.


void initState() {

  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL');
  await InstanaAgent.setUserID('1234567890');
  await InstanaAgent.setUserName('John Appleseed');
  await InstanaAgent.setUserEmail('[email protected]');

Meta data

Arbitrary meta data can optionally be attached to all data transmitted to Instana. Consider using this to track UI configuration values, settings, feature flags… any additional context that might be useful for analysis.

Note: we currently support up to 50 meta key/value pairs.

static Future<void> setMeta({ String key,  String value}) async


value (String) The value of the key-value pair you want to add as meta data.
key (String) The key of the key-value pair you want to add as meta data.


await InstanaAgent.setMeta(key: 'exampleKey', value: 'Some Value');

Report Custom Events

Custom events enable reporting about non-standard activities, important interactions and custom timings to Instana. This can be especially helpful when analyzing uncaught errors (breadcrumbs) and to track additional performance metrics.

static Future<void> reportEvent({ String name, EventOptions options}) async


name (String) Defines what kind of event has happened in your app that should result in the transmission of a custom beacon.
options (EventOptions, optional) A timestamp in milliseconds since Epoch indicating at which time the event started. Falls back to now() - duration when not defined.


startTime (int) A timestamp in milliseconds since Epoch indicating at which time the event started. Falls back to now() - duration when not defined.
duration (int) The duration in milliseconds of how long the event lasted. Default is zero
viewName (String) You can pass a String to group the request to a view. If you send explicitly nil, the viewName will be ignored. Alternatively you can leave out the parameter viewName to use the current view name you did set in setView(String))
meta (Map<String, String>) A JavaScript object with string values which can be used to send metadata to Instana just for this singular event. In contrast to the usage of the metadata API, this metadata is not included in subsequent beacons.
backendTracingID (String) Identifier to create a backend trace for this event.


await InstanaAgent.reportEvent(
      name: 'advancedCustomEvent',
      options: EventOptions()
        ..viewName = 'customViewName'
        ..startTime = DateTime.now().millisecondsSinceEpoch
        ..duration = 3 * 1000
        ..meta = {
          'customKey1': 'customValue1',
          'customKey2': 'customValue2'