Documentation Grafana Cloud Monitor applications Frontend Observability Instrument Tracing

Capture traces in Faro

Tracing collects and reports a detailed view of what occurs each time a user interacts with an application. Because tracing captures an application’s flow and data progression, it yields a considerable amount of data.

The tracing instrumentation performs analysis on the browser of your application. It relies on OpenTelemetry to collect the data and it leverages the faro.api.pushTraces() function to report it.

For example, if you have an application with a frontend that calls an API that stores data in a database, you can use the tracing instrumentation to:

• Track what happens in your application when the user clicks a button, which APIs are called, the amount of time spent on the request, and so on.
• Associate actions that occur in the frontend of your application with actions that occur in the API of your application.
• Determine the amount of time spent on specific HTTP requests and the amount of time spent on different events of an HTTP request, for example, domain lookup and so on.

By default, tracing uses the following OpenTelemetry instruments:

• @opentelemetry/instrumentation-fetch
• @opentelemetry/instrumentation-xml-http-request

How to use the tracing instrumentation

The following tracing instrumentation is not enabled by default. You must manually enable it.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [
    // Other instrumentations

    // Don't forget to add the other instrumentations as well
    ...getWebInstrumentations(),

    new TracingInstrumentation({
      // Optional, if you want to add custom attributes to the resource
      resourceAttributes: {
        'my.attribute': 'my-attribute-value',
      },

      // Optional, if you want to replace the default W3C Trace Context Propagator
      propagator: new MyPropagator(),

      // Optional, if you want to overwrite the default Zone Context Manager
      contextManager: new MyContextManager(),

      // Optional, if you want to overwrite the default instrumentations or set ignore URLs
      instrumentations: [
        ...getDefaultOTELInstrumentations({
          // URLs defined here are ignored by the HTTP requests instrumentations
          ignoreUrls: [/localhost:3000/],
        }),

        new MyOtherOTELInstrumentation(),
      ],
    }),
  ],
});

Configuration

The TracingInstrumentation class provides the following configuration options to pass to the web-tracing instrumentation when you instantiate the class.

ts Copy

new TracingInstrumentation({
  /* options */
});

• ignoreUrls: Specify endpoint URLs to ignore from tracking. Faro handles the configuration for ignored URLs globally and it’s recommended that you use that option instead. Use the web-tracing specific setting only if you need to override the default behavior of the web-tracing package’s custom instruments.
• propagateTraceHeaderCorsUrls: Specify which URLs should include trace headers for cross-origin resource sharing (CORS) requests.
• fetchInstrumentationOptions: Specific options to configure the OpenTelemetry fetch instrumentation
  • applyCustomAttributesOnSpan: A custom function to modify span attributes
  • ignoreNetworkEvents: Enable this flag to add additional network events to each requests.
• xhrInstrumentationOptions: Specific options to configure the OpenTelemetry xml-http-request instrumentation
  • applyCustomAttributesOnSpan: A custom function to modify span attributes
  • ignoreNetworkEvents: Enable this flag to add additional network events to each requests.

ts Copy

type DefaultInstrumentationsOptions = {
  ignoreUrls?: MatchUrlDefinitions;
  propagateTraceHeaderCorsUrls?: MatchUrlDefinitions;

  fetchInstrumentationOptions?: {
    applyCustomAttributesOnSpan?: FetchCustomAttributeFunction;
    ignoreNetworkEvents?: boolean;
  };

  xhrInstrumentationOptions?: {
    applyCustomAttributesOnSpan?: XHRCustomAttributeFunction;
    ignoreNetworkEvents?: boolean;
  };
};