@ar.io/wayfinder-core 0.0.5-alpha.3 → 0.0.5-alpha.4

package/README.md

@@ -91,9 +91,22 @@ const wayfinder = new Wayfinder({
       },
     },
   },
+  // telemetry configuration
+  telemetrySettings: {
+    enabled: true,
+    // sample 50% of requests
+    sampleRate: 0.5,
+    // honeycomb API key and dataset if you want to collect traces
+    apiKey: '<YOUR_API_KEY>',
+    dataset: 'wayfinder',
+  },
 });
 ```
 
+### Telemetry
+
+Wayfinder can optionally emit OpenTelemetry spans for every request. **By default, telemetry is disabled**. You can control this behavior with the `telemetrySettings` option.
+
 ## ar:// Protocol
 
 Wayfinder supports several ar:// URL formats:

package/dist/telemetry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Span, type Tracer } from '@opentelemetry/api';
+import type { GatewaysProvider, TelemetryConfig, WayfinderOptions } from './types.js';
+import { WayfinderEmitter } from './wayfinder.js';
+export declare const initTelemetry: (config?: TelemetryConfig) => Tracer | undefined;
+export declare const startRequestSpans: ({ originalUrl, emitter, tracer, verificationSettings, routingSettings, gatewaysProvider, }?: {
+    originalUrl?: string;
+    emitter?: WayfinderEmitter;
+    tracer?: Tracer;
+    verificationSettings?: WayfinderOptions["verificationSettings"];
+    routingSettings?: WayfinderOptions["routingSettings"];
+    gatewaysProvider?: GatewaysProvider;
+}) => {
+    parentSpan: Span | undefined;
+    routingSpan: Span | undefined;
+    verificationSpan: Span | undefined;
+};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAGL,IAAI,EACJ,KAAK,MAAM,EAIZ,MAAM,oBAAoB,CAAC;AAc5B,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,eAAO,MAAM,aAAa,GACxB,SAAQ,eAIP,KACA,MAAM,GAAG,SAmCX,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,6FAO/B;IACD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IAChE,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IACtD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAChC;;;;CA+DL,CAAC"}

package/dist/telemetry.js

@@ -0,0 +1,115 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { DiagConsoleLogger, DiagLogLevel, context, diag, trace, } from '@opentelemetry/api';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchSpanProcessor, TraceIdRatioBasedSampler, } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from '@opentelemetry/semantic-conventions';
+export const initTelemetry = (config = {
+    enabled: false,
+    sampleRate: 0,
+    serviceName: 'wayfinder-core',
+}) => {
+    if (config.enabled === false)
+        return undefined;
+    diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR);
+    const exporter = new OTLPTraceExporter({
+        url: config.exporterUrl ?? 'https://api.honeycomb.io',
+        headers: {
+            'x-honeycomb-team': config.apiKey ?? '',
+            'x-honeycomb-dataset': 'wayfinder-dev',
+        },
+    });
+    const isBrowser = typeof window !== 'undefined';
+    const spanProcessor = new BatchSpanProcessor(exporter);
+    const sampler = new TraceIdRatioBasedSampler(config.sampleRate ?? 1);
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: 'wayfinder-core',
+        [ATTR_SERVICE_VERSION]: 'v0.0.5-alpha.5', // hard coded for now as importing JSON breaks wayfinder-react
+    });
+    const provider = isBrowser
+        ? new WebTracerProvider({
+            sampler,
+            resource,
+            spanProcessors: [spanProcessor],
+        })
+        : new NodeTracerProvider({
+            sampler,
+            resource,
+            spanProcessors: [spanProcessor],
+        });
+    provider.register();
+    return trace.getTracer('wayfinder-core');
+};
+export const startRequestSpans = ({ originalUrl, emitter, tracer, verificationSettings, routingSettings, gatewaysProvider, } = {}) => {
+    const activeContext = context.active();
+    const parentSpan = tracer?.startSpan('wayfinder.request', {
+        attributes: {
+            originalUrl: originalUrl ?? 'undefined',
+            'verification.enabled': verificationSettings?.enabled ?? false,
+            'verification.strategy': verificationSettings?.strategy?.constructor.name ?? 'undefined',
+            'verification.strict': verificationSettings?.strict ?? false,
+            'verification.trustedGateways': verificationSettings?.strategy?.trustedGateways
+                ?.map((gateway) => gateway.toString())
+                .join(','),
+            'routing.strategy': routingSettings?.strategy?.constructor.name ?? 'undefined',
+            gatewaysProvider: gatewaysProvider?.constructor.name,
+        },
+    }, activeContext);
+    const parentContext = parentSpan
+        ? trace.setSpan(context.active(), parentSpan)
+        : context.active();
+    let routingSpan;
+    let verificationSpan;
+    // add listeners on the emitter to the span
+    emitter?.on('routing-started', () => {
+        if (parentSpan && !routingSpan) {
+            context.with(parentContext, () => {
+                routingSpan = tracer?.startSpan('wayfinder.routing');
+            });
+        }
+    });
+    emitter?.on('routing-skipped', () => {
+        parentSpan?.setAttribute('routing.skipped', true);
+        routingSpan?.end();
+        parentSpan?.end();
+    });
+    emitter?.on('routing-succeeded', () => {
+        parentSpan?.setAttribute('routing.succeeded', true);
+        routingSpan?.end();
+    });
+    emitter?.on('verification-progress', () => {
+        if (parentSpan && !verificationSpan) {
+            context.with(parentContext, () => {
+                verificationSpan = tracer?.startSpan('wayfinder.verification');
+            });
+        }
+    });
+    emitter?.on('verification-succeeded', () => {
+        parentSpan?.setAttribute('verification.succeeded', true);
+        verificationSpan?.end();
+        parentSpan?.end();
+    });
+    emitter?.on('verification-failed', () => {
+        parentSpan?.setAttribute('verification.failed', true);
+        verificationSpan?.end();
+        parentSpan?.end();
+    });
+    return { parentSpan, routingSpan, verificationSpan };
+};

package/dist/types.d.ts

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { WayfinderEmitter } from './wayfinder.js';
 /**
  * This is an extension of the fetch function that allows for overriding the verification and routing settings for a single request.
  */
@@ -70,6 +71,7 @@ export interface WayfinderVerificationEventArgs {
 export interface WayfinderEventArgs {
     verification?: WayfinderVerificationEventArgs;
     routing?: WayfinderRoutingEventArgs;
+    parentEmitter?: WayfinderEmitter;
 }
 /**
  * Configuration options for the Wayfinder
@@ -122,6 +124,22 @@ export interface WayfinderOptions {
          */
         strategy?: RoutingStrategy;
     };
+    /**
+     * Telemetry configuration used to initialize OpenTelemetry tracing
+     */
+    telemetrySettings?: TelemetryConfig;
+}
+export interface TelemetryConfig {
+    /** Enable or disable telemetry collection */
+    enabled: boolean;
+    /** Sampling ratio between 0 and 1 */
+    sampleRate: number;
+    /** Honeycomb API key */
+    apiKey?: string;
+    /** Optional custom OTLP exporter URL */
+    exporterUrl?: string;
+    /** Service name used for traces */
+    serviceName: string;
 }
 export type DataStream = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
 export interface GatewaysProvider {
@@ -138,6 +156,7 @@ export interface RoutingStrategy {
     }): Promise<URL>;
 }
 export interface VerificationStrategy {
+    trustedGateways: URL[];
     verifyData(params: {
         data: DataStream;
         txId: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/verification/data-root-verifier.d.ts

@@ -3,7 +3,7 @@ export declare const convertDataStreamToDataRoot: ({ stream, }: {
     stream: DataStream;
 }) => Promise<string>;
 export declare class DataRootVerificationStrategy implements VerificationStrategy {
-    private readonly trustedGateways;
+    readonly trustedGateways: URL[];
     private readonly maxConcurrency;
     private readonly logger;
     private readonly classifier;

package/dist/verification/data-root-verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-root-verifier.d.ts","sourceRoot":"","sources":["../../src/verification/data-root-verifier.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,cAAc,EACd,UAAU,EACV,MAAM,EACN,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAOrB,eAAO,MAAM,2BAA2B,GAAU,aAE/C;IACD,MAAM,EAAE,UAAU,CAAC;CACpB,KAAG,OAAO,CAAC,MAAM,CAwDjB,CAAC;AAGF,qBAAa,4BAA6B,YAAW,oBAAoB;IACvE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;gBAChC,EACV,eAAe,EACf,cAAkB,EAClB,MAAsB,EACtB,UAA0C,GAC3C,EAAE;QACD,eAAe,EAAE,GAAG,EAAE,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,cAAc,CAAC;KAC7B;IAOD;;;;OAIG;IACG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAuCxD,UAAU,CAAC,EACf,IAAI,EACJ,IAAI,GACL,EAAE;QACD,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,IAAI,CAAC;CA0BlB"}
+{"version":3,"file":"data-root-verifier.d.ts","sourceRoot":"","sources":["../../src/verification/data-root-verifier.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,cAAc,EACd,UAAU,EACV,MAAM,EACN,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAOrB,eAAO,MAAM,2BAA2B,GAAU,aAE/C;IACD,MAAM,EAAE,UAAU,CAAC;CACpB,KAAG,OAAO,CAAC,MAAM,CAwDjB,CAAC;AAGF,qBAAa,4BAA6B,YAAW,oBAAoB;IACvE,SAAgB,eAAe,EAAE,GAAG,EAAE,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;gBAChC,EACV,eAAe,EACf,cAAkB,EAClB,MAAsB,EACtB,UAA0C,GAC3C,EAAE;QACD,eAAe,EAAE,GAAG,EAAE,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,cAAc,CAAC;KAC7B;IAOD;;;;OAIG;IACG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAuCxD,UAAU,CAAC,EACf,IAAI,EACJ,IAAI,GACL,EAAE;QACD,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,IAAI,CAAC;CA0BlB"}

package/dist/verification/hash-verifier.d.ts

@@ -1,6 +1,6 @@
 import type { DataStream, Logger, VerificationStrategy } from '../types.js';
 export declare class HashVerificationStrategy implements VerificationStrategy {
-    private readonly trustedGateways;
+    readonly trustedGateways: URL[];
     private readonly maxConcurrency;
     private readonly logger;
     constructor({ trustedGateways, maxConcurrency, logger, }: {

package/dist/verification/hash-verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash-verifier.d.ts","sourceRoot":"","sources":["../../src/verification/hash-verifier.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAK5E,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBACpB,EACV,eAAe,EACf,cAAkB,EAClB,MAAsB,GACvB,EAAE;QACD,eAAe,EAAE,GAAG,EAAE,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAMD;;;;OAIG;IACG,SAAS,CAAC,EACd,IAAI,GACL,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,QAAQ,CAAA;KAAE,CAAC;IAqE5C,UAAU,CAAC,EACf,IAAI,EACJ,IAAI,GACL,EAAE;QACD,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlB"}
+{"version":3,"file":"hash-verifier.d.ts","sourceRoot":"","sources":["../../src/verification/hash-verifier.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAK5E,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,SAAgB,eAAe,EAAE,GAAG,EAAE,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBACpB,EACV,eAAe,EACf,cAAkB,EAClB,MAAsB,GACvB,EAAE;QACD,eAAe,EAAE,GAAG,EAAE,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAMD;;;;OAIG;IACG,SAAS,CAAC,EACd,IAAI,GACL,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,QAAQ,CAAA;KAAE,CAAC;IAqE5C,UAAU,CAAC,EACf,IAAI,EACJ,IAAI,GACL,EAAE;QACD,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlB"}

package/dist/verification/signature-verifier.d.ts

@@ -4,7 +4,7 @@ import type { DataClassifier, DataStream, Logger, VerificationStrategy } from '.
  * using trusted gateways to provide the metadata needed for verification.
  */
 export declare class Ans104SignatureVerificationStrategy implements VerificationStrategy {
-    private readonly trustedGateways;
+    readonly trustedGateways: URL[];
     private readonly maxConcurrency;
     private readonly logger;
     constructor({ trustedGateways, maxConcurrency, logger, }: {
@@ -58,7 +58,7 @@ export declare class Ans104SignatureVerificationStrategy implements Verification
  * from a trusted gateway's /tx/<tx-id>/signature endpoint.
  */
 export declare class TransactionSignatureVerificationStrategy implements VerificationStrategy {
-    private readonly trustedGateways;
+    readonly trustedGateways: URL[];
     private readonly logger;
     constructor({ trustedGateways, logger, }: {
         trustedGateways: URL[];
@@ -102,6 +102,7 @@ export declare class SignatureVerificationStrategy {
     private readonly ans104;
     private readonly transaction;
     private readonly classifier;
+    readonly trustedGateways: URL[];
     constructor({ trustedGateways, maxConcurrency, logger, classifier, }: {
         trustedGateways: URL[];
         maxConcurrency?: number;

package/dist/verification/signature-verifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signature-verifier.d.ts","sourceRoot":"","sources":["../../src/verification/signature-verifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"signature-verifier.d.ts","sourceRoot":"","sources":["../../src/verification/signature-verifier.ts"],"names":[],"mappings":"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"}

package/dist/verification/signature-verifier.js

@@ -334,7 +334,9 @@ export class SignatureVerificationStrategy {
     ans104;
     transaction;
     classifier;
+    trustedGateways;
     constructor({ trustedGateways, maxConcurrency = 1, logger = defaultLogger, classifier = new GqlClassifier({ logger }), }) {
+        this.trustedGateways = trustedGateways;
         this.ans104 = new Ans104SignatureVerificationStrategy({
             trustedGateways,
             maxConcurrency,

package/dist/wayfinder.d.ts

@@ -15,7 +15,8 @@
  * limitations under the License.
  */
 import { EventEmitter } from 'eventemitter3';
-import type { GatewaysProvider, Logger, VerificationStrategy, WayfinderEvent, WayfinderEventArgs, WayfinderFetch, WayfinderOptions } from './types.js';
+import { type Tracer } from '@opentelemetry/api';
+import type { GatewaysProvider, Logger, TelemetryConfig, VerificationStrategy, WayfinderEvent, WayfinderEventArgs, WayfinderFetch, WayfinderOptions } from './types.js';
 export declare const arnsRegex: RegExp;
 export declare const txIdRegex: RegExp;
 /**
@@ -30,7 +31,7 @@ export declare const resolveWayfinderUrl: ({ originalUrl, selectedGateway, logge
     logger?: Logger;
 }) => URL;
 export declare class WayfinderEmitter extends EventEmitter<WayfinderEvent> {
-    constructor({ verification, routing }?: WayfinderEventArgs);
+    constructor({ verification, routing, parentEmitter, }?: WayfinderEventArgs);
 }
 export declare function tapAndVerifyReadableStream({ originalStream, contentLength, verifyData, txId, emitter, strict, }: {
     originalStream: ReadableStream;
@@ -51,12 +52,13 @@ export declare function tapAndVerifyReadableStream({ originalStream, contentLeng
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
  */
-export declare const wayfinderFetch: ({ logger, gatewaysProvider, verificationSettings, routingSettings, emitter, }: {
+export declare const wayfinderFetch: ({ logger, gatewaysProvider, verificationSettings, routingSettings, emitter, tracer, }: {
     logger?: Logger;
     gatewaysProvider: GatewaysProvider;
     verificationSettings: NonNullable<WayfinderOptions["verificationSettings"]>;
     routingSettings: NonNullable<WayfinderOptions["routingSettings"]>;
     emitter?: WayfinderEmitter;
+    tracer?: Tracer;
 }) => (input: URL | RequestInfo, init?: RequestInit & {
     verificationSettings?: NonNullable<WayfinderOptions["verificationSettings"]>;
     routingSettings?: NonNullable<WayfinderOptions["routingSettings"]>;
@@ -87,6 +89,14 @@ export declare class Wayfinder {
      * The verification settings to use when verifying data.
      */
     readonly verificationSettings: WayfinderOptions['verificationSettings'];
+    /**
+     * Telemetry configuration used for OpenTelemetry tracing
+     */
+    readonly telemetrySettings: TelemetryConfig;
+    /**
+     * OpenTelemetry tracer instance
+     */
+    protected tracer?: Tracer;
     /**
      * A helper function that resolves the redirect url for ar:// requests to a target gateway.
      *
@@ -204,6 +214,6 @@ export declare class Wayfinder {
      * @param options - Wayfinder configuration options
      */
     constructor({ logger, gatewaysProvider, // forcing it to be required to avoid making ar-io-sdk a dependency
-    verificationSettings, routingSettings, }: WayfinderOptions);
+    verificationSettings, routingSettings, telemetrySettings, }: WayfinderOptions);
 }
 //# sourceMappingURL=wayfinder.d.ts.map

package/dist/wayfinder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAK7C,OAAO,KAAK,EACV,gBAAgB,EAChB,MAAM,EACN,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAKpB,eAAO,MAAM,SAAS,QAAuB,CAAC;AAC9C,eAAO,MAAM,SAAS,QAAwB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,2CAIjC;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,GAAG,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,KAAG,GAgDH,CAAC;AAEF,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,cAAc,CAAC;gBACpD,EAAE,YAAY,EAAE,OAAO,EAAE,GAAE,kBAAuB;CAyB/D;AAED,wBAAgB,0BAA0B,CAAC,EACzC,cAAc,EACd,aAAa,EACb,UAAU,EACV,IAAI,EACJ,OAAO,EACP,MAAc,GACf,EAAE;IACD,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,cAAc,CAiFjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,+EAM5B;IACD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,oBAAoB,EAAE,WAAW,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC5E,eAAe,EAAE,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B,MAEG,OAAO,GAAG,GAAG,WAAW,EACxB,OAAO,WAAW,GAAG;IACnB,oBAAoB,CAAC,EAAE,WAAW,CAChC,gBAAgB,CAAC,sBAAsB,CAAC,CACzC,CAAC;IACF,eAAe,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;CACpE,KACA,OAAO,CAAC,QAAQ,CAoLpB,CAAC;AAEF;;GAEG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;OAUG;IACH,SAAgB,gBAAgB,EAAE,gBAAgB,CAAC;IAEnD;;;;OAIG;IACH,SAAgB,eAAe,EAAE,QAAQ,CACvC,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CACjD,CAAC;IACF;;OAEG;IACH,SAAgB,oBAAoB,EAAE,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IAE/E;;;;;;;;;;;;;;OAcG;IACH,SAAgB,UAAU,EAAE,CAAC,MAAM,EAAE;QACnC,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACI,OAAO,EAAE,cAAc,CAAC;IAE/B;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACH,SAAgB,OAAO,EAAE,gBAAgB,CAAC;IAE1C;;;OAGG;gBACS,EACV,MAAsB,EACtB,gBAAgB,EAAE,mEAAmE;IACrF,oBAAoB,EACpB,eAAe,GAChB,EAAE,gBAAgB;CA2DpB"}
+{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}

package/dist/wayfinder.js

@@ -16,7 +16,9 @@
  */
 import { EventEmitter } from 'eventemitter3';
 import { defaultLogger } from './logger.js';
+import { context, trace } from '@opentelemetry/api';
 import { FastestPingRoutingStrategy } from './routing/ping.js';
+import { initTelemetry, startRequestSpans } from './telemetry.js';
 import { sandboxFromId } from './utils/base64.js';
 import { HashVerificationStrategy } from './verification/hash-verifier.js';
 // known regexes for wayfinder urls
@@ -68,7 +70,7 @@ export const resolveWayfinderUrl = ({ originalUrl, selectedGateway, logger, }) =
     return new URL(originalUrl);
 };
 export class WayfinderEmitter extends EventEmitter {
-    constructor({ verification, routing } = {}) {
+    constructor({ verification, routing, parentEmitter, } = {}) {
         super();
         if (verification) {
             if (verification.onVerificationSucceeded) {
@@ -92,6 +94,29 @@ export class WayfinderEmitter extends EventEmitter {
                 this.on('routing-succeeded', routing.onRoutingSucceeded);
             }
         }
+        if (parentEmitter) {
+            this.on('routing-started', (event) => {
+                parentEmitter.emit('routing-started', event);
+            });
+            this.on('routing-skipped', (event) => {
+                parentEmitter.emit('routing-skipped', event);
+            });
+            this.on('routing-succeeded', (event) => {
+                parentEmitter.emit('routing-succeeded', event);
+            });
+            this.on('verification-succeeded', (event) => {
+                parentEmitter.emit('verification-succeeded', event);
+            });
+            this.on('verification-failed', (event) => {
+                parentEmitter.emit('verification-failed', event);
+            });
+            this.on('verification-progress', (event) => {
+                parentEmitter.emit('verification-progress', event);
+            });
+            this.on('verification-skipped', (event) => {
+                parentEmitter.emit('verification-skipped', event);
+            });
+        }
     }
 }
 export function tapAndVerifyReadableStream({ originalStream, contentLength, verifyData, txId, emitter, strict = false, }) {
@@ -182,26 +207,25 @@ export function tapAndVerifyReadableStream({ originalStream, contentLength, veri
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped fetch function that supports ar:// protocol and always returns Response
  */
-export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verificationSettings, routingSettings, emitter, }) => {
+export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verificationSettings, routingSettings, emitter, tracer, }) => {
     return async (input, init) => {
         const { 
         // allows for overriding the verification and routing settings for a single request
         verificationSettings: requestVerificationSettings, routingSettings: requestRoutingSettings, ...restInit } = init ?? {};
+        const url = input instanceof URL ? input.toString() : input.toString();
         const requestEmitter = new WayfinderEmitter({
             verification: requestVerificationSettings?.events,
             routing: requestRoutingSettings?.events,
+            parentEmitter: emitter,
+        });
+        const { parentSpan } = startRequestSpans({
+            originalUrl: url,
+            verificationSettings: requestVerificationSettings ?? verificationSettings,
+            routingSettings: requestRoutingSettings ?? routingSettings,
+            gatewaysProvider,
+            emitter: requestEmitter,
+            tracer,
         });
-        if (emitter) {
-            requestEmitter.on('routing-started', (event) => {
-                emitter.emit('routing-started', event);
-            });
-            requestEmitter.on('routing-skipped', (event) => emitter.emit('routing-skipped', event));
-            requestEmitter.on('routing-succeeded', (event) => emitter.emit('routing-succeeded', event));
-            requestEmitter.on('verification-succeeded', (event) => emitter.emit('verification-succeeded', event));
-            requestEmitter.on('verification-failed', (event) => emitter.emit('verification-failed', event));
-            requestEmitter.on('verification-progress', (event) => emitter.emit('verification-progress', event));
-        }
-        const url = input instanceof URL ? input.toString() : input.toString();
         if (!url.toString().startsWith('ar://')) {
             logger?.debug('URL is not a wayfinder url, skipping routing', {
                 input,
@@ -246,6 +270,9 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
                     originalUrl: url,
                     redirectUrl: redirectUrl.toString(),
                 });
+                const requestSpan = parentSpan
+                    ? tracer?.startSpan('wayfinder.fetch', undefined, trace.setSpan(context.active(), parentSpan))
+                    : undefined;
                 // make the request to the target gateway using the redirect url
                 const response = await fetch(redirectUrl.toString(), {
                     // enforce CORS given we're likely going to a different origin, but always allow the client to override
@@ -253,58 +280,87 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
                     mode: 'cors',
                     ...restInit,
                 });
+                // add response attributes to the span
+                requestSpan?.setAttribute('response.status', response.status);
+                requestSpan?.setAttribute('response.statusText', response.statusText);
+                response.headers.forEach((value, key) => {
+                    requestSpan?.setAttribute(`response.headers.${key}`, value);
+                });
                 logger?.debug(`Successfully routed request to gateway`, {
                     redirectUrl: redirectUrl.toString(),
                     originalUrl: url,
                 });
                 // only verify data if the redirect url is different from the original url
-                if (redirectUrl.toString() !== url) {
-                    if (verificationSettings.enabled &&
-                        verificationSettings.strategy?.verifyData) {
-                        const headers = response.headers;
-                        // transaction id is either in the response headers or the path of the request as the first parameter
-                        const txId = headers.get('x-arns-resolved-id') ??
-                            redirectUrl.pathname.split('/')[1];
-                        const contentLength = +(headers.get('content-length') ?? 0);
-                        if (!txIdRegex.test(txId)) {
-                            // no transaction id found, skip verification
-                            logger?.debug('No transaction id found, skipping verification', {
-                                redirectUrl: redirectUrl.toString(),
-                                originalUrl: url,
-                            });
-                            requestEmitter.emit('verification-skipped', {
-                                originalUrl: url,
-                            });
-                            return response;
-                        }
-                        // Check if the response has a body
-                        if (response.body) {
-                            const newClientStream = tapAndVerifyReadableStream({
-                                originalStream: response.body,
-                                contentLength,
-                                verifyData: verificationSettings.strategy?.verifyData.bind(verificationSettings.strategy),
-                                txId,
-                                emitter: requestEmitter,
-                                strict: verificationSettings.strict,
-                            });
-                            return new Response(newClientStream, {
-                                status: response.status,
-                                statusText: response.statusText,
-                                headers: response.headers,
-                            });
-                        }
-                        else {
-                            // No response body to verify, skip verification
-                            logger?.debug('No response body to verify', {
-                                redirectUrl: redirectUrl.toString(),
-                                originalUrl: url,
-                                txId,
-                            });
-                            return response;
-                        }
-                    }
+                if (redirectUrl.toString() === url) {
+                    logger?.debug('Redirect URL is the same as the original URL, skipping verification', {
+                        redirectUrl: redirectUrl.toString(),
+                        originalUrl: url,
+                    });
+                    requestEmitter.emit('verification-skipped', {
+                        originalUrl: url,
+                    });
+                    requestSpan?.end();
+                    return response;
+                }
+                // if verification is disabled, return the response
+                if (!(verificationSettings.enabled &&
+                    verificationSettings.strategy?.verifyData)) {
+                    logger?.debug('Verification is disabled or no verification strategy is provided, skipping verification', {
+                        redirectUrl: redirectUrl.toString(),
+                        originalUrl: url,
+                    });
+                    requestEmitter.emit('verification-skipped', {
+                        originalUrl: url,
+                    });
+                    requestSpan?.end();
+                    return response;
+                }
+                // Verify the response
+                // TODO: add more verification and response attributes to the span
+                const headers = response.headers;
+                // transaction id is either in the response headers or the path of the request as the first parameter
+                const txId = headers.get('x-arns-resolved-id') ??
+                    redirectUrl.pathname.split('/')[1];
+                const contentLength = +(headers.get('content-length') ?? 0);
+                requestSpan?.setAttribute('txId', txId);
+                requestSpan?.setAttribute('contentLength', contentLength);
+                requestSpan?.end();
+                if (!txIdRegex.test(txId)) {
+                    // no transaction id found, skip verification
+                    logger?.debug('No transaction id found, skipping verification', {
+                        redirectUrl: redirectUrl.toString(),
+                        originalUrl: url,
+                    });
+                    requestEmitter.emit('verification-skipped', {
+                        originalUrl: url,
+                    });
+                    return response;
+                }
+                // Check if the response has a body
+                if (response.body) {
+                    const newClientStream = tapAndVerifyReadableStream({
+                        originalStream: response.body,
+                        contentLength,
+                        verifyData: verificationSettings.strategy?.verifyData.bind(verificationSettings.strategy),
+                        txId,
+                        emitter: requestEmitter,
+                        strict: verificationSettings.strict,
+                    });
+                    return new Response(newClientStream, {
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers: response.headers,
+                    });
+                }
+                else {
+                    // No response body to verify, skip verification
+                    logger?.debug('No response body to verify', {
+                        redirectUrl: redirectUrl.toString(),
+                        originalUrl: url,
+                        txId,
+                    });
+                    return response;
                 }
-                return response;
             }
             catch (error) {
                 logger?.debug('Failed to route request', {
@@ -353,6 +409,14 @@ export class Wayfinder {
      * The verification settings to use when verifying data.
      */
     verificationSettings;
+    /**
+     * Telemetry configuration used for OpenTelemetry tracing
+     */
+    telemetrySettings;
+    /**
+     * OpenTelemetry tracer instance
+     */
+    tracer;
     /**
      * A helper function that resolves the redirect url for ar:// requests to a target gateway.
      *
@@ -467,7 +531,7 @@ export class Wayfinder {
      * @param options - Wayfinder configuration options
      */
     constructor({ logger = defaultLogger, gatewaysProvider, // forcing it to be required to avoid making ar-io-sdk a dependency
-    verificationSettings, routingSettings, }) {
+    verificationSettings, routingSettings, telemetrySettings, }) {
         this.logger = logger;
         this.gatewaysProvider = gatewaysProvider;
         // default verification settings
@@ -495,12 +559,21 @@ export class Wayfinder {
             verification: this.verificationSettings?.events,
             routing: this.routingSettings?.events,
         });
+        this.telemetrySettings = {
+            enabled: telemetrySettings?.enabled ?? false,
+            sampleRate: telemetrySettings?.sampleRate ?? 0.1, // 10% sample rate by default
+            apiKey: telemetrySettings?.apiKey ?? 'c8gU8dHlu6V7e5k2Gn9LaG', // intentionally left here - if it gets abused we'll disable it
+            exporterUrl: telemetrySettings?.exporterUrl ?? 'https://api.honeycomb.io/v1/traces', // TODO: replace with proxy url and remove api key
+            serviceName: telemetrySettings?.serviceName ?? 'wayfinder-core',
+        };
+        this.tracer = initTelemetry(this.telemetrySettings);
         this.request = wayfinderFetch({
             logger: this.logger,
             emitter: this.emitter,
             gatewaysProvider: this.gatewaysProvider,
             routingSettings: this.routingSettings,
             verificationSettings: this.verificationSettings,
+            tracer: this.tracer,
         });
         this.resolveUrl = async ({ originalUrl, logger = this.logger }) => {
             const selectedGateway = await this.routingSettings.strategy.selectGateway({
@@ -512,6 +585,10 @@ export class Wayfinder {
                 logger,
             });
         };
-        this.logger.debug(`Wayfinder initialized with ${this.routingSettings.strategy?.constructor.name} routing strategy`);
+        this.logger.debug('Wayfinder initialized', {
+            verificationSettings: this.verificationSettings,
+            routingSettings: this.routingSettings,
+            telemetrySettings: this.telemetrySettings,
+        });
     }
 }

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "0.0.5-alpha.3",
+  "version": "0.0.5-alpha.4",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "license": "Apache-2.0",
-  "keywords": ["ar-io", "arweave", "wayfinder", "ar://"],
+  "keywords": [
+    "ar-io",
+    "arweave",
+    "wayfinder",
+    "ar://"
+  ],
   "author": {
     "name": "Permanent Data Solutions Inc",
     "email": "info@ar.io",
@@ -16,7 +21,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "package.json", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,6 +49,11 @@
   },
   "dependencies": {
     "@dha-team/arbundles": "^1.0.3",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.202.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "@opentelemetry/sdk-trace-web": "^2.0.1",
     "arweave": "^1.14.0",
     "eventemitter3": "^5.0.1",
     "plimit-lit": "^3.0.1",