İşleme sürecini OpenTelemetry ile gözlemleme

Bir bakışta

NextPDF, yerleşik OpenTelemetry izlemesi sunar: Taşınabilir Belge Biçimi (PDF) oluşturma yaşam döngüsü boyunca 10 izleme aralığı ve 7 metrik. Sözleşme nettir: OTel SDK’si yokken sıfır ek yük ve sıfır yapılandırma — otomatik yükleme hatası yok, başarım kaybı yok. Yazılım geliştirme kitini (SDK) kurun, genel olarak bir TracerProvider/MeterProvider kaydedin; aynı kod otomatik olarak dışa aktarım yapar. İzin listesi tabanlı bir AttributeSanitizer, Sıfır Güven Veri İlkesi’ni zorunlu kılar; böylece telemetri hiçbir zaman belge içeriği veya kişisel olarak tanımlanabilir bilgi (PII) taşımaz.

Bu sayfayı, taşıma katmanından bağımsız OpenTelemetry kavramlarının PHP’ye özgü tamamlayıcısı olarak kullanın. Çalıştırılabilir bir örnek ve onu destekleyen bir test, akışın tamamını kapsar.

Kurulum

composer require nextpdf/core:^3

Core tek başına, no-op açısından güvenli izleme yüzeyini sağlar. Canlı veri dışa aktarmak için SDK’yi ve bir dışa aktarıcıyı ekleyin.

composer require open-telemetry/sdk:^1
composer require open-telemetry/exporter-otlp:^1   # or zipkin / prometheus

Kavramsal genel bakış

İki giriş noktasını kullanın:

TelemetryBridge — statik bir cephe. isAvailable() OTel’i bir kez denetler ve sonucu önbelleğe alır. startSpan() / endSpan() / recordMetric(), OTel yokken kısa devre yaparak no-op olur. Sıfır ek yük sözleşmesi budur. OTel yokken bu çağrılar bir mikrosaniyenin oldukça altında tamamlanır.
OpenTelemetryInterceptor — SDK’yle tümleşen yol. Bilinen 10 aralığı otomatik olarak izler, bilinen 7 metriği kaydeder ve her özniteliği AttributeSanitizer üzerinden yönlendirir. Oluşturulurken SDK’nin varlığını denetler ve sonucu önbelleğe alır. Tüm OTel sınıf başvuruları çalışma zamanı korumalarının arkasında yer alır; böylece sınıf, SDK olmadan da yüklenir. Önerilen BatchSpanProcessor sınırları (maxQueueSize=2048, maxExportBatchSize=512) statik erişimciler olarak sunulur.

10 aralık: document.build, font.resolve, html.parse, writer.serialize, image.decode, layout.pass, barcode.encode, form.build, navigation.build, attachment.embed. 7 metrik: render.duration, render.page_count, render.warnings, render.memory_peak, render.file_size, render.font_count, render.image_count.

AttributeSanitizer yalnızca izin listesiyle çalışır. pdf.page_count, pdf.file_size_bytes, pdf.output_profile ve nextpdf.tier gibi yapısal meta veri anahtarlarına izin verir. Ham HTML’yi, PDF bayt akışlarını, base64 ikili nesnelerini ve dosya sistemi yollarını koşulsuz düşürür. Bu, NIST SP 800-92 yönergesindeki iki noktayı uygular: telemetri hassas içerik taşımamalıdır ve telemetri gizliliği açık bir denetimdir.

API yüzeyi

Uygulama programlama arayüzü (API) yüzeyi, NextPDF\Telemetry\TelemetryBridge, NextPDF\Telemetry\OpenTelemetryInterceptor ve NextPDF\Telemetry\AttributeSanitizer üzerindeki PHPDoc’tan üretilir. Burada kullanılan başlıca üyeler şunlardır: TelemetryBridge::isAvailable() / startSpan() / endSpan() / recordMetric(); OpenTelemetryInterceptor::knownSpans() / knownMetrics() / maxQueueSize() / maxExportBatchSize(); ve AttributeSanitizer::sanitize().

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Telemetry\TelemetryBridge;

$span = TelemetryBridge::startSpan('document.build', [
    'pdf.page_count' => 1,
    'nextpdf.tier'   => 'core',
]);

$doc = Document::createStandalone();
$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Observed render');
$pdf = $doc->getPdfData();

TelemetryBridge::recordMetric('render.file_size', strlen($pdf), []);
TelemetryBridge::endSpan($span); // null-safe when OTel is absent

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/out.pdf');

Kod örneği — üretim

Tam örnek SDK yokken de çalışır; böylece sıfır ek yüklü no-op yolunu kanıtlar. Sanitizer izin listesini çalıştırır ve test koşum aracının çıktı kanalını gözetir. Yeniden üretilebilirlik koşum aracı bu betiği iki kez çalıştırır.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Telemetry\AttributeSanitizer;
use NextPDF\Telemetry\OpenTelemetryInterceptor;
use NextPDF\Telemetry\TelemetryBridge;

// Discover the surface — static, dependency-free, SDK-optional.
$spans   = OpenTelemetryInterceptor::knownSpans();
$metrics = OpenTelemetryInterceptor::knownMetrics();

// Zero-Trust Data Policy: the sanitizer drops anything off the allowlist
// and anything that looks like a payload.
$sanitizer = new AttributeSanitizer();
$exported = $sanitizer->sanitize([
    'pdf.page_count'      => 1,
    'pdf.output_profile'  => 'PDF/A-4',
    'document.raw_html'   => '<html><body>secret</body></html>', // dropped
    'source.path'         => '/var/secret/invoice.pdf',          // dropped
]);

$span = TelemetryBridge::startSpan('document.build', [
    'pdf.page_count' => 1,
    'nextpdf.tier'   => 'core',
]);

