İşletme

Portta ne var

Tek bir adres her şeyi sunar: /v1/traces, /v1/logs ve /v1/metrics üzerinde OTLP alımı, /v1/ingest üzerinde yerel alım, /v1/api altında sorgu API'si, / üzerinde operatör arayüzü ve aşağıdaki üç işletim ucu. Yapılandırılacak bir yan araç ya da ters proxy yoktur; bu da kurulumun neden tek satıra sığdığının büyük kısmıdır.

Arayüz ikili dosyanın içine derlenmiştir, yani ne statik dosya sunucusu ne de ikinci bir birim bağlaması vardır. Alım, büyük gövde sınırını taşır ve CORS taşımaz. Sorgu API'si CORS taşır, böylece başka bir kökenden sunulan bir arayüz onu okuyabilir.

/healthz ile /readyz aynı soru değildir

Ayrıdırlar, çünkü farklı sonuçlara yanıt verirler; ikisini de aynı işleyiciye bağlamak yeniden başlatma döngüsü kurmanın yaygın bir yoludur.

/healthz canlılıktır. Depoya bilerek hiç dokunmaz: yavaş ya da kilitli bir veritabanı sürecin öldürülüp yeniden başlatılmasına yol açmamalıdır, çünkü yeniden başlatmak diski onarmaz ve başlatma döngüsü size yolda olan yığınları da kaybettirir.

/readyz hazırlıktır. Bir okuyucu bağlantısı üzerinde tek bir önemsiz sorgu çalıştırır, böylece hizmet veremeyen bir örneğe trafik gönderilmesi durur. Depo erişilemez durumdayken 503 yanıtı verir: status alanı degraded olur ve detail hatayı adlandırır. Çıplak bir durum kodu sizi körlemesine araştırmaya gönderirdi.

İki gövde de aynı alanları taşır: status, version, spec_version, uptime_seconds, storage ve bir sorun varsa detail. spec_version, bu sürümün uyguladığı veri modeli sürümüdür; bir istemcinin anlamadığı bir sunucuyla konuşmayı reddedebilmesinin yolu budur.

$ curl -s localhost:4317/healthz{"status":"ok","version":"0.1.0","spec_version":"1.0.0", "uptime_seconds":86400,"storage":"sqlite"}$ curl -s -o /dev/null -w "%{http_code}\n" localhost:4317/readyz200$ curl -s localhost:4317/metrics | head -4# HELP mcpd_signals_accepted_total Signals written to storage.# TYPE mcpd_signals_accepted_total countermcpd_signals_accepted_total 184203# HELP mcpd_signals_rejected_total Signals refused, with a reason returned to the sender.

İki yoklama da anahtar istemez, /metrics de istemez. Ağınızda bu kabul edilebilir değilse, girişinizde kısıtlayın.

livenessProbe:
  httpGet: { path: /healthz, port: 4317 }
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readyz, port: 4317 }
  periodSeconds: 5

# SIGTERM karşılanır, yoldaki alımın bitmesi için süre tanıyın.
terminationGracePeriodSeconds: 30

Metrikler

mcpd kendi sayaçlarını /metrics üzerinde Prometheus metin biçiminde dışa verir. Bir özellik bayrağının arkasında değillerdir: gözlenemeyen bir gözlemlenebilirlik aracı yüktür.

Her sayaç süreç ömrü boyuncadır ve yeniden başlatmada sıfırlanır, bu yüzden bir seviyeye değil bir hıza uyarı kurun. İzlemeye değer iki tane var. mcpd_signals_rejected_total, gönderenlere hayır dendiği ve büyük olasılıkla yanıtı okumadıkları anlamına gelir. mcpd_request_errors_total ise tanımı gereği mcpd'nin kendi kusurudur: bir 4xx çağıranındır ve orada hiç sayılmaz.

Yükselen bir mcpd_traces_sampled_out_total bir kusur değildir. Biri neden çalıştırmasının eksik olduğunu sorduğunda arayüzdeki boşluğu açıklayan sayı odur.

mcpd_signals_over_quota_total, bir sinyalin yerine ulaşmamasının öbür nedeni için aynı biçimde bir sayıdır: proje dakikalık tavanına çarptı. Bu retler mcpd_signals_rejected_total içinde de sayılır, bu yüzden sınırlanan bir filoyu bozuk veri gönderen bir filodan ayırmak için bunu izleyin. Tavanın neyi kapsadığı için Yapılandırma sayfasına bakın.

