.NET SDK tam başvuru

.NET 8, 9 ve 10, net8.0 hedefli Sigillum Finans SDK 0.11.0 NuGet paketini ve Java/Python ile ortak gözlem sözleşmesini kullanır. Resmî OpenTelemetry bağımlılıkları zorunludur. Dağıtım ticari lisanslıdır; paketin oluşturulmuş olması herkese açık paket deposunda yayımlandığı anlamına gelmez.

Portalın sağladığı yerel NuGet kaynağından Sigillum.Finans.Sdk.AspNetCore paketini ekleyin. Dağıtım ZIP dosyası bu paket ile Sigillum.Finans.Sdk çekirdek paketini içerir. Üçüncü taraf bağımlılıklarını kurumun onaylı NuGet kaynağından çözümleyin. Worker ve konsol uygulamaları yalnız çekirdek paketi kullanır; ASP.NET Core paylaşılan çalışma ortamını gerektirmez.

Servise özel yapılandırmayı AppContext.BaseDirectory/.sigillum/config.json konumuna yerleştirin veya mutlak dosya yolunu belirtin.

using Sigillum.Finans.Sdk;

builder.Services.AddSigillum();
builder.Services.AddHttpClient();
// After building the application, before handlers that consume request bodies:
app.UseSigillum();

Kayıt işlemi, IHttpClientFactory istemcilerine hazır handler ekler. Middleware gelen ASP.NET Core isteklerini gözlemler. Ayrı bir müşteri yardımcı projesi veya gizli HTTP profili gerekmez. Doğrudan oluşturulan HttpClient için sağlanan handler kullanılır:

var client = new HttpClient(new SigillumHttpHandler(observer)
{
    InnerHandler = new HttpClientHandler()
});

Okunmamış gelen içerik yalnız HTTP/1.0 veya HTTP/1.1 çerçeveleme bilgisi gövde bulunmadığını kanıtlıyorsa tam ve boş sayılır: Transfer-Encoding bulunmamalı, Content-Length bulunmamalı veya geçerli tek bir sıfır uzunluk olmalıdır. Gözlenmiş parça veya yakalama kaybı da bulunmamalıdır. HTTP metodu tek başına yeterli değildir. Çelişkili, tekrarlı veya geçersiz başlıklar ile HTTP/2, HTTP/3 ve bilinmeyen protokollerde doğal tüketim tamamlanmayı göstermedikçe kayıt eksik kalır. SDK bu kontrol için gövdeyi okumaz, boşaltmaz veya geri sarmaz.

Worker veya toplu iş için SDK’yı bir kez başlatıp tanımlı işlem adını kullanın:

using var observer = new SigillumClient(absoluteConfigPath);
using var operation = observer.BeginOperation("configured-execution-name");
// Existing native work continues here.

Yapılandırma, güven hazırlığı ve teslim arka plan worker’ında çalışır. İş çağrısı hazırlık, ağ, disk, alındı veya flush beklemez. Dispose yeni yakalamayı durdurur; bekleyen teslimi beklemez. Yapılandırma hazır olmadan yapılan çağrılar yakalanmış gibi sunulmaz; gözlem kaybı bildirilir. Status hazırlık, bellek, doğrulanmış teslim, kayıp ve yeniden deneme bilgilerini ayırır.

Ortak sigillum.sdk-config/2 dosyasının alanları:

localTransfer varsa SDK worker’ı SFRAW001 yakalamalarını yerel Sigillum Agent /v1/captures adresine gönderir. İçerik özetleri, zarflar, SFREC001 paketleme, şifreleme, kalıcı yeniden deneme ve uzak TLS aktarımı ayrı ürün sürecinde yapılır. Özel OTEL yaşam döngüsü SDK worker’ında kalır. İş çağrıları ve uygulama başlangıcı ajanı beklemez. Ajan erişilemezse sınırlı RAM yeniden denemesi sürer; doğrudan uzak aktarım yedeğine geçilmez. Yerel hata beklemesi küçük rastgele sapmalı üstel artışla yapılandırılmış gecikmeden başlar; üst sınır 30 saniye veya daha büyük yapılandırılmış gecikmedir. Geçerli alındı hata serisini sıfırlar. Doğrudan aktarımın sabit gecikmesi değişmez.

HMAC ile doğrulanan tam localDurable alındısı, ajanın kalıcı yerel tesliminden sonra SDK bellek payını serbest bırakır. Status.LocalDurableRecords yerel, Status.DurableRecords doğrudan uzak teslimi sayar. Yerel alındı merkezde nihai kanıt kabulü değildir. Profiller aynı ajanın /v1/profiles yolundan alınır; imza ve sürüm kontrolleri korunur. localTransfer yoksa doğrudan HTTPS kullanılır.

