Telemetri

telemetry plugin'i tüm sağlayıcı işlemlerini kendi OpenTelemetry tracer ve meter kaydedicilerinize bildirir: çağrı başına, sağlayıcıyı, işlemi, sonucu, HTTP durumunu, deneme sayısını ve süreyi taşıyan bir span, ayrıca bir çağsayacı ve gecikme histogramı. Kütüphanenin içinde gelir ve bağımlılık gerektirmez: yapısal olarak uyumlu nesnelerle konuşur, yani gerçek bir @opentelemetry/api tracer'ı iki paket birbirinden haberdan olmadan çalışır (hata kodları).

KurulumCopy Anchor Link

import { betterPayment, iyzico } from 'better-payment';
import { trace, metrics } from '@opentelemetry/api';
import { telemetry } from 'better-payment/plugins';

const payment = betterPayment({
  mode: 'production',
  providers: { iyzico: iyzico({ /* ... */ }) },
  plugins: [
    telemetry({
      tracer: trace.getTracer('better-payment'),
      meter: metrics.getMeter('better-payment'),
    }),
  ],
});

tracer, meter ya da ikisini birden verin. Hiçbiri verilmezse plugin hiçbir iş yapmaz. Yalnızca sağlayıcı işlemleri bildirilir; sağlayıcıya özel metotlar (checkout formülleri, abonelikler) plugin sistemi içindeki gibi hook'larsız çalışır.

SeçeneklerCopy Anchor Link

payment.telemetry.disable(); // the hooks do no work at all
payment.telemetry.enable();
payment.telemetry.enabled;   // true

Span nitelikleriCopy Anchor Link

Her çağrı, adında payment.<operation> olan (payment.createPayment, payment.refund, ...) ve yalnızca şu nitelikleri taşıyan bir span üretir:

Her nitelik düşük kartinalitylidir ve yalnızca işlem meta verisinden gelir. Kart numaraları, tokenler, CVV, e-postalar, IP'ler, conversation id'ler, istek/yanıt gövdeleri ve sağlayıcı mesajları okunmaz; bu nedenle bir niteliğe asla ulaşamazlar. 64 karakterden uzun değerler düşürülür. Başarısız span ERROR (2), başarılı olan OK (1) durumu alır.

MetriklerCopy Anchor Link

Bir meter verildiğinde plugin ayrıca çağrı başına şunları kaydeder:

• payment.calls sayacı: yukarıdaki niteliklerle +1, süre hariç;
• payment.duration histogramı: çağrının milisaniye cinsinden süresi.

Her iki enstrüman da tembelce, ilk bildirilen çağrıda bir kez oluşturulur.

OpenTelemetry uyumluluğuCopy Anchor Link

@opentelemetry/api bağımlılığı yoktur: plugin kullandığı birkaç üyeyi (startSpan, setAttribute, setStatus, end, createCounter, createHistogram) gerçek API ile aynı biçime sahip yapısal arayüzler olarak tanımlar — TelemetryTracer, TelemetrySpan, TelemetryMeter. OpenTelemetry'nin verdiği her şey (trace.getTracer, metrics.getMeter) bu arayüzleri karşılar; OpenTelemetry kullanmayan uygulamalar kendi tracer'ını ya da hiçbir şey vermeyebilir.

Panolar ve uyarılarCopy Anchor Link

Nitelik kümesi, üç sağlayıcı-çağrısı SLO'su için gereken tam şeydir. OpenTelemetry collector metrikleri Prometheus'a gönderirken payment.calls sayacı payment_calls_total, payment.duration histogramı ise payment_duration_milliseconds olur:

# failure ratio over the last 5 minutes, per provider
sum by (payment_provider) (
  rate(payment_calls_total{payment_result="failure"}[5m])
)
/
sum by (payment_provider) (rate(payment_calls_total[5m]))

Span'ler aynı nitelikleri taşıdığı için izler, kart verisi içerebilecek bir log satırı açmadan hangi ödemenin hangi sağlayıcı çağrısının yavaş ya da hatalı olduğunu gösterir.

Ödeme güvenliğiCopy Anchor Link

Telemetri bir ödemenin sonucunu asla değiştiremez: plugin yalnızca after hook'unda sonucu okur ve hiçbir şey döndürmez; her tracer ve meter çağrısı sarılmıştır — exception fırlatan bir tracer yapılandırılmış logger üzerinden raporlanır ve ödemeye değişmeden devam edilir. Kayıt işlemleri sınırlıdır (timer yok, yukarıdaki pendingTimeoutMs ve maxPending), ve plugin Node'a özel API kullanmadığı için kütüphanenin geri kalanı gibi edge çalıştırıcılarında da çalışır.