@sophonz/react-native-tracer-provider

An OpenTelemetry TracerProvider backed by the native Sophonz SDKs. Spans created through the OpenTelemetry JS API, by your code or by an instrumentation library, are recorded natively in the same session as everything else. Requires @sophonz/react-native.

Install

npm:

npm install @sophonz/react-native-tracer-provider

yarn:

yarn add @sophonz/react-native-tracer-provider

For iOS you will also need to install or update pods for the application:

cd ios && pod install --repo-update

Setup in your code

Initialize the Tracer Provider near the start of your app's cycle. The Sophonz SDK will need to have started before you can use the tracer provider. To achieve this you can either start the SDK before the component that sets up the provider renders, or you can make use of the enabled parameter on the useSophonzNativeTracerProvider hook to prevent it from triggering until the SDK is ready as in this example:

const {isStarted} = useSophonz({
  ios: {collectorUrl: "https://in.sophonz.ai", appKey: "sk_..."},
});

const optionalConfig = {...}; // See SophonzNativeTracerProviderConfig in ./src/types/ for possible options
const {tracerProvider: sophonzTracerProvider, tracer: sophonzTracer} = useSophonzNativeTracerProvider(optionalConfig, isStarted);

You can then use the provided tracer to add custom instrumentations to your application:

const MyScreen = () => {
  useEffect(() => {
    span = sophonzTracer.startSpan("my-span");

    someAsyncOperation().then(() => span.end());
  }, []);
  return <View />;
};

If you'd prefer not to have to pass around the tracer object you can instead leverage helpers from the @opentelemetry/api library. First register the Sophonz tracer provider as the global one:

import { trace } from "@opentelemetry/api";
trace.setGlobalTracerProvider(sophonzTracerProvider);

You can then create new tracers on the fly where needed and the getTracer method from the OTel API will know to use Sophonz as the tracer provider:

import { trace } from "@opentelemetry/api";

const MyScreen = () => {
  useEffect(() => {
    const tracer = trace.getTracer("my-application");
    
    span = tracer.startSpan("my-span");

    someAsyncOperation().then(() => span.end());
  }, []);

  return <View />;
};

This method of registering the tracer provider globally also means that any OTel instrumentation libraries in your app to will now automatically be able to find Sophonz's provider and use it for tracing.

Limitations

• Because the bridge is asynchronous, span.spanContext() returns a blank context if called right after startSpan without yielding. Use spanContextAsync() instead, or configure spanContextSyncBehaviour: "throw":

  const mySpan = tracer.startSpan("my-span");
  const spanContext = await (mySpan as SophonzNativeSpan).spanContextAsync();

• parentSpanId is not set when the parent ended in an earlier session than the one the child starts in.

On iOS spans go through Sophonz.shared.createSpan, since the Apple SDK exposes no OpenTelemetry TracerProvider:

• span kind is ignored, every span is internal
• span.updateName is ignored
• the tracer's name, version and schema URL are not recorded
• array attribute values are recorded as their string form
• a spz.type attribute becomes the span's type (the navigation package relies on this for ux.view)
• an ERROR status message is kept as the otel.status_description attribute