execution başlangıcında tam operation adı ve boş path; http başlangıcında tam metot ve yol kullanılır. Paylaşılan servis entryPoints: [] ile gelen imzalı bağlam üzerinden çalışabilir. Geçerli bağlam veya eşleşen giriş olmadan uygulama tahmin edilmez.

Worker; kapsamın P-256 imzasını, anahtarını, kurum/ortamını, gerçek başlangıcını ve sınırlı servis kümesini doğrular. İmzasız veya sürüm-1 yapılandırmaya dönüş yoktur. Başlangıçta scopeToken ile UTC başlangıç zamanı sabitlenir; alt adımlar ve yeniden denemeler aynı kapsamı taşır.

Profiller aynı kökendeki kimlik doğrulamalı /api/transfer/profiles adresinden 30 saniyede bir yenilenir. TLS, zaman aşımı ve 1 MiB yanıt sınırı korunur. Yalnız doğrulanmış ileri sürüm yeni görüntü olarak uygulanır. Yenileme teslim yeniden denemesinden bağımsızdır; iş metotları ağ yapılandırması yapmaz. İptal yeni başlangıçları durdurur, kabul edilmiş çalışmaları yeniden yazmaz.

Gelen kapsamın servis kümesinde bulunmayan servis span, HTTP, AI veya referans kaydı üretmez; doğrulanmış bağlamı sonraki bağlı servise aktarabilir. Dönen kapsamda IsObserved false olur; önceki bağlamı geri yüklemek için kapsam normal biçimde dispose edilir. Başka uygulamaya bağlı olması mevcut uygulamanın kapsamını genişletmez.

Varsayılan sınırlar: 64 MiB, 1024 kayıt/etkin kapsam, 5000 ms worker istek zaman aşımı, 1000 ms yeniden deneme gecikmesi ve 65536 bayt parça. Özel OTEL span’ları, kodlanmış bekleyen paket ve kodlama çalışma alanı aynı sınırlı bütçeye dahildir. Kuyruk sınırı azaltılabilir; ortak 64 MiB/1024 tavanının üzerine çıkarılamaz.

SigillumClient servis genelindeki gözlemcidir. SdkOptions, SdkLimits, SdkEntryPoint ve ReceiptTrust tipli yapılandırma seçenekleridir. SdkOperation dispose edilebilir işlem/adım kapsamıdır. Context içindeki SdkContext gerçek işlem/span kimliklerini ve sabit ScopeToken değerini taşır. Current ve Context referans dizileri etkin ve kuyruktaki kayıtlardan ayrılmış kopyalardır.

Aileler lifecycle, ai, http, otel, context, source ve custom’dır. Alan adları, eksik alan ile açık null farkı, sayısal metnin hassasiyeti ve ek alanlar korunur. Yakalamanın true dönmesi yalnız sınırlı RAM kabulüdür. JSON nesne/derinlik/tekrarlı alan denetimi worker’da yapılır. Geçersiz veri teslim edilmez; bellek payı bırakılır ve aynı sabit işlem kapsamına kodlama kaybı kaydı eklenir. SDK iş nesnesi getter’larını veya tembel sonuçları gezmez, modelin gizli akıl yürütmesini çıkarmaz. Hazır UTF-8 JSON ve dizileri verin.

observer.Classification("""
    {"intent":"actual-source-intent","score":0.9876543210987654321}
    """u8.ToArray());

observer.SetReferences(new SdkReferences(
    SessionRef: existingSessionReference,
    PersonRef: existingPersonReference,
    External: [new("institution.trace", existingTraceReference)]));

SdkAttachment(Id, MediaType, Purpose, Bytes) özgün baytları; SdkLink(TraceId, SpanId, Relation) gerçek ilişkileri taşır. İçerik bütçe kabulünden sonra kopyalanır, hash/uzunluk/referansları worker üretir. JSON sınırı zarf payı düşülmüş 8 MiB, derinlik 32, ek sayısı en çok 128 ve tek ek en çok 16 MiB’dir; toplam 32 MiB paket ve kuyruk bütçesi ayrıca uygulanır. Büyük, bozuk veya kapasite dışı gözlem kayıp bildirir; iş çağrısına hata fırlatmaz veya tam kayıt gibi sunulmaz.

