Synopsis
trace record file-name [options]
trace amend file-path --add provider [options]
trace trim file-name [options]
trace plans [options]
trace providers [options]
Description
trace, performans analizi için kullanılan yazılım olaylarının (software events) dosyalarını kaydeder ve değiştirir. Bir izleme (trace) dosyası, sistemin belirli bir süre boyunca ne yaptığını yakalar; örneğin hangi iş parçacıklarının (threads) zamanlandığı, ilk kez hangi belleğin kullanıldığı ve çekirdekte, kullanıcı alanında veya yardımcı işlemcilerde çalışan yazılımlardan gelen diğer binlerce türde olay gibi.
Record
İzleme dosyaları (.atrc uzantılı), bir Darwin sisteminin belirli bir süre boyunca nasıl davrandığını yakalar. Varsayılan olarak, kdebug izleme olaylarından bir seçki, Birleşik Günlük Kaydı (Unified Logging) bilgileri ve semboller ile makine yapılandırması gibi analizi destekleyen meta verileri içerir.
record alt komutu, komut satırında iletilen bir plana ve seçeneklere göre mevcut sistemden bu dosyaları oluşturur. file-name konumsal bağımsız değişkeni bir ön ek olarak kullanılır ve yol bileşenlerini içerebilir. Dosyanın yolu, sonuna artan bir sayı ve ardından dosya uzantısı eklenerek türetilir. Belirli bir dosya yoluna yazmak için bağımsız değişkeni '.atrc' ile sonlandırın. Varsayılan plan, Instruments System Trace ve spindump(1) tarafından okunabilir dosyalar üretir.
Planlar; kullanıcının 'katmanlar' (layers) ve 'sağlayıcılar' (providers) ile güvenli yapılandırma yapmasını destekler. Katmanlar, trace record için yardım çıktısında listelenir ve planın hangi olayların toplanacağı gibi temel yapılandırmasını değiştirir. Sağlayıcıları listeleme henüz uygulanmamıştır, ancak bunlar kdebug izleme sınırlarının ötesindeki özel veri kaynakları gibi daha karmaşık özellikler ekler. Örneğin, Birleşik Günlük Kaydı (Unified Logging) desteği bir sağlayıcı olarak uygulanmıştır.
Bu alt komut, güvenli olmayan işlemler konusunda katıdır ve aracın güvenilirliğini etkileyebilecek tüm seçeneklerin, üretilen dosyaların kullanılamaz olabileceğini kabul etmek için --unsafe bayrağını da içermesini gerektirir. Deneysel özellikler de benzer şekilde ele alınır ve hala test edilme aşamasındayken bir --experimental bayrağı gerektirir.
--help | -h record alt komutu için bir yardım mesajı sunar.
--plan: Varsayılan olmayan bir plan kullanır. trace plans tarafından listelenenlerden biri olmalıdır.
--add layer-or-provider Seçilen plana bir katman veya sağlayıcı ekleyerek davranışını artırır. Katmanların listesi yardım mesajında veya trace plans çıktısında gösterilir. Sağlayıcıların listesi trace providers kullanılarak elde edilebilir.
--provider-name:option-name=option-value provider-name adlı sağlayıcı tarafından kullanılmak üzere option-name seçeneğini option-value olarak ayarlar. Olası seçeneklerin listesi trace providers tarafından raporlanır.
--omit layer-or-provider Seçilen plandan varsayılan bir katmanı veya sağlayıcıyı hariç tutar.
--overwrite Çıktı dosyasının önceden var olan bir dosyanın üzerine yazılmasına izin verir.
--compress Çıktı dosyasındaki olayları sıkıştırır.
--notify-after-start notification-name İzleme oturumunu başlattıktan sonra notify(3) ile notification-name adında bir Darwin bildirimi yayınlar. Diğer sistemler iş yüklerini aşamalandırmak için notify(3) arayüzleri veya notifyutil(1) ile bu bildirimi kullanabilir. Örneğin, ‘notifyutil -1 ktrace-start’, ktrace-start adlı bildirimin yayınlanmasını bekleyecek ve ardından çıkış yapacaktır. Ek bildirimler göndermek için bu seçenek birden fazla kez belirtilebilir.
--notify-after-end notification-name İzleme oturumu bittikten ve dosya tamamen yazıldıktan sonra notify(3) ile notification-name adında bir Darwin bildirimi yayınlar.
--end-after-duration durations Belirtilen süre geçtikten sonra izlemeyi sonlandırır.
--end-on-notification notification-name notification-name ile eşleşen bir Darwin bildirimi notify(3) ile yayınlandığında izlemeyi sonlandırır.
--end-on-kdebug-event event-id Verilen event-id değerine sahip bir kdebug olayı yayımlandığında izlemeyi sonlandırır. Bu özellik şu anda deneyseldir ve olay planın bir parçası değilse güvenli değildir.
--end-after-kdebug-events-size size-bytes Kdebug olayları için dosya belirtilen size-bytes bayt boyutuna ulaştığında izlemeyi sonlandırır.
--trailing-duration duration Yalnızca izleme sonlandırılmadan önceki belirtilen süre içindeki olayları dahil eder. Başka bir deyişle, olayların dairesel arabelleğini (ringbuffer) tutar ve geçmişte duration süresinden daha eski olanları atar. Bu seçenek, gelen olayları işlemek için harcanan daha yüksek CPU kullanımı pahasına, kaydın depolama üzerindeki G/Ç (I/O) etkisini azaltmak için kullanılabilir.
--command | -c command [command-options] İzlemeyi, komuttan oluşturulan bir alt sürece (subprocess) odaklar. Komut çıkış yaptığında kayıt sona erer.
--process | -p pid-or-name İzlemeyi, kimliği (pid) veya adı ile mevcut bir sürece odaklar. Bu seçenek birden fazla kez sağlanabilir ve --command seçeneğiyle birleştirilebilir.
--start-on-notification notification-name notify(3) veya notifyutil(1) ile notification-name ile eşleşen bir Darwin bildirimi yayınlanana kadar izlemeye başlamak için bekler. Örneğin, ‘notifyutil -p ktrace-end’ seçeneği ktrace-end adında bir bildirim yayınlar.
--profiling-interval duration Profil oluşturma zamanlayıcısını (profiling timer) planın belirttiğinden farklı bir hızda çalıştırır. duration bağımsız değişkeni us, ms ve s eklerini kabul eder.
Aşağıdaki seçenekler güvenli değildir ve kullanılamaz bir izleme dosyası üretme ihtimali vardır.
--unsafe Güvenli olmayan seçeneklerin kullanılmasına izin verir.
--experimental Deneysel planların ve seçeneklerin kullanılmasına izin verir.
--kdebug-buffer-size size-with-suffix kdebug izleme sistemi için varsayılan arabellek boyutunu geçersiz kılar. Daha küçük arabelleklerin olayları kaybetmesi muhtemelken, daha büyük arabelleklerin sistem üzerinde daha önemli bir etkisi olabilir.
--kdebug-filter-include filter-description Filtre açıklamasını takip ederek izleme dosyasına dahil edilecek ek kdebug olaylarını belirtir. Filtre açıklamaları, iki kuraldan birinin virgülle ayrılmış bir listesidir:
C0x01 Verilen sınıftaki tüm olayları filtreler; bu durumda, sınıf 1.
S0x0140 Belirli bir alt sınıftaki olayları filtreler; burada üst bayt sınıfı, alt bayt ise o sınıf içindeki alt sınıfı temsil eder. Bu durumda, sınıf 1 ve alt sınıf 0x40.
Ek olaylar arabellek boyutunda değişiklik yapılmasını gerektirebilir.
--kdebug-filter-exclude filter-description Bir filtre açıklamasını takip ederek kdebug olaylarının izleme dosyasına dahil edilmesini engeller. Bazı olaylar belirli analiz araçları için gereklidir.
--prioritize-collection Mümkün olan en yüksek toplama önceliğini veya --collection-priority tarafından belirtilen değeri kullanır. Diğer süreçlerle potansiyel olarak çakışır.
--collection-priority Toplama önceliğini ayarlar ve potansiyel olarak diğer süreçlerle çakışır.
--kdebug-continuous-time kdebug olaylarını kesintisiz zaman damgalarıyla (continuous timestamps) kaydeder.
Amend
trace amend, sağlayıcılardan önceden kaydedilmiş izleme dosyalarına daha fazla bilgi ekler.
--add provider-name Değişiklik sürecine en az bir sağlayıcı eklenmelidir.
--provider-name:option-name=option-value trace providers çıktısında açıklandığı gibi, değişiklik yapılacak sağlayıcı için seçenekleri ayarlar.
Trim
trace trim, belirli bir zaman aralığı dışındaki olayları bir izleme dosyasından kaldırır.
--from time-spec Sağlanan time-spec parametresinden önceki tüm olayları kaldırır; bu parametre ön ekine göre yorumlanan bir sayıdır:
@ olay zaman damgası (event timestamp)
birim belirten bir ek ile (‘s’, ‘ms’ veya ‘us’) izlemenin başlangıcından bu yana geçen süre
birim belirten bir ek ile izlemenin bitiminden önceki süre
--to time-spec Sağlanan time-spec parametresinden sonraki tüm olayları kaldırır.
--output | -o path Kırpılmış (trimmed) dosyayı belirtilen yola yazar.
Plans
trace plans, trace record için kullanılabilir planları ve bunlara eklenebilecek katmanları listeler.
--verbose Her plan hakkında belgeleri gibi ek bilgileri yazdırır.
--experimental Deneysel planları gösterir.
Providers
trace providers, trace record için kullanılabilir sağlayıcıları ve bunlara iletilebilecek seçenekleri listeler.
--experimental Deneysel sağlayıcıları gösterir.
Ktrace
‘ktrace’ özelliği iki çekirdek (kernel) alt sistemi tarafından desteklenir: kdebug olay biçimini ve arabellek sistemini sağlar, kperf ise tetikleyicilere dayalı olarak örnekleme bilgilerini olaylar olarak yayar.
kdebug tarafından kullanılan olay biçimi basit ve kısıtlayıcıdır, ancak etkilidir. Olaylar, 32 bitlik bir debug ID kullanılarak sınıflandırılır:
sınıf alt sınıf kod işlev ╭──────┬───────┬─────────────┬─╮ │ 8 │ 8 │ 14 │2│ ╰──────┴───────┴─────────────┴─╯ ╰──────────────╯ │ sınıf-alt sınıf 00│ ╰──────────────────────────────╯ │ olay ID │ ╰──────────────────────────────╯ debug ID
Sınıflar, sistemin geniş bölümleri için <sys/kdebug.h> içinde atanır. Each sınıf kendi alt sınıflarını atayabilir. sınıf-alt sınıf, üzerinde filtreleme yapılabilen en hassas ayrıntıdır. Kodlar her alt sınıftaki belirli olaylar içindir ve işlevler olayın bir başlangıç (DBG_FUNC_START), bitiş (DBG_FUNC_END) veya darbe (impulse - ayarlanmamış bırakılır) olup olmadığını belirtir. Bir olay ID'si, işlev bitleri 0 olarak ayarlanmış bir debug ID'sidir.
Olaylar ayrıca bir zaman damgası, 4 işaretçi boyutunda bağımsız değişken, olayı yayan iş parçacığının kimliği ve olayın yayıldığı işlemci kimliğini (CPU ID) içerir. İşlemci kimliği, sistemdeki işlemci sayısından daha büyük olabilir; bu bir yardımcı işlemci (coprocessor) olayını gösterir.
İzleme dosyaları, nasıl kaydedildiklerine ve yürürlükteki filtrelere bağlı olarak fs_usage(1), spindump(1) veya Instruments dahil olmak üzere özel araçlarla analiz edilebilir.
Exit Status
trace aracı başarı durumunda 0, bir hata oluşursa >0 ile çıkış yapar.
See Also
fs_usage(1), notify(3), ktrace(5) ve ktrace(1)
Darwin September 25, 2025 Darwin