Telemetry Configuration

Wayfinder includes optional telemetry support built on the OpenTelemetry standard. Telemetry is completely opt-in and disabled by default.

Overview

Wayfinder's telemetry system:

100% Opt-in: Disabled by default, only enabled when you explicitly configure it
OpenTelemetry Standard: Built on the industry-standard OpenTelemetry framework
Your Choice of Destination: Send data to your own servers
Configurable: Full control over what data is collected and where it goes

All telemetry is disabled by default. It only activates when you explicitly enable it in your configuration.

Basic Configuration

Minimal Setup

import { Wayfinder, NetworkGatewaysProvider } from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
  telemetrySettings: {
    enabled: true,
    serviceName: 'my-application',
    sampleRate: 0.1, // 10% of requests
  },
})

Send to Your Own Infrastructure

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
  telemetrySettings: {
    enabled: true,
    serviceName: 'my-application',
    sampleRate: 0.1,
    exporterUrl: 'https://your-telemetry-server.com/traces',
    apiKey: 'your-api-key',
  },
})

Advanced Configuration

For advanced telemetry configuration, custom instrumentation, and detailed trace management, refer to the OpenTelemetry documentation.

Wayfinder uses these OpenTelemetry packages:

@opentelemetry/api
@opentelemetry/exporter-trace-otlp-http
@opentelemetry/sdk-trace-base

Best Practices

Production Settings

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
  telemetrySettings: {
    enabled: true,
    serviceName: 'my-app-prod',
    sampleRate: 0.01, // 1% sampling for production
    exporterUrl: process.env.TELEMETRY_EXPORTER_URL,
  },
})

Development Settings

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
  telemetrySettings: {
    enabled: true,
    serviceName: 'my-app-dev',
    sampleRate: 0.5, // Higher sampling for debugging
  },
})

Frequently Asked Questions

Q: Is telemetry enabled by default? A: No, telemetry is completely disabled by default and only activates when you explicitly configure it.

Q: Can I use my own telemetry backend? A: Yes, specify your own exporterUrl to send data to any OpenTelemetry-compatible backend.

Q: Does this affect performance? A: Minimal impact when using appropriate sampling rates (1-10% for production).

Q: Can I disable telemetry after enabling it? A: Yes, simply set enabled: false or remove the telemetrySettings configuration entirely.