React Native Monitoring API

Setup

Initialize Instana in your App class' componentDidMount(), as early as possible:

export default class App extends Component {
  componentDidMount() {
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL, null);
    // Alternatively with configuration options
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL, {'collectionEnabled': false});
  }
}

Session identifier

Each Instana agent instance has a unique session identifier that you might use for other purposes in your app.

static getSessionID()

var sessionID = await Instana.getSessionID();

Automatic HTTP monitoring

Views

Instana can segment mobile app insights by logical views. To do so, set the view name via the Instana.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: Instana.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 setView(String name)

Instana.setView('Webview: FitBit authorization');

Identifying users

User-specific information can optionally be sent with data that is transmitted to Instana. This information can then be used to unlock more 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 does not associate any user-identifiable information to beacons. Be aware of the respective data protection laws when you are choosing to do so. Identify users through a user ID. For Instana, it is 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 might alternatively use session IDs. Session IDs are not as helpful as user IDs when you are filtering data but they are a good indicator to calculate affected or unique user metrics. Set a username such as Anonymous to have a clear differentiation between authenticated and unauthenticated users. Session IDs can be sensitive data (depending on the framework or platform used). 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 setUserID(String id)
static setUserName(String email)
static setUserEmail(String name)

export default class App extends Component {
  componentDidMount() {
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL);
    Instana.setUserID('1234567890');
    Instana.setUserEmail('instana@example.com');
    Instana.setUserName('instana react-native agent demo');
  }
}

Metadata

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

Note: Instana currently support up to 50 meta key or value pairs.

static setMeta(String key, String value)

export default class App extends Component {
  componentDidMount() {
    Instana.setMeta('randomKey1', 'randomValue1');
    Instana.setMeta('randomKey2', 'randomValue2');
  }
}

Report custom events

Custom events enable reporting about nonstandard activities, important interactions, and custom timings to Instana. It can be especially helpful when you are analyzing uncaught errors (breadcrumbs) and to track more performance metrics.

static reportEvent(String eventName, {
  startTime: Number startTime,
  duration: Number duration,
  viewName: String viewName,
  backendTraceId: String backendTraceId,
  meta: Map meta
})

Instana.reportEvent('myCustomEvent', {
  startTime: Date.now() - 500,
  duration: 300,
  viewName: 'overridenViewName',
  backendTracingId: '31ab91fc1092',
  meta: {
    state: 'running'
  },
  customMetric: 123.4567
});

Excluding URLs from Monitoring

URLs can be ignored by providing regular expressions, by adding them to the ignoreURLs list. A good scenario for usage of this function would be to ignore all HTTP requests that contain any sensitive data like a password.

Keep in mind that the Agent needs to convert each String you provide to the setIgnoreURLsByRegex method into a native regex expression for each supported platform. We highly encourage you to track any Promise rejections, which inform you about any issue the Agent encountered while you are interpreting your input.

static setIgnoreURLsByRegex([]String regexArray)

export default class App extends Component {
  componentDidMount() {
    setIgnoreURLsByRegex();
    async function setIgnoreURLsByRegex() {
      try {
        await Instana.setIgnoreURLsByRegex(["http:\/\/localhost:8081.*", "/.*([&?])password=.*/i"]);
      } catch (e) {
        console.warn(e);
      }
    }
  }

Redact URL Query parameters

Query parameters in collected URLs might contain sensitive data. Therefore, the Instana agent supports the specification of regex patterns for query parameter keys whose values need to be redacted. Any value that needs to be redacted will be replaced with the string <redacted>. The redaction happens within the Instana agent before the agent reports to the Instana server. Consequently, secrets will not reach the Instana servers for processing and will not be available for analysis in the Instana UI or retrieval by using Instana API.

By default, the Instana agent is configured with a list of three regex patterns to automatically redact query parameter values for the keys "password", "key" and "secret".

static setRedactHTTPQueryByRegex([]String regexArray)
```#### <a href="#parameters-7"><img src="../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> Parameters
{: #parameters-7}

| <div style="width:230px">Parameter</div>                              | Description                               |
| --------------------------------- | --------------------------------------------- |
| `regex ` (`[NSRegularExpression]`)  | An array of `String ` matching the keys for the values that you want to redact. |

#### <a href="#example-6"><img src="../ecosystem/icons2/anchor.svg" width="15px" height="15px"></img></a> Example {: #example-6}

```javascript {: codeblock}
export default class App extends Component {
  componentDidMount() {
    setRedactHTTPQueryByRegex();
    async function setRedactHTTPQueryByRegex() {
      try {
        await Instana.setRedactHTTPQueryByRegex(["pass(word|wort)"]);
      } catch (e) {
        console.warn(e);
      }
    }
  }

This example redacts values for the http parameter keys "password" or "passwort". The captured URL https://example.com/accounts/?password=123&passwort=459 will be collected and displayed as https://example.com/accounts/?password=<redacted>&passwort=<redacted>.

The Instana agent does not support treating path parameters (/account/ /status) or matrix parameters (/account;accountId= /status) as secrets.

Capture HTTP headers

Optionally, the Instana agent can capture the HTTP headers of every tracked request/response.

A list of regex patterns can be defined to determine which headers will be captured.

If the same header name is present in both a request and its response, only the response's header value will be kept.

static setCaptureHeadersByRegex([]String regexArray)

export default class App extends Component {
  componentDidMount() {
    setCaptureHeadersByRegex();
    async function setCaptureHeadersByRegex() {
      try {
        await Instana.setCaptureHeadersByRegex(["cache-control", "etag"]);
      } catch (e) {
        console.warn(e);
      }
    }
  }

Slow sending mode

By default, the slow sending mode feature is disabled. If required, you can enable this feature.

By default, if the sending of a beacon fails, the Instana agent tries to resend the beacon until the sending is successful. However, this behavior doesn't work well with some cellular networks. By enabling the slow sending mode feature, the beacon-sending interval is changed to the time value that is assigned to the slowSendInterval parameter. Each sending consists of only one beacon instead of a batch (a maximum of 100 beacons in a batch). The Instana agent stays in slow sending mode until one beacon is sent successfully.

The valid time range for the slowSendInterval parameter is 2-3600 seconds.

export default class App extends Component {
  componentDidMount() {
    var options = {}
    options.slowSendInterval = 120.0;
    Instana.setup('<your key>', '<your reporting url>', options);
  }
}

User session ID

By default, the user session is tracked, and the ID is a randomly generated Universally Unique Identifier (UUID). This ID remains unchanged while the app is installed. You can configure the expiration time of the user session ID by using the usiRefreshTimeIntervalInHrs parameter. The following parameter values indicate the status of the user session ID:

• Negative number: This value indicates that the user session ID never expires. The default value is -1.

• Positive number: This value means that the user session ID is refreshed after the set time, that is, a new UUID is generated and used.

• Zero: This value denoted by 0.0 means that the user session ID is disabled.

export default class App extends Component {
  componentDidMount() {
    var options = {}
    options.usiRefreshTimeIntervalInHrs = 24.0;
    Instana.setup('<your key>', '<your reporting url>', options);
  }
}