#Ottrelite Instrumentation for React

Ottrelite Instrumentation for React provides two main ways to add performance tracing to your React applications:

1. React Hooks API - Manual instrumentation using React hooks like useComponentRenderTracing
2. Babel Plugin - Automatic instrumentation using the "use trace" directive

#Installation

First, ensure you are already using @ottrelite/core. Then, add this package:

npm install @ottrelite/instrumentation-react

#Features

#React Hooks API

The React API provides hooks that allow you to manually instrument your components. The main hook is useComponentRenderTracing, which traces a component's render lifecycle.

#useComponentRenderTracing

This hook traces a component's render lifecycle (i.e., any - first or subsequent - render).

function MyComponent() {
  const { markJSRenderEnd } = useComponentRenderTracing("MyComponent");

  // Your component logic here...

  const contents = <View>{/* ... */}</View>;

  markJSRenderEnd();

  return contents;
}

The hook must be called first in the component to mark the JS logic start time undelayed. Any components you render & return must first be stored in a variable, and returned after calling the hook's returned markJSRenderEnd function.

#Babel Plugin for Automatic Instrumentation

The Babel plugin automatically instruments React components and hooks using the "use trace" directive. This provides a convenient way to add tracing without manually calling hooks.

#Setting up the Babel Plugin

Add the plugin to your Babel configuration. If you are using a babel.config.js file:

module.exports = {
  ...,
  plugins: ['module:@ottrelite/instrumentation-react'],
  ...
};

#Using the "use trace" Directive

Add the "use trace" directive as the first line in functions you want to instrument:

• Function components: First line of the component function body
• Class components: First line of the render method body
• Hooks: First line of the hook function body

The directive schema is "use trace [API] [Name]" where:

• [API] (default: dev) - Either dev (Ottrelite Development API) or otel (OpenTelemetry JS SDK)
• [Name] (optional) - Custom name for the tracer; if not provided, the function/component name is used

#Functions

export function MyFunction() {
    "use trace";
    // Your  logic here
});

#Function Components

import { memo } from 'react';

export const MyComponent = memo(function MyComponent() {
    "use trace";
    
    // Your component logic here
    
    return <div>Hello World</div>;
});

When using memo(), you must either:

1. Use a named function: memo(function MyComponent() { ... })
2. Provide an explicit name: "use trace dev MyComponent"

#Class Components

import { Component } from 'react';

export class MyClassComponent extends Component {
  render() {
    'use trace';
    
    // Your render logic here
    
    return <div>Hello World</div>;
  }

  shouldComponentUpdate(nextProps, nextState, nextContext) {
    // only rerender if props, state, or context have changed
    return (
      !_.isEqual(this.props, nextProps) ||
      !_.isEqual(this.state, nextState) ||
      !_.isEqual(this.context, nextContext)
    );
  }
}

#Tracer Name Resolution

The tracer name is determined in the following priority order:

Both [API] and [Name] parameters are optional. The shortest form is "use trace" which is equivalent to "use trace dev <resolved component name>".