mcpd_signals_unbounded_total karşıt sayıdır: adlandırdıkları projeyi hiçbir tavan kapsamadığı için saklanan sinyaller. Yalnızca projects altında yazılmış tavanlar adlandırdıkları projeleri sınırlar, yani başka bir ad veren gönderen onların yanından geçip gider. Bu sinyaller reddedilmek yerine sayılır, çünkü kimsenin yazmadığı bir projeyi reddetmek, yapılandırmasını değiştirmeden yükselten bir kurulumun verisini düşürürdü. Sıfır olmaması, proje bazlı olanların yanına üst düzey bir --quota-per-minute koymanız gerektiği anlamına gelir.

Tavan, bir satırın girebileceği her kapıyı kapsar: dört alım ucu, tek kayıtlık puan ve geri bildirim uçları ve puanları hesaplanıp saklanmadan önce aynı sayaca yazılan POST /v1/api/score. Orada tavanın altına sığmayan, tavanın ötesine yazılmak yerine yanıtın skipped listesinde puan başına bildirilir.

mcpd_audit_write_failures_total, yazılamayan denetim satırlarını sayar. Her satırın anlattığı istek yine de başarılı oldu ve verisini yine de döndürdü, ki mesele budur: bir denetim yazması, anlattığı okumayı hiçbir zaman başarısız kılmaz. Sıfır olmaması bu yüzden, saklanmış yüklerin denetim günlüğünün hesabını veremediği okumaların olduğu anlamına gelir; onu bir erişilebilirlik sinyali değil bir bütünlük sinyali sayın.

scrape_configs:
  - job_name: mcpd
    static_configs:
      - targets: ['mcpd:4317']

Kapanış

mcpd, SIGTERM ve SIGINT sinyallerini karşılar. Her ikisinde de yeni bağlantı kabul etmeyi bırakır ve süreç çıkmadan önce yolda olan isteklerin bitmesine izin verir.

Bunu bir orkestratör altında işler kılan, özellikle SIGTERM sinyalinin karşılanmasıdır. Kubernetes SIGTERM gönderir ve SIGKILL öncesinde tanıdığı ek süreyi bekler; yalnızca SIGINT dinleyen bir konteyner durdurulmaz, öldürülür ve o sırada işlemin ortasında olan yığın kaybolur.

mcpd 0.1.0 listening on http://0.0.0.0:4317  storage     sqlite at /data/mcpd.dbretention removed 12480 rows older than 30 daysreceived termination signalshutting down

mcpd'nin çıkarken kurtaramayacağı şey, hâlâ bir gönderenin kuyruğunda duran her şeydir. SDK'lar span'leri bellekte tutar ve bir worker üzerinde dışa verir; yani shutdown() çağırmadan çıkan bir süreç, henüz gitmemiş olan her şeyi kaybeder. Bu, daemon'un değil ajanın doğru yapması gereken kapanıştır.

Yedekler

Deponun tamamı --data konumundaki tek bir SQLite dosyasıdır. WAL kipinde çalışır, yani diskte mcpd.db yanında mcpd.db-wal ve mcpd.db-shm dosyalarını bulacaksınız. Süreç çalışırken yalnızca .db dosyasını kopyalamak, size ileri yazma günlüğünde duran her şeyin eksik olduğu bir dosya verir.

Yedeği SQLite üzerinden alın; mcpd yazmayı sürdürürken tutarlı bir anlık görüntü okur:

Önce süreci durdurup üç dosyayı da kopyalamak da eşit derecede geçerlidir ve imajda bir sqlite3 ikili dosyası gerektirmez. Bu sürümde mcpd backup alt komutu ve zamanlanmış yedek yoktur: bu, anlık görüntü araçlarınızın işidir ve aksini iddia etmek kritik yola yarım kalmış bir tanesini koyardı.

Saklama satırları siler ama dosyayı küçültmez. SQLite boşalan sayfaları tutar ve yeniden kullanır; yani disk kullanımı büyük bir silmeden sonra düşmek yerine yatay seyreder. Yeri gerçekten geri almanız gerekiyorsa durdurulmuş bir örnek üzerinde VACUUM çalıştırın.

Geri yükleme

Bir yedeği geri koymak dört adımdır ve ileri yazma günlüğü yüzünden sıra önemlidir.