OTEL yardımcıları bilinen skaler veya aynı tür ilkel dizi değerlerini, olay ve bağlantılar bunların JSON nesnelerini kabul eder. OTEL’in integer/double tipleri kullanılır; keyfî hassasiyetli sayısal metin için ham JSON gözlemini kullanın. Değer tutulmadan bütçe ayrılır, değiştirilmiş değerin payı bırakılır. En çok 1024 öznitelik, 1024 olay, 1024 bağlantı, ilkel dizide 4096 eleman ve 64 dış referans vardır; ortak bayt sınırı her zaman geçerlidir. Bağımsız metin kısaltması yapılmaz. Özel Activity nesnesi dışarı açılmaz.

Desteklenen HTTP sınırları metot, hedef, başlıklar, durum, gerçekten tüketilen gövde, parça/konum/bitiş, güvenli hata/iptal türü ve gerçek ilişkileri kaydeder. Gövde önceden okunmaz. Send ve SendAsync gerçek aktarımı bir kez çağırır; senkron işlemler senkron kalır. Başarılı yeniden konumlama veya boyut değiştirme içeriği kısmi yapar. Bitişten sonraki konum değişikliği geçmişi değiştirmek yerine açık kayıp kaydı ekler.

Başlıklarda en çok 4096 ad/değer çifti ve toplam 1 MiB UTF-8 sınırı vardır; aşım complete: false ve kayıp bildirimi üretir. Başlık kopyaları ve JSON çalışma alanı aynı bütçeyi kullanır. Sarılı içeriğin başlık payı, uygulama içeriği dispose edene kadar tutulur. Pay yoksa doğal içerik değiştirilmez. EOF öncesi dispose, kapasite kaybı ve eksik tüketim kısmi kalır. Doğal değer, hata, iptal ve stream sahipliği uygulamadadır. traceparent, tracestate, yerel OTEL sağlayıcıları ve Activity.Current korunur.

Her SDK örneğinin kurumun OTEL ortamından bağımsız, sürekli etkin özel sağlayıcısı vardır. Resmî Activity başlangıç/bitiş ve listener çağrıları worker’da çalışır. İş yolu yalnız sınırlı bağlam ve değişmez gözlemler üretir. Yavaş kurum listener’ı gözlem teslimini geciktirebilir; bu enstrümantasyon üzerinden iş çağrısına girmez.

Özel span; resource, instrumentation scope, attributes, events, links, status ve gerçek düşen kayıt sayaçlarını taşır. Gerçek OTEL kimlikleri nativeContext, ürünün nedensel kimlikleri observerContext olarak sunulur ve etiketli bağlantıyla ilişkilendirilir. Kimlikler aynıymış gibi gösterilmez. Kaynak beyanı institutionProvided, otomatik HTTP/yaşam döngüsü sdkAutomatic, gerçek OTEL nativeOtel kökenindedir.

x-sigillum-context v2 taşıyıcısı MAC ve kapsam doğrulamasından geçer; scopeToken ayrıca imzalıdır. Bağlam MAC anahtarını bilmek servis kapsamını değiştirme yetkisi vermez. İsteğe bağlı referanslar 16 KiB taşıma sınırını aşarsa yalnız referansların aktarımı atlanır; yerel asıllar ve imzalı ilişki çekirdeği korunur, referencePropagationPartial bildirilir. Bu veri iş yetkilendirmesi değildir. SDK’sız bileşen gözlenmez; bağlam gerçekten taşınırsa ilişki devam eder. Paralel çağrılar ayrı çocuklardır. Zaman, içerik, kişi veya oturum benzerliğinden bağlam üretilmez.

Worker aynı işlem ve sabit profilde hazır bulunan en çok 16 kaydı ve 8 MiB’ı eşik beklemeden toplar. Geçerli daha büyük tek kayıt 32 MiB sınırında tek başına gider. Yeniden deneme aynı paket baytları, teslim kimliği ve bellek payını kullanır. Adil sıra başka işlemlerin teslimini engellemez. Yalnız gerçek kök servisin kök-span kaydı sabit başlangıç kabulünü tekrar taşır; alt-span paketleri boş kabul listesi kullanır.

Bellek, tam kurum/ortam/servis/kayıt/paket/teslim bağları ve sabitlenmiş P-256 alındı doğrulanınca bırakılır. Alındı kalıcı ürün teslimini kanıtlar; nihai merkezde yayımlama değildir. Alındı öncesi RAM kalıcı değildir; süreç kapanınca kaybolabilir. Ürün aktarım worker’ı şifreli kalıcı yeniden denemeyi yürütür. Aktarım en çok bir IPv4 ve bir IPv6 bağlantı denemesini eşzamanlı açar; kaybedeni iptal edip kapatır. Sunucu adı, TLS adı ve CA kontrolleri korunur; uygulamanın HTTP istemcisi değiştirilmez.