How to Configure the DSN Endpoint for Reporting Data in web-tracing

To configure the DSN endpoint in web-tracing, pass the dsn property containing a valid POST/GET URL to the initialization options in WebTracing or initOptions, which automatically routes all telemetry payloads to that destination while adding the endpoint to the internal ignore list to prevent self-tracing.

The dsn (Data Source Name) is the critical configuration value that tells the web-tracing SDK where to send collected telemetry—including page views, performance metrics, JavaScript errors, and custom events. In the m-cheng-web/web-tracing repository, this single string drives the entire data transmission pipeline from client to backend.

Where the DSN Is Stored: The Options Class

The SDK stores your DSN inside the global Options class defined in packages/core/src/lib/options.ts. When you initialize the library, the constructor copies your dsn value into the instance property this.dsn and immediately adds it to the request ignore list to prevent the SDK from tracing its own network calls.

// packages/core/src/lib/options.ts (lines 13-70)
class Options {
  dsn: string
  // ... other properties
  
  constructor(initOptions: InitOptions) {
    this.dsn = initOptions.dsn
    // Automatically ignore requests to the DSN endpoint
    this.ignoreRequest.push(new RegExp(initOptions.dsn))
  }
}

The initOptions function (lines 98-106 in the same file) validates that dsn is a non-empty string during startup. If omitted, the SDK will throw a validation error because the documentation marks this field as 必填 (required) in docs/guide/use/options.md.

How the SDK Sends Data to Your DSN

Once configured, the DSN is consumed by the transport layer in packages/core/src/lib/sendData.ts. The SendData.executeSend method (lines 74-89) receives options.value.dsn as the target URL and selects the most efficient transport mechanism—Beacon API, Image tag, or XMLHttpRequest—based on payload size and the sendTypeByXmlBody flag.

// packages/core/src/lib/sendData.ts
executeSend(dsn: string, data: any) {
  if (sendByBeacon(dsn, data)) return
  if (sendByImage(dsn, data)) return
  sendByXML(dsn, data)
}

When the internal event queue flushes, sendData.emit calls this.executeSend(options.value.dsn, afterSendParams). If the endpoint is unreachable, the SDK marks the server as unavailable and enters a retry loop controlled by checkRecoverInterval.

Configuring the DSN Endpoint: Practical Examples

You must provide a reachable URL—either absolute (https://api.example.com/track) or relative (/trackweb)—that accepts the SDK's POST or GET payloads.

Vue 3 Framework Integration

In a Vue 3 application, pass the DSN inside the plugin configuration object as shown in examples/vue3/src/main.ts:

import { createApp } from 'vue'
import WebTracing from '@web-tracing/vue3'

const app = createApp(App)

app.use(WebTracing, {
  // Required: Your telemetry collector endpoint
  dsn: '/trackweb',          
  // Alternative: dsn: 'https://collector.mycompany.com/v1/trace',
  
  appName: 'production-app',
  debug: true,
  pv: true,
  performance: true,
  error: true,
  
  // Optional: Exclude additional internal APIs from tracing
  ignoreRequest: [/getAllTracingList/, /cleanTracingList/]
})

app.mount('#app')

Core Package Direct Initialization

For framework-agnostic usage, import initOptions from the core package:

import { initOptions } from '@web-tracing/core'

initOptions({
  dsn: 'https://telemetry.example.com/collect',
  appName: 'micro-service',
  debug: false,
  sendTypeByXmlBody: true  // Force XMLHttpRequest for larger payloads
})

Automatic DSN Protection and Retry Logic

The SDK implements two safeguards around your DSN configuration:

• Self-tracing prevention: The constructor in options.ts automatically pushes a RegExp matching your DSN into _options.ignoreRequest, ensuring that failed delivery attempts or successful pings do not generate recursive telemetry.
• Resilience: If executeSend encounters a network error, handleServerError pauses transmission and testServerAvailable polls the DSN at intervals defined by checkRecoverInterval until the endpoint recovers.

Summary

• The DSN is required: Pass a valid URL string to dsn during initialization via WebTracing or initOptions.
• Storage location: The value lives in the Options class at packages/core/src/lib/options.ts and is accessed globally through options.value.dsn.
• Transport mechanism: SendData.executeSend in packages/core/src/lib/sendData.ts routes all data to this endpoint using Beacon, Image, or XML transports.
• Auto-ignore: The SDK automatically adds your DSN pattern to the ignore list to prevent infinite tracing loops.
• Failure handling: Unreachable DSNs trigger automatic backoff and retry logic without manual intervention.

Frequently Asked Questions

What happens if I forget to configure the DSN endpoint?

The SDK will fail to initialize. According to the validation logic in packages/core/src/lib/options.ts, initOptions checks that dsn is a non-empty string. If omitted or empty, the initialization throws an error before any telemetry collection begins.

Can I use a relative URL as the DSN endpoint?

Yes. The SDK accepts both absolute URLs (https://...) and relative paths (/trackweb). The example in examples/vue3/src/main.ts demonstrates a relative configuration where /trackweb resolves against the current domain.

Does the SDK trace its own requests to the DSN endpoint?

No. The Options constructor automatically appends a RegExp matching your DSN to the internal ignoreRequest array. This ensures that network requests sent to your telemetry collector never appear as new tracing events, preventing recursive data loops.

How does web-tracing handle DSN endpoint failures?

When SendData.executeSend fails to reach the DSN, the SDK invokes handleServerError to mark the server as unavailable. It then uses testServerAvailable to poll the endpoint at the interval specified by checkRecoverInterval (default configuration), resuming automatic transmission once the endpoint responds successfully.

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