1. Daemon'u durdurun. Çalışan bir sürecin altında geri yükleme, aynı dosya üzerinde ikinci bir yazıcı demektir.
2. Yedeği --data konumundaki dosyanın üzerine kopyalayın.
3. Yanındaki -wal ve -shm dosyalarını silin. Onlar yerine geçtiğiniz veritabanına aittir ve yerinde bırakılırlarsa geri yüklediğinize tekrar oynatılırlar.
4. Daemon'u başlatın ve geri yüklenen dosyayı okuduğunu doğrulayın: /readyz 200 yanıtı verir ve proje üzerinde bir trace listesi yedeğin tuttuğu çalıştırmaları döndürür.

$ kill $(cat mcpd.pid) && cp /backup/mcpd-2026-09-01.db /data/mcpd.db$ rm -f /data/mcpd.db-wal /data/mcpd.db-shm$ mcpd --data /data/mcpd.db &$ curl -s -o /dev/null -w "%{http_code}\n" localhost:4317/readyz200$ curl -s "localhost:4317/v1/api/traces?project=default&limit=500" | jq ".traces | length"2

Yükseltmeler

İkili dosyayı ya da imaj etiketini değiştirin ve yeniden başlatın. Şema her seferinde açılışta uygulanır ve güncel bir dosya üzerinde çalıştırıldığında hiçbir şeyi değiştirmeyecek şekilde yazılmıştır. Uygulanan sürüm, aynı dosyanın içindeki bir schema_version tablosuna kaydedilir ve bu sürüm 2 numaradadır.

Akılda tutulacak iki şey. Geriye değil ileriye alın: eski bir ikili dosyanın daha yeni bir dosyayı okuyacağı vaat edilmez, bu yüzden önce yedeği alın. Ve SDK sürümlerini sabitliyorsanız yükseltmeden sonra /healthz üzerinden spec_version değerini denetleyin, çünkü bir istemcinin karşılaştırdığı sayı odur.

Tek bir örnek nerede yetmez

Bu konuda dürüst olmak, ölçmediğimiz bir sayıdan daha yararlıdır. Hiçbir verim rakamı yayımlamıyoruz, çünkü arkasında durabileceğimiz hiçbiri yok.

• Tek yazıcı. SQLite deposu bir muteks arkasında tek bir yazma bağlantısı ve dört okuma bağlantısı tutar. WAL kipi, bir pano sorgusunun alımı hiç engellememesi demektir, ki asıl önemli olacak hata buydu; ancak bütün yazmalar o tek bağlantı üzerinden sıraya girer.
• Dosya başına tek örnek. Aynı dosyaya yönlendirilmiş iki mcpd süreci desteklenen bir kurulum değildir. Onu yatay ölçeklenen bir hizmet olarak değil, bir birimi olan tek bir kopya olarak çalıştırın.
• Yukarıdaki iki sınır da gömülü deponundur. İçine derlenmiş olan ve aşağıda anlatılan ClickHouse üzerinde geçerliliklerini yitirirler.
• Payload'lar büyüktür. Prompt'lar ve tamamlamalar bayt değil kilobayt ölçeğindedir ve mcpd'yi çalıştırmaya değer kılan da onlardır. Depolama, span sayısıyla değil metin hacmiyle çok daha hızlı büyür; bu yüzden saniyedeki span rakamıyla değil kendi yüklerinizle ölçün.
• Saklama, yazdığınız projeleri kapsar. Saatlik tarama, projects bloğundaki her projeden siler; her biri kendi retention_days değerini ayarlamışsa ona, ayarlamamışsa genel rakama göre. Buna --project ile adlandırılan proje de eklenir. Bir gönderenin uydurduğu ve ikisinde de görünmeyen bir projenin penceresi yoktur ve hiç budanmaz; saklamaya bir gizlilik denetimi olarak güvenmeden önce bunu bilmeye değer.

Hacim örneği aştığında, size maliyeti sırasına göre kollar şunlardır: dosyayı sınırlayan --retention-days; girişi sınırlayan ve deterministik olduğu için tutulan bir trace'i bütün tutan --sample; ve tek yazıcı ile tek kopyayı birlikte kaldıran ClickHouse'a geçmek. Bakınız Örnekleme ve Maskeleme ve saklama.

Zaten bir tane çalıştırıyorsanız Postgres

