How to Integrate Web-Tracing with Vue 2 Applications: Complete Setup Guide

To integrate Web-Tracing with Vue 2, install the @web-tracing/vue2 package and register it as a Vue plugin via Vue.use(), which automatically wires error handling and initializes the core SDK with your configuration.

Web-Tracing is a pure-JavaScript monitoring SDK that unifies tracking for click events, page views, performance metrics, errors, network requests, and screen recordings. For Vue 2 applications, the dedicated integration package @web-tracing/vue2 provides a plugin-based architecture that intercepts Vue-specific errors and initializes the tracing core without requiring changes to existing component logic.

Vue 2 Integration Architecture

The Vue 2 integration centers on the plugin entry point at packages/vue2/index.ts. This file exposes an install function that Vue invokes when you call Vue.use(). During installation, the plugin performs two critical operations:

1. Error Handling Override – The plugin replaces Vue.config.errorHandler with a wrapper that captures Vue rendering errors, normalizes them via parseError(), and forwards structured payloads to the core SDK using traceError(). Your original error handler, if defined, is preserved and called after the tracing logic.
2. SDK Initialization – The plugin invokes init(options) from @web-tracing/core, creating a reactive global options store and starting the event-dispatch loop for automatic page views, performance monitoring, and network interception.

The plugin re-exports core utilities such as tracePerformance, traceCustomEvent, tracePageView, and destroyTracing from @web-tracing/core, allowing you to import these pure functions directly into Vue components for manual instrumentation.

Step-by-Step Implementation

1. Install the Vue 2 Package

Add the framework-specific package to your project using your preferred package manager:

pnpm install @web-tracing/vue2

# or

npm install @web-tracing/vue2

# or

yarn add @web-tracing/vue2

2. Register the Plugin in Your Entry File

In your main.js (or main.ts), import the plugin and register it with Vue.use(), passing a configuration object that defines your DSN, sampling rates, and feature toggles:

// main.js
import Vue from 'vue'
import WebTracing from '@web-tracing/vue2'

Vue.use(WebTracing, {
  dsn: '/trackweb',              // Endpoint for sending telemetry data
  appName: 'my-vue2-app',
  debug: true,
  pv: true,                      // Enable automatic page-view tracking
  performance: true,             // Capture performance metrics
  error: true,                   // Enable error monitoring
  event: true,                   // Track click and custom events
  cacheMaxLength: 10,
  cacheWatingTime: 1000,
  userUuid: 'init_userUuid',
  scopeError: true,
  tracesSampleRate: 0.5,         // Sample 50% of traces
  ignoreErrors: ['111', /^promise/, /.*split is not .* function/],
  ignoreRequest: [/getAllTracingList/, /cleanTracingList/],

  // Optional lifecycle hooks for transforming or filtering data
  beforePushEventList(data) {
    // Modify event payload before it enters the send queue
    return data
  },
  beforeSendData(data) {
    // Return false to cancel the network request
    return data
  },
  afterSendData(data) {
    console.log('Telemetry sent:', data)
  }
})

Source: Implementation based on packages/vue2/index.ts and configuration patterns from docs/guide/starting.md.

3. Implement Manual Tracing in Components

While the plugin automatically captures Vue errors and page views, you can manually track custom events or update global settings by importing functions from @web-tracing/core:

<template>
  <button @click="trackClick">Track Interaction</button>
</template>

<script>
import { traceCustomEvent, options } from '@web-tracing/core'

export default {
  methods: {
    trackClick() {
      // Emit a structured custom event with arbitrary metadata
      traceCustomEvent({
        eventType: 'click',
        eventName: 'purchase_button_clicked',
        extra: { productId: 'SKU-123', price: 99.99 }
      })
    }
  },
  mounted() {
    // Dynamically enable screen recording at runtime
    options.value.recordScreen = true
  }
}
</script>

Source: Component usage patterns demonstrated in examples/vue2/src/views/event/index.vue.

Configuration Reference

The InitOptions interface (defined in @web-tracing/core types) accepts the following key parameters:

• dsn – The HTTP endpoint where telemetry payloads are sent.
• appName – Identifier for your application in the monitoring dashboard.
• tracesSampleRate – Number between 0 and 1 controlling the percentage of traces to capture.
• ignoreErrors – Array of strings or regular expressions for error messages to suppress.
• ignoreRequest – Array of URL patterns for network requests to exclude from tracing.

Lifecycle hooks allow you to intercept the data pipeline:

• beforePushEventList(data) – Transform or filter events before they enter the in-memory cache.
• beforeSendData(data) – Inspect or cancel the network request by returning false.
• afterSendData(data) – Execute logic after successful transmission.

Running the Official Example

To see a fully configured Vue 2 application with Web-Tracing, examine the source in examples/vue2/src/main.js within the main repository, or clone the standalone demonstration project:

git clone https://github.com/m-cheng-web/web-tracing-examples-vue2.git
cd web-tracing-examples-vue2
pnpm install
pnpm dev   # Starts Vite development server

This demo illustrates plugin registration, component-level error boundaries, and manual traceCustomEvent calls in a real-world routing context.

Summary

• Install @web-tracing/vue2 via npm, pnpm, or yarn to add the Vue-specific plugin wrapper.
• Register the plugin with Vue.use() in your entry file to automatically capture Vue errors and initialize the core SDK.
• Configure tracing behavior—including sampling rates, filtering rules, and HTTP endpoints—via the options object passed during installation.
• Import traceCustomEvent and other utilities from @web-tracing/core for manual instrumentation inside Vue components.
• Access the reactive options.value object to toggle features like screen recording at runtime without reloading the application.

Frequently Asked Questions

Does the Vue 2 plugin capture all application errors automatically?

Yes. The plugin overrides Vue.config.errorHandler in packages/vue2/index.ts to intercept component rendering errors and lifecycle exceptions. It normalizes the error object using parseError() and forwards it to the core SDK via traceError(), ensuring Vue-specific stack traces are preserved while maintaining any previously defined error handler.

Can I use Web-Tracing with Vue 2 without the plugin?

While technically possible by manually calling init() from @web-tracing/core, the plugin is strongly recommended. Without it, you would need to manually wire Vue.config.errorHandler to capture Vue-specific error contexts and normalize component stack traces, which the plugin handles automatically in packages/vue2/index.ts.

How do I dynamically change tracing options after initialization?

Import the options object from @web-tracing/core and mutate its value property (e.g., options.value.recordScreen = true). This reactive store is created when the plugin calls init() and can be updated from any Vue component to adjust sampling rates, enable screen recording, or modify the DSN at runtime.

Where can I find the complete source code for the Vue 2 integration?

The plugin implementation resides in packages/vue2/index.ts, which contains the install function and error handler wrapper. For usage examples, see examples/vue2/src/main.js for plugin registration and examples/vue2/src/views/event/index.vue for component-level tracing implementations. Documentation is available in docs/guide/starting.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}