Telemetri: OpenTelemetry köprüsü ve no-op yedeği

Bir bakışta

Telemetri modülü, motoru OpenTelemetry (OTel) yazılım geliştirme kitine (SDK) bağlayan isteğe bağlı köprüdür. SDK kurulu olduğunda, temizlenmiş özniteliklerle span ve metrikler yayınlanır. SDK bulunmadığında, no-op tracer ve meter nesnelerinden oluşan eksiksiz bir küme enstrümantasyon çağrılarını geçerli ve fiilen ücretsiz tutar. Enstrümantasyonu kod akışında güvenle bırakabilirsiniz.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Tasarım hedefi, SDK bulunmadığında gözlemlenebilirliği sıfır maliyetle sağlamaktır. Motorun performans açısından sıcak yolları, bir tracer ve bir meter çağrısını önceden denetlemeden yapar. Bu çağrıların gerçek iş yapıp yapmayacağı, her çağrı noktasındaki bir koşula değil, çalışma zamanı durumuna bağlıdır.

OpenTelemetryInterceptor köprü görevi görür. isAvailable() OTel SDK’nın mevcut olup olmadığını bildirir. startSpan(string $name, array $attributes = []) / endSpan(?object $span) izlenen bir işlemi parantez içine alır ve recordMetric() bir sayaç veya gösterge değeri kaydeder. OTel bulunmadığında, interceptor kendisini kullanılamaz olarak bildirir ve çağrılar etkisiz kalır. TelemetryBridge interceptor’ı motorun gözlem noktalarına bağlar.

AttributeSanitizer güvenlik katmanıdır. sanitize(array $attributes) öznitelik haritasını süreç dışına çıkmadan önce temizler. Telemetri öznitelikleri, kazara kişisel olarak tanımlanabilir bilgi (PII) aktarımı için yaygın bir kanaldır; bu nedenle temizleme bir eklenti değil, sözleşmenin parçasıdır. Temizleyici, interceptor ve köprü @since 2.3.0 sürümündedir.

NullTracer, NullSpanBuilder, NullSpan, NullMeter, NullCounter ve NullHistogram no-op yedeğidir. OTel SDK’nın sunduğu çağrı biçimleriyle eşleşirler: spanBuilder(), setAttribute() (zincirlenebilir), startSpan(), end(), createHistogram(), createUpDownCounter(), add() ve record(). Hiçbir şey yapmazlar. Yedek eksiksiz olduğu için, enstrümante edilmiş kod kullanılabilirliğe göre dallanmaz; tracer’ı çağırır ve no-op çağrıyı soğurur.

API yüzeyi

Sınıf	Temel üyeler	Rol
OpenTelemetryInterceptor	isAvailable(), startSpan(), endSpan(), recordMetric()	OTel span ve metrik köprüsü (@since 2.3.0)
TelemetryBridge	motor bağlantısı	Interceptor’ı motor gözlem noktalarına bağlar (@since 2.3.0)
AttributeSanitizer	sanitize(array $attributes): array	Öznitelikleri PII güvenliği için temizler (@since 2.3.0)
NullTracer	spanBuilder(string $name): NullSpanBuilder	No-op tracer
NullSpanBuilder	setAttribute(), startSpan(): NullSpan	No-op span builder (zincirlenebilir)
NullSpan	end()	No-op span
NullMeter	createHistogram(), createUpDownCounter()	No-op meter
NullCounter / NullHistogram	add(), record()	No-op enstrümanlar

Eksiksiz PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Telemetry komutunu çalıştırın.

Kod örneği — hızlı başlangıç

Kaynak: examples/33-opentelemetry-observability.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Telemetry\OpenTelemetryInterceptor;

$otel = new OpenTelemetryInterceptor(/* optional OTel tracer/meter */);

$span = $otel->startSpan('pdf.render', ['doc.pages' => 12]);
// ... render work ...
$otel->endSpan($span);

$otel->recordMetric('pdf.render.bytes', 482_113, ['profile' => 'pdfa4']);

OTel SDK bulunmadığında, yukarıdaki her çağrı bir no-op’tur. Kod aynı kalır ve maliyet sıfır olur.

Kod örneği — üretim