mcpd'yi bir Postgres bağlantı dizesine yönlendirin, gömülü dosya yerine orada saklasın. Şema açılışta oluşturulur.

Bu, ClickHouse'un kaldırdığı aynı iki sınırı kaldırır. Yazmalar artık tek bir bağlantıdan geçmez, yani mcpd tek bir hizmetin arkasında birkaç kopya olarak çalışır; üstelik bunu çoğu ekibin zaten işlettiği, yedeklediği ve izlediği bir veritabanı üzerinde yapar.

Göç bir Postgres danışma kilidi alır ve şema zaten güncelse tümüyle atlanır. Birkaç kopyanın aynı anda başlaması bu yüzden güvenlidir ve aşamalı bir dağıtım, başka kopyaların yazdığı tablolar üzerinde dışlayıcı bir kilit almaz.

Tam metin araması, GIN dizinli üretilmiş bir tsvector sütunu kullanır, simple yapılandırmasıyla: küçük harfe çevirir ve sözcük sınırlarından böler ama kök bulmaz; yani bir prompt'ta yazdığınız sözcüğü birebir aramak beklediğiniz şeyi yapar.

Saklama milyarlarca span ile ölçülüyorsa Postgres yerine ClickHouse'u seçin. Bunun altında, zaten çalıştırdığınız veritabanı daha iyi yanıttır.

Dosya artık doğru biçim olmadığında ClickHouse

mcpd'yi bir ClickHouse HTTP ucuna yönlendirin, gömülü dosya yerine orada saklasın. Şema açılışta oluşturulur, yani elle uygulanacak bir şey yoktur.

Yukarıdaki iki kısıt birlikte kalkar. Yazmalar artık tek bir bağlantıdan geçmez, yani mcpd tek bir hizmetin arkasında birkaç kopya olarak çalışır ve span'ler bu verinin gerçek biçimi için kurulmuş bir MergeTree içine düşer: okumaktan çok daha fazla yazma ve bir zaman aralığını tarayan sorgular.

Saklama, bir dizüstünün diskiyle değil aylarca üretim trafiğiyle ölçüldüğünde onu seçin. Bundan küçük her şeyde gömülü dosya daha hızlı çalışır, daha hızlı yedeklenir ve işletilecek bir şey eksiktir. Canınızı yakana kadar dosyada kalın.

Trace'ler bir ReplacingMergeTree içindedir, çünkü bir trace izdüşümü span'leri geldikçe yeniden hesaplanır ve doğru olan son yazmadır. Sırasız gelen, yeniden denenen veya yerinde güncellenen span'ler bu yüzden kopya biriktirmek yerine doğru yanıtta buluşur.

Burada bir güvence diğer iki arka uçtakinden zayıftır ve belgelemek zorunda kalabileceğiniz güvence odur. ClickHouse üzerinde silme eşzamansız bir mutasyondur, yani bir silme isteği kabul edilir ve sonrasında uygulanır. SQLite ve Postgres, yanıtı veren işlemin içinde siler. Yanıt, ikisinden hangisinin olduğunu deletes_pending içinde söyler. Bakınız Maskeleme ve saklama.

Bir kurulumu denetlemek

mcpd doctor yapılandırmayı ve depoyu okur, neyin yanlış olduğunu bildirir ve her birini düzelten seçeneği adlandırır. Var olma nedeni, asıl canınızı yakan hataların sessiz olmasıdır: hiçbir şey çökmez ve haftalar sonra öğrenirsiniz.

Üç seçenek komutun kendisine aittir. --offline depo dışında hiçbir yere bağlanmaz, yani iletme ucu denetlenmiş değil atlanmış olarak bildirilir. --read-only hiçbir şey yazmaz, yani depolama denetimi deponun yazılabildiğini değil okunabildiğini kanıtlar ve bunu söyler. --window-days, etkinlik, saat ve fiyat kitabı denetimlerinin kaç günlük geçmişi okuyacağıdır; aksini söylemezseniz yedi, 1 ile 36525 arasında. Aldığı diğer her şey daemon'un kendi yapılandırmasıdır, yani başlatacağınız çağrıyı notlandırır.

Şu sırayla on iki grup notlandırılır ve rapor her düzeyin sayısıyla biter:

