NextPDF Connect'i OpenTelemetry ile gözlemleme

NextPDF Connect’i OpenTelemetry ile gözlemleme

Genel bakış

NextPDF, Taşınabilir Belge Biçimi (PDF) oluşturma yaşam döngüsü boyunca izleme span’leri ve metrikler yayan yerleşik OpenTelemetry araçlaması içerir. Sınıf yolunda hiçbir OpenTelemetry Yazılım Geliştirme Kiti (SDK) bulunmadığında araçlama etkinleşmez: performans maliyeti oluşmaz, otomatik yükleme hatası görülmez ve yapılandırılacak bir şey yoktur. Bu sayfa taşımadan bağımsızdır; dolayısıyla PDF’i süreç içi bir çağrı, bir Model Context Protocol (MCP) tools/call çağrısı, bir Temsili Durum Aktarımı (REST) isteği veya NextPDF Connect’e yapılan bir gRPC çağrısı aracılığıyla nasıl oluşturursanız oluşturun aynı araçlama geçerlidir.

Bu sayfayı çalıştırılabilir bir tarif değil, açıklama olarak değerlendirin. OpenTelemetry SDK’sını ve dışa aktarıcıyı ana uygulama sağlar; NextPDF sağlamaz. Bağımsız bir örnek bulunmadığından bu sayfa yeniden üretilebilir bir karma değeri sabitlemez.

Kurulum

OpenTelemetry SDK’sını ve dışa aktarıcıyı ana uygulama seçer ve kurar. NextPDF, global olarak kayıtlı bir izleyici sağlayıcısını okur ve kendi SDK’sını paketlemez. İzlemelere güvenmeden önce, NextPDF’in SDK’yı görebildiğini doğrulamak için paketle gelen kullanılabilirlik denetimini çalıştırın. Denetim, yalnızca OpenTelemetry API’si sınıf yolunda bulunduğunda true döndürür.

Kavramsal genel bakış

NextPDF, belge oluşturma yaşam döngüsü için span’ler ile küçük bir sayaç ve histogram kümesi yayar. Span’ler bir kök oluşturma span’ini, yazı tipi çözümlemesini, HyperText Markup Language (HTML) ayrıştırmasını, yerleşimi, görüntü kod çözümünü, serileştirmeyi ve isteğe bağlı barkod, form, gezinme ve ek aşamalarını kapsar. Metrikler işleme süresini, sayfa sayısını, uyarıları, en yüksek bellek kullanımını, çıktı boyutunu, yazı tipi sayısını ve görüntü sayısını kapsar. Span’lerin ve metriklerin tam dökümü, kurulu NextPDF sürümüne bağlıdır; bu nedenle eski metinlerde geçen sabit sayıları sürüme bağlı olarak değerlendirin. Bir sayıyı ezberlemek yerine çalışan derlemeye göre doğrulayın.

NextPDF Connect bir web çatısının arkasında çalıştığında, bir Connect çağrısı gelen Hypertext Transfer Protocol (HTTP) isteği izlemesinin alt öğesi olarak görünür. Böylece tek bir dağıtık izleme; HTTP girişini, uygulamayı ve PDF derlemesini kapsar.

API yüzeyi

Bu sayfa bir Connect aracı tanımlamaz. Bunun yerine genel kapsamdaki araçlamayı açıklar. Araç yüzeyi için bkz. /connect/tool-catalog/. Taşımalar için bkz. /transports/mcp/, /transports/rest/ ve /transports/grpc/.

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

Herhangi bir PDF oluşturmadan önce bir izleyici sağlayıcısını global olarak oluşturup kaydedin, ardından her zamanki gibi oluşturun. NextPDF’in dahili araçlaması, çağrı başına kod gerektirmeden span’leri ve metrikleri otomatik olarak yayar. Arabelleğe alınmış span’lerin kaybolmaması için süreç kapanırken sağlayıcıyı boşaltın. Somut sağlayıcı ve dışa aktarıcı entegrasyonunun sahibi ana uygulamadır. Bu entegrasyonu OpenTelemetry PHP projesi belgeler; bu sayfa onu birebir yinelemez.

Kod örneği — üretim

HTTP üzerinden dışa aktaran bir toplayıcı için ana uygulama bir PSR-18 HTTP istemcisi sağlar. Bir taşıma hatasını ve başarısız bir HTTP durumunu ayrı durumlar olarak değerlendirin. Bir PSR-18 istemcisi, tipli bir istemci özel durumunu yalnızca isteği hiç gönderemediğinde fırlatır (PSR-18 §4). Buna karşılık bir 4xx/5xx yanıtı, çağırana normal şekilde döner ve bir özel durum değildir (PSR-18 §4). Toplayıcıya dışa aktarım yolu ile Connect araç taşıması birbirinden bağımsızdır; bu nedenle başarısız bir toplayıcı dışa aktarması, PDF oluşturmanın kendisini asla başarısız kılmamalıdır.