$doc = Document::createStandalone();
$doc->setTitle('Observability demo');
$doc->addPage();
$doc->setFont('helvetica', 'B', 16);
$doc->cell(0, 12, 'Observe rendering with OpenTelemetry', newLine: true);
$pdf = $doc->getPdfData();

TelemetryBridge::recordMetric('render.page_count', 1, []);
TelemetryBridge::recordMetric('render.file_size', strlen($pdf), []);
TelemetryBridge::endSpan($span);

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/out.pdf');

fwrite(STDERR, sprintf(
    "spans=%d metrics=%d otel_available=%s sanitized_keys=%s\n",
    count($spans),
    count($metrics),
    TelemetryBridge::isAvailable() ? 'yes' : 'no',
    implode(',', array_keys($exported)),
));

Uç durumlar ve tuzaklar

Telemetri işlemeyi asla bozmaz. Hem köprü hem de interceptor kendi iç hatalarını yutar. Yanlış yapılandırılmış bir dışa aktarıcı gözlemlenebilirliği bozar, PDF çıktısını asla. İşleme kodunu, bir telemetri hatasını işleme hatası olarak ele alan bir catch bloğuna almayın.
endSpan(null) güvenlidir. startSpan(), OTel yokken null döndürür ve endSpan(), no-op olarak null kabul eder. Bunları her zaman çiftler hâlinde kullanın ve dönüş değerine göre asla dallanmayın.
Metrikler kayıtlı bir MeterProvider gerektirir. Yalnızca bir TracerProvider kayıtlıysa aralıklar dışa aktarılır ancak metrikler sessizce atlanır. Metrikler bilgi amaçlıdır. Tam kapsam için her iki sağlayıcıyı da kaydedin.
Sanitizer yalnızca izin listesiyle çalışır. İzin listesinde olmayan yeni bir öznitelik anahtarı dışa aktarılmaz. Bu davranış tasarım gereğidir. İzin listesini motorda genişletin ve sanitizer’ı atlamayın.
W3C İzleme Bağlamı yayılımı. Hizmetler arası izleme yayılımı, W3C İzleme Bağlamı traceparent/tracestate başlıklarını kullanır. Bunları NextPDF değil, OTel SDK’sinin yayıcıları işler. W3C İzleme Bağlamı Önerisi doğrulama derlemesinde bulunmadığından bu yayılım notu RAG ile çözümlenmemiştir ve normatif bir iddia olarak değil, tümleştirme yönergesi olarak belirtilmiştir. Yan dosyaya bakın.
Yeniden üretilebilirlik uyarısı. İşleme, her kayıtta /ID değeri ve değiştirilme tarihi yeniden üretilen bir belge yayınlar (ISO 32000-2 §14.3). Yakalanan PDF, yalnızca yapısal soyut sözdizimi ağacını (AST) ve meta veriyi kapsayan semantic profille karşılaştırılır.

Başarım

OTel’siz yol: isAvailable() ilk çağrıdan sonra önbelleğe alınır. Sonraki aralık ve metrik çağrıları tek bir boole denetimi yapıp geri döner. İzleme içeren örnek, SDK yokken sonuna kadar çalışır.
OTel ile: BatchSpanProcessor sınırları (maxQueueSize=2048, maxExportBatchSize=512), sürekli yük altında belleği sınırlar ve dışa aktarım sıcak yolun dışında kalır.
Belirtilen performance_budget (wall_ms: 3000, peak_mb: 128), rastgele belgeleri değil, koşum aracı çalıştırmasını sınırlar.
Bu reçete, #33 için §4.3 boşluk listesi kapsamındadır. Daha önce yalnızca MCP biçemindeki kavram sayfası vardı, PHP’ye özgü bir örnek bulunmuyordu. Yeni bir examples/33-opentelemetry-observability.php ile onu destekleyen tests/Cookbook/Php/ObserveWithOpenTelemetryRecipeTest.php yazıldı.

Güvenlik notları

Telemetri belge içeriği veya PII taşımamalıdır. AttributeSanitizer izin listesi bunu kodda zorunlu kılar. Ham HTML, PDF akışları, base64 ikili nesneleri ve dosya sistemi yolları düşürülür. Bu, hassas içeriği günlüklerin ve telemetrinin dışında tutmaya ve telemetri gizliliğini korumaya ilişkin NIST SP 800-92 yönergesiyle uyumludur.
Kendi eklediğiniz öznitelikler de izin listesine tabidir. İzin verilen bir anahtarın altına hassas değerler eklememekten siz sorumlu kalırsınız. Örneğin, bir kullanıcı tanımlayıcısını pdf.output_profile içine koymayın.
Tanılama ayrıntısını serbest biçimli yükler değil, yapılandırılmış anahtarlar taşır. Bu, PSR-3 §1.2’nin günlük bağlamına uyguladığı disiplinin aynısıdır.

Uygunluk

Beyan	Belirtim	Madde
Telemetri hassas içerik taşımamalıdır; PII işleme gereklidir.	NIST SP 800-92	§3
Telemetri/günlük gizliliği açık bir denetimdir.	NIST SP 800-92	§3
Yapılandırılmış bağlam anahtarları, serbest biçimli yük değil, ayrıntıyı taşır.	PSR-3	§1.2
Çıktı `/ID` değeri ve tarihler her kayıtta yeniden üretilir → semantic profil.	ISO 32000-2	§14.3

Bu reçete, mühendislik izleme davranışını açıklar. Herhangi bir uygunluk sertifikası iddiasında bulunmaz. NIST SP 800-92 başvuruları, bir uygunluk iddiasını değil, telemetride içerik taşımama tasarım amacını temellendirir.