identity ve limits en son eklenen ikisidir ve ikisi de aynı nedenle notlandırılmıyordu: hiçbiri çökmeye yol açmıyor. Öznesi olmayan bir denetim günlüğü neyin yapıldığını kaydeder, hiçbir zaman kimin yaptığını değil. 0.0 ile 1.0 dışındaki bir örnekleme kesri --sample için reddedilir ama bir proje bloğunda hiç denetlenmezdi, yani bir proje böyle bir kesir taşıyabilir ve daemon onunla çalışırdı. Yanında üst düzey bir tavan olmadan proje bazlı ayarlanmış bir tavan, kimsenin yazmadığı her projeyi hiç tavansız bırakır ve proje adını gönderen seçer.

Atlanmış, tamam değildir

Çalıştırılmamış bir denetim atlandı der, hiçbir zaman tamam demez. Komutun asıl anlamı bu ayrımdadır: yönlendirdiğiniz yapılandırmada bulunmayan bir alt sistem sağlığı yerinde bir alt sistem değildir ve ikisini aynı şekilde bildirmek, doctor'ı tam da yanlış dosya verildiğinde en kendinden emin hâline getirirdi. Özet satırı atlanan denetimleri ayrıca sayar ve bunu sözle söyler; böylece on dört bulgusunun ikisini doğrulamış bir çalıştırma temiz bir sağlık raporu gibi okunamaz.

$ mcpd doctor --data /data/mcpd.db | tail -42 ok, 9 skipped, 2 warnings, 1 faultA skipped check proved nothing: it was not run, or there was nothing thereto run it against. Only the 2 ok were verified.A fault is something broken or open. Exiting 2.

Yoğun bir depo bozuk bir depo değildir

Yazma kilidine ihtiyaç duyan tek denetim depolama yoklamasıdır. Altındaki her şey okur ve okuyucular bir yazıcının arkasında sıraya girmez. O kilit için yarışı kaybeden bir yoklama yazması atlandı olarak bildirilir: üç kez denenir ve üçü de kilidi bekleyip vazgeçerse rapor, yazmanın denetlenmediğini ve nedenini söyler.

Bu önemlidir, çünkü gömülü depo tek bir yazıcı alır ve gerçek alım altındaki bir kurulum o kilidi neredeyse sürekli tutar. Çekişmeyi bir kusur olarak bildirmek, komutun tam da kurulum sağlıklı ve yoğunken bir dağıtımı düşürmesine yol açıyordu. Yoklamanın yakalamak için var olduğu hatalar kendilerini adlandırır ve hiçbiri "locked" demez: salt okunur bir bağlama, dolu bir disk ve INSERT yetkisi olmayan bir rol hâlâ kusurdur, bozuk bir kilit de öyledir; o "locking protocol" der ve gerçek hasardır.

Çıkış kodu

Bir kusurda sıfırdan farklı kodla çıkar, yani bir dağıtımı durdurabilir. Uyarı kusur değildir: sıfırla çıkar ve bir kişinin okumasını bekler. Bir yapılandırma uyarı değil kusur sayılır ve bunu bir hatta bağlamadan önce bilmeye değer: geri döngü olmayan bir adreste açık bir okuma kapsamı, ki porta erişebilen herkese saklanmış her prompt'u verir. Aynı adreste açık bir alım kapsamı uyarı olarak kalır, çünkü çöp satırları saklama temizler, ifşayı ise geri alamazsınız. İnternetin tamamını içeren güvenilir bir kimlik aralığı da aynı nedenle aynı şekilde notlandırılır: o zaman herhangi bir adres başlığı ayarlayıp adlandırdığı kişi olarak kaydedilebilirdi.

Erişilebilir olmadan önce denetlenecek ayarlar

mcpd, geri döngü olmayan bir adrese bağlandığında, ona erişmemesi gereken bir çağırana açık her yüzey için açılışta bir uyarı loglar ve her uyarı ayarlanacak seçenekleri adlandırır. Başlamayı reddetmek yerine uyarır, çünkü reddetmek sıfırdan ilk trace'e giden yolu koparırdı. Yine de gerçek bir açık hakkında uyarıdır: açık bir okuma API'si, porta erişebilen herkese saklanmış her prompt'u verir.

Son üç anahtar olmadan ingest anahtarı ve read anahtarı da çalıştırma yüzeyine erişir, read anahtarı da siler. Her anahtarın ve ayarlayabileceğiniz diğer her şeyin tam ayrıntısı Yapılandırma sayfasındadır.