Çağıranın sağladığı meta verilerin bir span’e sızmasını önlemek için işleme işlemini temizlenmiş özniteliklerle sarmalayın.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Telemetry\AttributeSanitizer;
use NextPDF\Telemetry\OpenTelemetryInterceptor;

final readonly class InstrumentedRenderer
{
    public function __construct(
        private OpenTelemetryInterceptor $otel,
        private AttributeSanitizer $sanitizer,
    ) {}

    /**
     * @param callable():string         $render     Returns the rendered PDF bytes.
     * @param array<string, mixed>      $attributes Caller-supplied span attributes.
     */
    public function render(callable $render, array $attributes): string
    {
        $span = $this->otel->startSpan('pdf.render', $this->sanitizer->sanitize($attributes));

        try {
            return $render();
        } finally {
            $this->otel->endSpan($span);
        }
    }
}

Uç durumlar & tuzaklar

• No-op yedeği tasarım gereği eksiksizdir. Enstrümantasyonu “işten tasarruf etmek” amacıyla isAvailable() ile korumayın. No-op zaten hiçbir maliyet getirmez ve bu koruma, tasarımın kaldırdığı dallanmayı geri ekler.
• Çağıranın sağladığı öznitelikleri bir span veya metriğe eklemeden önce her zaman AttributeSanitizer üzerinden geçirin. Telemetri öznitelikleri kazara bir PII kanalıdır.
• endSpan(null) geçerlidir: null span, no-op durumudur. Her startSpan() çağrısını bir endSpan() ile bir finally içinde eşleştirin.
• NullSpanBuilder::setAttribute() zincirleme için static döndürür. No-op durumunda, zincir tasarım gereği etkisizdir.
• Yeniden üretilebilirlik profili structural olarak belirlenmiştir: span’ler zaman damgaları ve iz tanımlayıcıları taşır; bu nedenle bu alanlarda iki çalıştırma arasında farklılık olur.

Performans

OTel bulunmadığında, maliyet bir no-op’a yapılan metot çağrısından ibarettir ve fiilen ücretsizdir. OTel mevcut olduğunda, maliyet OTel SDK’dan gelir; köprü buna, öznitelik sayısıyla doğrusal ölçeklenen öznitelik temizlemeyi ekler. 1500 ms duvar / 64 MB tepe değerindeki performance_budget, bir telemetri hizmet düzeyi sözleşmesi (SLA) değil, motor referans bütçesidir.

Güvenlik notları

Telemetri bir veri çıkış yüzeyidir. AttributeSanitizer sırları ve PII’yi span ve metriklerin dışında tutar. Çağırandan etkilenen herhangi bir öznitelik için temizlemeyi zorunlu kabul edin; bu, projenin güvenli telemetri yükümlülüğüdür. OTel dışa aktarıcısı verileri harici bir arka uca gönderir ve o arka uç bir güven sınırıdır. Uç noktasını ve kimlik bilgilerini, sürüm denetimine işlenmiş yapılandırma yerine bir gizli anahtar yöneticisi üzerinden yapılandırın. Span ve metrik verilerinin bir günlük havuzuna ulaştığını varsayın ve buna göre temizleyin. Motor tehdit modeli için /modules/core/security/ bölümüne bakın.

Uyumluluk

Bu modül, herhangi bir Taşınabilir Belge Biçimi (PDF) belirtimi hakkında normatif iddiada bulunmaz. Bir PDF maddesine değil, harici bir gözlemlenebilirlik belirtimi olan OpenTelemetry veri modeline köprü kurar. No-op yedeği, enstrümante edilmiş kodun taşınabilir kalması için OpenTelemetry uygulama programlama arabirimi (API) yüzeyini yansıtır. Bu, bir PDF uyumluluk beyanı değil, bir API uyumluluğu özelliğidir. Motor uyumluluğu, /modules/core/conformance/ bölümünde açıklanan oracle ve golden paketleriyle doğrulanır.

Ayrıca bakınız

• Observability modülü — daha geniş çalışma zamanı durumu yüzeyi.
• Performance modülü — telemetriyle eşleşen bellek tanılaması.
• Contracts / Observability — yapılandırılmış istisna ve bozulma sözleşmeleri.
• Motor güvenlik modeli