Uç durumlar ve dikkat edilecek noktalar

• Sağlayıcının ilk oluşturmadan sonra kaydedilmesi. Kayıttan önce oluşturulan herhangi bir span, işlem yapmayan bir izleyici kullanır ve arka uca asla ulaşmaz. Sağlayıcıyı uygulama başlatılırken kaydedin.
• Kapatma sırasında boşaltma yapılmaması. Bir toplu işlemci span’leri arabelleğe alır ve süreç sağlayıcı kapatması yapılmadan sonlanırsa bu span’ler kaybolur. Sağlayıcı kapatmasını worker’a veya kernel terminate kancasına bağlayın.
• gRPC dışa aktarması, gRPC PHP uzantısını gerektirir. HTTP dışa aktarması hiçbir uzantı gerektirmez; bu nedenle uzantı kullanılamadığında HTTP’yi seçin.
• W3C Trace Context yayılımı. Gelen istek traceparent/tracestate taşıdığında, SDK bu bağlamı otomatik olarak NextPDF’in span’lerine yayar ve Connect çağrısı, çağıranın izlemesine katılır.

Performans

Araçlama yükü, PDF oluşturma süresiyle karşılaştırıldığında küçüktür. Frontmatter’daki bütçe belge düzeyinde bir üst sınırdır, garanti değildir. Yüksek istek oranlarında, dışa aktarıcı hacmini ve maliyetini sınırlamak için baş tabanlı veya toplayıcı tarafı örnekleme kullanın.

Güvenlik notları

Güvenli telemetri ve günlük temizleme

NextPDF, katı ve aşılamaz bir telemetri verisi ilkesi uygular. Sabit bir öznitelik izin listesi yalnızca yapısal meta verileri ve performans metriklerini dışa aktarır: sayfa, yazı tipi ve görüntü sayıları, dosya boyutları, çıktı profili adları, boole bayrakları, süreler, bellek, sürüm ve katman tanımlayıcıları. NextPDF, belge içeriğini, dosya yollarını, ham akış baytlarını, base64 yüklerini, kişisel verileri veya kimlik bilgilerini asla dışa aktarmaz. İzin listesi dışındaki tüm öznitelikleri çıkarır. Anahtarın kendisine izin verilmiş olsa bile, yük deseniyle eşleşen tüm değerleri de çıkarır. Bu davranış, belge verilerini sızdırmadan izlemelerin paylaşılan bir gözlemlenebilirlik hattına akmasını sağlar. Bu, bir kitaplık davranışıdır; izlemeleri alan arka uç hakkında dağıtım düzeyinde bir garanti değildir.

Uygunluk

İddia	Madde	reference_id
Taşıma hatası, tek PSR-18 istemci özel durumu örneğidir	PSR-18 §4
Bir 4xx/5xx yanıtı normal bir dönüş değeridir, özel durum değildir	PSR-18 §4

OpenTelemetry protokolü ve World Wide Web Consortium (W3C) Trace Context biçimi, her biri kendi kuruluşu tarafından sürdürülen dış spesifikasyonlardır. Bu sayfa bunlara uygunluk iddiasında bulunmaz ve metinlerini yeniden vermez. Yetkili tanımlar, yayımlanmış OpenTelemetry spesifikasyonunda (https://opentelemetry.io/docs/specs/otel/) ve W3C Trace Context Önerisi’nde (https://www.w3.org/TR/trace-context/) yer alır.

Ticari bağlam

Geçerli değil — araçlama bir çekirdek yetenektir ve kapı denetimine tabi değildir.

Connect ayrıntıları

Taşıma kullanılabilirliği (MCP / REST / gRPC)

Araçlama taşımadan bağımsızdır. Herhangi bir taşıma üzerinden yapılan bir Connect çağrısı aynı oluşturma yaşam döngüsü span’lerini üretir. Ana uygulama taşıma katmanını araçlandırdığında, taşıma kendi çevreleyen span’ini ekler.

HITL risk katmanı

Gözlemlenebilirlik, risk modelinden ayrıdır. Telemetri yaymak, bir aracın risk düzeyini değiştirmez ve asla ConfirmationGate tarafından kapı denetimine tabi tutulmaz.

Onay kapısı JSON zarfı

Geçerli değil — telemetri yayımı bir araç çağrısı değildir; bu nedenle kapıdan geçmez.

Ayrıca bkz.

• /connect/tool-catalog/ — gözlemlenen araç yüzeyi.
• /transports/mcp/ / /transports/rest/ / /transports/grpc/ — izlenen bir Connect çağrısını kabul edebilen taşımalar.