Flare Flare PHP PHP JavaScript JavaScript Protocol Protocol

Introduction

View as Markdown

If you haven't turned on tracing yet, start with turn on tracing in the quick start. This page covers the Vue-specific half: naming navigation spans after your router's routes. You can stop after the error reporting steps in the quick start and come back to this later. It isn't required to get errors into Flare.

On its own, @flareapp/js already traces page loads, client side navigations, and the fetch/XMLHttpRequest calls your page makes. It has no router though, so it names a navigation span after the raw URL it navigated to. @flareapp/vue adds the route pattern, through the router option on flareVue.

Passing your router to flareVue

There is no separate function to call, unlike some other framework integrations. @flareapp/vue has an internal traceVueRouter function, but it is not exported: it only runs through the router option below, so there is nothing named traceVueRouter for you to import. Pass your Vue Router instance as the router option when you register the plugin, and flareVue wires the route tracing in for you:

import { flare } from '@flareapp/js';
import { flareVue } from '@flareapp/vue';
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import App from './App.vue';
import Home from './pages/Home.vue';
import Product from './pages/Product.vue';

const router = createRouter({
    history: createWebHistory(),
    routes: [
        { path: '/', component: Home },
        { path: '/products/:id', component: Product },
    ],
});

flare.light('YOUR PROJECT KEY');
flare.configure({
    enableTracing: true,
    tracesSampleRate: 0.2,
});

const app = createApp(App);
app.use(router);
app.use(flareVue, { router });
app.mount('#app');

Vue Router 4 and 5 are both supported. Pass the router instance you get back from createRouter(). It makes no difference to flareVue whether you call app.use(router) before or after app.use(flareVue, { router }).

What the router integration adds

Without the router option, a browser_navigation or browser_pageload span only knows the raw URL it loaded, for example /products/482. With router passed in, both span types also contain the matched route pattern, for example /products/:id, so every visit to a product page groups together on the Pages table instead of becoming one entry for every product. When you open a single trace, you still see the URL. Flare uses the pattern to group pages, not to name the span.

The pageload span gets the route pattern too. If the router already resolved the first route when flareVue runs, Flare adds the pattern right away. If it did not, the first navigation adds it.

See the screenshot on the quick start for what a navigation span looks like in a trace.

Tracing options to set alongside it

flareVue has two options of its own that touch tracing: router, above, and profileComponents, covered in the profiling introduction. Everything else about tracing is set on the client through flare.configure(), not on the plugin. These are the ones you are most likely to want next to your router.

enableTracing is false by default. While it is off, passing router changes nothing, because no spans are recorded at all.

tracesSampleRate is the fraction of traces that gets sent, from 0 to 1, and defaults to 1. Every page load and every navigation starts its own trace, so in an app where people click around a lot, 1 adds up quickly. Something between 0.1 and 0.2 is a good starting point once you have real traffic.

tracesSampler replaces that fixed rate with a function of your own, and takes precedence over tracesSampleRate when both are set. With a router in place you can keep every page load and send only a fraction of the navigations that follow it:

flare.configure({
    enableTracing: true,
    tracesSampler: (ctx) => (ctx.spanType === 'browser_pageload' ? 1 : 0.1),
});

Watch out for one detail here. The sampling decision is made when the navigation span starts, which happens in the router's beforeEach guard, before the matched route pattern reaches Flare. So ctx.name is the raw path, for example /products/482, and never the pattern /products/:id. Branch on ctx.spanType as above, or match the raw path yourself. Read more in sampling.

idleTimeout, finalTimeout and childSpanTimeout decide when a navigation span closes. A navigation span closes idleTimeout milliseconds after its last child span ended, 1000 by default, with a hard limit of finalTimeout milliseconds from its start, 30000 by default. While the navigation is still in flight, flareVue holds the span open, so that countdown only starts once the router confirms the route. If a page fetches its data well after the route confirms, that request can start after the span already closed, and it then ends up outside the navigation instead of inside it. Raise idleTimeout when your routes load data late.

Every tracing option, with its default, is listed in the configuration reference.

Stopping the router integration

Unlike some other framework integrations, flareVue does not return a stop function for you to call. On Vue 3.5 and above, it stops the router tracing on its own when the app unmounts, by hooking into app.onUnmount(). If you are on an older Vue 3.x release, without app.onUnmount(), the router tracing is not automatically cleaned up when the app unmounts. In practice this only matters if you create and tear down more than one app instance for the same router while your page keeps running, for example in a test.

Read more

Sourcemaps Introduction

On this page