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

> Learn how to configure the DSN endpoint in web-tracing and ensure your telemetry data reports correctly. Follow our guide for seamless integration.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.

```typescript
// 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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.

```typescript
// 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`](https://github.com/m-cheng-web/web-tracing/blob/main/examples/vue3/src/main.ts):

```typescript
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:

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.