SpitfireYük Testi ve Gözlemlenebilirlikv1.1.0 · Yenilikler

Sürüm: 1.1.0Bu dokümantasyon Spitfire 1.1.0 içindir.

React.js uygulamasını (tarayıcı) OTel ile bağlamak

Tarayıcıda React: sayfa yüklenmesi, fetch/XHR ve tıklamalar trace olarak; backend'e traceparent ile bağlanır. Değerler: Servisleri OTel ile bağlamak: genel bakış.

Sürüm tablosu

Derleme Paket Sürüm
Vite 5+, Next.js 15.3+, Create React App 5 @opentelemetry/sdk-trace, core, resources, context-zone 3.0.0
@opentelemetry/exporter-trace-otlp-http, instrumentation, instrumentation-fetch, instrumentation-xml-http-request 0.300.0
@opentelemetry/instrumentation-document-load 0.69.0
@opentelemetry/instrumentation-user-interaction + zone.js 0.68.0 + 0.16.3
@opentelemetry/api 1.10.0
Derleme makinesi Node.js 22.15 ve sonrası
Tarayıcı ES2022 (Chrome 94, Firefox 93, Safari 16.4 ve sonrası) –

Sürümünüzü bulun: node --version

Yalnızca trace. OTel tarayıcı instrumentation'ını deneysel sayar.

Doğrulandı: 2026-11-04. Kaynak: OTel JS browser, OTel JS 3.x migration guide, npm @opentelemetry/sdk-trace, npm @opentelemetry/instrumentation-document-load, npm @opentelemetry/instrumentation-user-interaction, Next.js instrumentation-client.

Gerekenler

  • Spitfire adresi https://<spitfire>
  • Servis adı <service-name>, sürüm <service-version>, ortam <environment>
  • Uygulama klasörü (burada /srv/web, package.json dosyasının olduğu yer) ve adresi (burada https://<app-origin>)
  • API adresiniz, düzenli ifade olarak (burada ^https://api\.example\.com/)

Vite

  1. Anahtarı oluşturun: Gözlemlenebilirlik → Tarayıcı ve uygulama anahtarı, İzin verilen kökenler https://<app-origin>; sfrum_… anahtarını kopyalayın (Gözlemlenebilirlik).

  2. Paketleri ekleyin:

bash
cd /srv/web && npm i @opentelemetry/api@1.10.0 @opentelemetry/sdk-trace@3.0.0 @opentelemetry/core@3.0.0 @opentelemetry/resources@3.0.0 @opentelemetry/context-zone@3.0.0 @opentelemetry/exporter-trace-otlp-http@0.300.0 @opentelemetry/instrumentation@0.300.0 @opentelemetry/instrumentation-fetch@0.300.0 @opentelemetry/instrumentation-xml-http-request@0.300.0 @opentelemetry/instrumentation-document-load@0.69.0 @opentelemetry/instrumentation-user-interaction@0.68.0 zone.js@0.16.3
  1. /srv/web/.env.production dosyasını oluşturun, yapıştırın:
bash
VITE_IS_OTEL_ENABLED=true
VITE_OTEL_SERVICE_NAME=<service-name>
VITE_OTEL_SERVICE_VERSION=<service-version>
VITE_OTEL_ENVIRONMENT=<environment>
VITE_OTEL_TRACES_ENDPOINT=https://<spitfire>/otlp/v1/traces
VITE_OTEL_KEY=sfrum_…
VITE_OTEL_TRACES_SAMPLER_ARG=0.1
VITE_OTEL_PROPAGATE_URLS=^https://api\.example\.com/
  1. /srv/web/src/otel.ts dosyasını oluşturun, yapıştırın:
ts
// VITE_IS_OTEL_ENABLED=true: OTel on; any other value: off.
import { context, propagation, trace } from '@opentelemetry/api';
import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from '@opentelemetry/core';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler, TracerProvider } from '@opentelemetry/sdk-trace';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
import { UserInteractionInstrumentation } from '@opentelemetry/instrumentation-user-interaction';
import { XMLHttpRequestInstrumentation } from '@opentelemetry/instrumentation-xml-http-request';

const env = import.meta.env;
if (env.VITE_IS_OTEL_ENABLED === 'true') {
  const provider = new TracerProvider({
    resource: resourceFromAttributes({
      'service.name': env.VITE_OTEL_SERVICE_NAME,
      'service.version': env.VITE_OTEL_SERVICE_VERSION,
      'deployment.environment': env.VITE_OTEL_ENVIRONMENT,
    }),
    sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(Number(env.VITE_OTEL_TRACES_SAMPLER_ARG)) }),
    spanProcessors: [new BatchSpanProcessor({
      exporter: new OTLPTraceExporter({ url: env.VITE_OTEL_TRACES_ENDPOINT, headers: { Authorization: `Bearer ${env.VITE_OTEL_KEY}` } }),
    })],
  });
  trace.setGlobalTracerProvider(provider);
  context.setGlobalContextManager(new ZoneContextManager().enable());
  propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }));
  const propagateTraceHeaderCorsUrls = [new RegExp(env.VITE_OTEL_PROPAGATE_URLS)];
  registerInstrumentations({
    instrumentations: [
      new DocumentLoadInstrumentation(),
      new UserInteractionInstrumentation({ eventNames: ['click', 'submit'] }),
      new FetchInstrumentation({ propagateTraceHeaderCorsUrls }),
      new XMLHttpRequestInstrumentation({ propagateTraceHeaderCorsUrls }),
    ],
  });
}
  1. /srv/web/src/main.tsx dosyasının ilk satırı yapın:
ts
import './otel';
  1. Derleyin:
bash
cd /srv/web && npm run build

Next.js

  1. Vite adım 1 ve 2; sonra Vite adım 3'teki /srv/web/.env.production dosyasında VITE_ yerine NEXT_PUBLIC_ yazın:
bash
sed -i.bak 's/^VITE_/NEXT_PUBLIC_/' /srv/web/.env.production
  1. Vite adım 4'teki kodu /srv/web/instrumentation-client.ts olarak kaydedin, öneki değiştirin:
bash
perl -0pi -e 's/const env = import\.meta\.env;\n//; s/\benv\.VITE_/process.env.VITE_/g; s/VITE_/NEXT_PUBLIC_/g' /srv/web/instrumentation-client.ts
  1. Derleyin:
bash
cd /srv/web && npm run build

Create React App

  1. Vite adım 1, 2 ve 4; sonra .env.production ve src/otel.ts önekini değiştirin:
bash
sed -i.bak 's/^VITE_/REACT_APP_/' /srv/web/.env.production && perl -0pi -e 's/const env = import\.meta\.env;\n//; s/\benv\.VITE_/process.env.VITE_/g; s/VITE_/REACT_APP_/g' /srv/web/src/otel.ts
  1. import './otel'; satırını /srv/web/src/index.tsx dosyasının ilk satırı yapın, sonra derleyin:
bash
cd /srv/web && npm run build

Backend'iniz

  1. Backend'in CORS ayarı https://<app-origin> için trace başlıklarına izin versin:
text
Access-Control-Allow-Headers: traceparent, tracestate, baggage

Doğrulama

  1. Tarayıcı gönderebilir:
bash
curl -s -o /dev/null -w '%{http_code}' -X OPTIONS https://<spitfire>/otlp/v1/traces -H 'Origin: https://<app-origin>' -H 'Access-Control-Request-Method: POST' | grep -q '^204
  

 && echo OK
  1. Spitfire anahtarı kabul ediyor:
bash
curl -s -o /dev/null -w '%{http_code}' -X POST https://<spitfire>/otlp/v1/traces -H 'Origin: https://<app-origin>' -H 'Authorization: Bearer sfrum_…' -H 'Content-Type: application/json' -d '{}' | grep -q '^200
  

 && echo OK
  1. Derleme endpoint'i içeriyor:
bash
grep -rq '/otlp/v1/traces' /srv/web/dist /srv/web/build /srv/web/.next/static 2>/dev/null && echo OK

Kapatma ve kaldırma

  1. Kapatma: .env.production içinde VITE_IS_OTEL_ENABLED (NEXT_PUBLIC_…, REACT_APP_…) için false yazın, yeniden derleyin.
  2. Kaldırma:
bash
cd /srv/web && npm uninstall @opentelemetry/api @opentelemetry/sdk-trace @opentelemetry/core @opentelemetry/resources @opentelemetry/context-zone @opentelemetry/exporter-trace-otlp-http @opentelemetry/instrumentation @opentelemetry/instrumentation-fetch @opentelemetry/instrumentation-xml-http-request @opentelemetry/instrumentation-document-load @opentelemetry/instrumentation-user-interaction zone.js && rm -f src/otel.ts instrumentation-client.ts

Sık karşılaşılan sorunlar

Belirti Çözüm
Doğrulama adım 1 bir şey yazmıyor https://<app-origin> adresini anahtarın İzin verilen kökenler listesine ekleyin; 30 sn bekleyin
401 Anahtar sfrum_… olmalı, açık olmalı, Bearer sonrasında yazılmalı
429 Anahtarın Dakikada gönderim değerini artırın ya da VITE_OTEL_TRACES_SAMPLER_ARG değerini düşürün
API çağrılarınız CORS hatası veriyor Backend'iniz adım 1
Tarayıcı ve backend span'leri tek trace değil VITE_OTEL_PROPAGATE_URLS API adresinize uymalı
npm i EBADENGINE hatası veriyor Derleme makinesinde Node.js 22.15 ve sonrası

İlgili sayfalar