---
title: "Capture traces | Grafana Cloud documentation"
description: "Faro's tracing support"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](https://opentelemetry.io/) 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`](https://www.npmjs.com/package/@opentelemetry/instrumentation-fetch)
- [`@opentelemetry/instrumentation-xml-http-request`](https://www.npmjs.com/package/@opentelemetry/instrumentation-xml-http-request)

> Note
> 
> To link the traces from the frontend with the traces from the API, the tracing instrumentation relies on a trace propagator, which by default uses `W3CTraceContextPropagator`. This propagator adds a `traceparent` header to all fetch requests that your API uses.

## How to use the tracing instrumentation

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

ts ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```ts
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```ts
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

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

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