ktrace(1) · macOS Kılavuz Sayfası

Synopsis

     ktrace info
     ktrace trace [-ACNnrSstu] [-R path | -E] [-C codes-path [...]] [-T timeout] [-f filter-desc]
	       [-b buffer-size-mb] [-x pid-or-process-name [...] | -p pid-or-process-name [...]]
	       [--json | --csv | --ndjson | --json-64] [-c command [...]] [--only-named-events]
	       [--no-default-codes-files] [--continuous] [--disable-coprocessors]
     ktrace dump [-E] [-f filter-desc] [-l compression-level] [-T timeout] [-b buffer-size-mb] [-p
	       pid-or-process-name] [--stackshot-flags extra-flags] [--include-log-content]
	       [--disable-coprocessors] [--notify-tracing-started key] [path]
     ktrace init -b buffer-size-mb | -n n-events
     ktrace setopt [-f filter-desc] [-w] [-x pid-or-process-name [...] | -p pid-or-process-name
	       [...]]
     ktrace enable
     ktrace disable
     ktrace remove
     ktrace reset
     ktrace decode debugid [debugid [...]]
     ktrace emit debugid [arg1 [arg2 [arg3 [arg4]]]]
     ktrace symbolicate path
     ktrace machine
     ktrace config
     ktrace compress [-l -fast|balanced|small] path
     ktrace artrace [-nr] [-t timeout] [-i interval] [-o filename] [-b buffer-size-mb] [-f
	       filter-desc] [-F filter-desc] [-p pid-or-process-name]
	       [--kperf=sampler-name[,sampler-name@]timer-period|timer-frequency|kdebug-filter-desc]
	       [--remote[=remote-device]] [--type=full|profile|lite|morelite|none]
	       [--stackshot-flags extra-flags] [--notify-tracing-started key] [-c command [...]]

Description

ktrace, olayları izlemek veya bunları bir dosyaya kaydetmek için sistemi yapılandırabilir ve olayların insan tarafından okunabilir bir temsilini yazdırabilir.

Subcommands

ktrace, farklı işlevleri mantıksal gruplara ayırmak için bir alt komut (subcommand) sözdizimi kullanır. Her alt komut kendi seçenek kümesini alır, ancak birkaç seçenek birden fazla alt komutta kullanılabilir.

info Çekirdek izlemenin (kernel trace) mevcut yapılandırması hakkında bilgi yazdırır.

trace [-ACNnrSstu] [-R path | -E] [-C codes-path [...]] [-T timeout] [-f filter-desc] [-b buffer-size-mb] [-x pid-or-process-name [...] | -p pid-or-process-name [...]] [--json | --csv | --ndjson | --json-64] [-c command [...]] [--only-named-events] [--no-default-codes-files] [--continuous] [--disable-coprocessors]

Olayları, her bir olay için duvar saati zamanı (wall clock time), işlem adları ve olay adlarını otomatik olarak sağlayarak, insan tarafından okunabilir bir biçimde standart çıktıya (stdout(4)) yazdırır. -R veya -E seçenekleri olmadan, ktrace izleme ara belleklerini makul bir boyuta ilklendirir ve sonlanana kadar izlemeyi etkinleştirir.

-R path path konumundaki izleme dosyasından olayları yazdırır.

-E Yeni bir yapılandırma oluşturmak yerine mevcut bir yapılandırmayı kullanır. Bu seçenek, trace alt komutunu init ve setopt gibi diğer ktrace alt komutlarıyla birlikte kullanmak için gereklidir.

-N Olayların adlarını görüntülemez.

-C Zaman damgalarını kesintisiz zamanda (continuous time) yazdırır.

-n İş parçacığı (thread) adlarını görüntüler.

-r İzlemeyi yalnızca pencere modunda veya halka ara bellek (ring buffer) modunda yapılandırır ve başlatır -- olayları yazdırmaz. Daha sonra bellekteki olayları okumak için ktrace trace -E kullanılabilir.

-S Dizge (string) içerdiği bilinen izleme noktaları için argümanları dizge olarak yazdırır.

-s Argümanlarda bulunan adresleri sembollere çözümlemeyi (symbolicate) dener.

-t Zamanları varsayılan yerel duvar saati zamanı yerine Mach mutlak zaman damgaları olarak yazdırır.

-A Zamanları izlemenin başlangıcından bu yana geçen saniye olarak yazdırır.

-u Adresleri uuid-offset çiftlerine çözümlemeyi dener.

-C codes-path Olay kimliğinden ad eşlemelerini sağlamak için özel bir kod dosyası kullanır. Kod dosyalarının biçimi hakkında daha fazla ayrıntı için trace(1) sayfasına bakın.

-b buffer-size-mb Megabayt cinsinden özel bir ara bellek boyutu ayarlar.

-f filter-desc İzleme oturumuna hangi olayların izleneceğini kontrol eden bir filtre açıklaması uygular. Bir filtrenin sözdizimiyle ilgili ayrıntılar için FİLTRE AÇIKLAMALARI bölümüne bakın. Herhangi bir filtre açıklaması sağlanmazsa, tüm olaylar izlenecektir.

-T timeout timeout süresi dolduktan sonra izlemeyi sonlandırır. ns veya ms gibi son ekler desteklenir, ancak yalnızca bir sayı belirtilirse varsayılan olarak saniye kabul edilir.

-x pid-or-process-name [...] | -p pid-or-process-name [...] Olayları izleyebilecek işlemleri kısıtlar. Belirtilen işlemlerden ad veya pid değerine göre olayları hariç tutar (-x) veya yalnızca onları izler (-p). Bu seçenekler birbirini dışlar. Kendisine bağlanılamayan (attach) işlemler, kararlı (release) çekirdeklerde her zaman hariç tutulur. Benzer şekilde, araçların iş parçacığı zamanlama durum makinelerini sürdürmesine izin vermek için bu seçenekten bağımsız olarak Mach zamanlama alt sınıfındaki olaylar her zaman dahil edilir.

--json Olayları bir JSON nesneleri dizisi olarak yazdırır.

--csv Olayları CSV girdileri olarak yazdırır.

--ndjson Olayları satırla sınırlandırılmış JSON nesnelerinden oluşan bir akış olarak yazdırır.

--json-64 Olayları 64 bit sayılar içeren JSON nesnelerinden oluşan bir akış olarak yazdırır.

-c command [...] command ile belirtilen komutu çalıştırır ve bu komut çıktığında izlemeyi durdurur. Bu seçenekten sonraki tüm argümanlar komuta iletilir.

dump

Daha sonra ktrace trace -R ile incelenmek üzere izlemeyi path konumundaki bir dosyaya yazar. Herhangi bir yol belirtilmezse araç, çalışma dizininde trace001.ktrace ile başlayan numaralandırılmış yeni bir dosyaya yazar. Komut, ktrace sonlandırılana, isteğe bağlı zaman aşımı tetiklenene veya sarmalama (wrapping) devre dışı bırakılmış mevcut bir yapılandırma kullanılırken izleme ara bellekleri dolana kadar olayları yazmaya devam eder. Bir sıkıştırma seviyesi belirtilirse, dosya yazılırken sıkıştırılır. Bu seçenek için varsayılan olmayan değerlerin kullanılması, olay toplama yükünü artırabilir.

-E Yeni bir yapılandırma oluşturmak yerine mevcut bir yapılandırmayı kullanır.

-f filter-desc Dosyaya yazılan olaylara hangi olayların izleneceğini kontrol eden bir filtre açıklaması uygular. Bir filtrenin sözdizimiyle ilgili ayrıntılar için FİLTRE AÇIKLAMALARI bölümüne bakın. Herhangi bir filtre açıklaması sağlanmazsa, tüm olaylar izlenecektir.

-p pid-or-process-name Yalnızca pid veya process-name ile tanımlanan işlem için gerçekleşen olayları kaydeder. Çekirdek sınırlaması nedeniyle adın yalnızca ilk 16 karakteri dikkate alınır. Filtre sözdizimiyle ilgili ayrıntılar için FİLTRE AÇIKLAMALARI bölümüne bakın. Herhangi bir filtre açıklaması sağlanmazsa, tüm olaylar izlenecektir.

-T timeout timeout süresi dolduktan sonra izlemeyi sonlandırır. ns veya ms gibi son ekler desteklenir, ancak yalnızca bir sayı belirtilirse varsayılan olarak saniye kabul edilir.

--stackshot-flags extra-flags stackshot'ları kaydederken sağlanan extra-flags tam sayısını ek bayraklar olarak iletir.

--notify-tracing-started key İzleme başladıktan sonra key üzerinde bir bildirim yayınlar.

init -b buffer-size-mb | -n n-events

İzlemeyi, izleme ara bellekleri için buffer-size-mb megabayt alan veya n-events olay tahsis edecek şekilde ilklendirir. Bu alt komut, setopt, enable veya disable alt komutlarını ilk kez kullanmadan önce veya remove alt komutunu kullandıktan sonra sağlanmalıdır.

setopt [-f filter-desc] [-w] [-x pid-or-process-name [...] | -p pid-or-process-name [...]]

Mevcut izleme yapılandırmasındaki seçenekleri ayarlar. İzleme yapılandırması zaten ilklendirilmiş olmalıdır.

-f filter-desc Mevcut yapılandırmaya hangi olayların izleneceğini kontrol eden bir filtre açıklaması uygular. Bir filtrenin sözdizimiyle ilgili ayrıntılar için FİLTRE AÇIKLAMALARI bölümüne bakın. Herhangi bir filtre açıklaması sağlanmazsa, tüm olaylar izlenecektir.

-w İzlemeyi, izleme ara belleğinin yeni olaylara yer açmak için eski olayları kaldırdığı bir halka ara bellek gibi davrandığı “pencereli” (windowed) modda çalışacak şekilde yapılandırır. Varsayılan olarak, ara bellekte yeni olaylar için yer kalmadığında izleme sona erer.

-x pid-or-process-name [...] | -p pid-or-process-name [...] Olayları izleyebilecek işlemleri kısıtlar. Belirtilen işlemlerden ad veya pid değerine göre olayları hariç tutar (-x) veya yalnızca onları izler (-p). Bu seçenekler birbirini dışlar. Kendisine bağlanılamayan işlemler, kararlı çekirdeklerde her zaman hariç tutulur. Benzer şekilde, araçların iş parçacığı zamanlama durum makinelerini sürdürmesine izin vermek için bu seçenekten bağımsız olarak Mach zamanlama alt sınıfındaki olaylar her zaman dahil edilir.

enable Olayları izlemeye başlar.

disable Olayları izlemeyi durdurur. İzleme, devre dışı bırakıldıktan sonra aynı yapılandırma kullanılarak yeniden başlatılabilir.

remove Mevcut izleme yapılandırmasını kaldırır ve izleme ile ilişkili belleği serbest bırakır.

reset İzlemeyi ve kperf dahil olmak üzere ilgili alt sistemleri varsayılan durumlarına sıfırlar.

decode debugid [debugid [...]] Sağlanan debugid'leri oluşturan bileşenleri yazdırır.

emit debugid [arg1 [arg2 [arg3 [arg4]]]]

Sağlanan debugid ve argümanlarla izleme akışına bir olay yayar.

symbolicate path path konumunda bulunan izleme dosyasını sembollerine çözümler (symbolicate).

config Mevcut sistemin izleme yapılandırmasını yazdırır.

machine Mevcut sistemin makine bilgilerini yazdırır.

compress [-l fast|balanced|small] path Aksi -l seçeneği ile belirtilmedikçe, path konumunda bulunan izleme dosyasını small sıkıştırma seviyesini kullanarak sıkıştırır.

artrace [-nr] [-t timeout] [-i interval] [-o filename] [-b buffer-size-mb] [-f filter-desc] [-F filter-desc] [-p pid-or-process-name] [--remote[=device-name]] [--type=full|profile|lite|morelite|none] [--kperf=sampler-name,sampler-name@timer-period|timer-frequency|kdebug-filter-desc] [-d group] [-e group] [--stackshot-flags extra-flags] [--disable-coprocessors] [-c command [...]] Sistemin profilini çıkararak izleme olaylarını otomatik olarak adlandırılmış bir dosyaya yazar. Varsayılan olarak bu; zamanlayıcı, sanal bellek (VM) ve sistem çağrısı kullanımını ölçer ve çekirdekteki iş parçacıklarını periyodik olarak örnekler.

-o path Oluşturulacak dosyanın adını belirtir.

-f filter-desc Filtre açıklaması tarafından belirtilen sınıfları ve alt sınıfları izler. Filtre sözdizimiyle ilgili ayrıntılar için FİLTRE AÇIKLAMALARI bölümüne bakın.

-F filter-desc Olayları varsayılan kümeden hariç tutar. Analiz araçları belirli olayların mevcut olmasına bağlı olabileceğinden, bu seçeneği dikkatli kullanın.

-t timeout İzlemeyi durdurur ve çıktıktan sonra timeout seçeneği sağlanırsa, izlemeyi durdurur ve timeout süresi dolduktan sonra çıkar. Zaman aşımı değerinin sonuna zaman birimlerini belirtmek için us, ms veya s eklenebilir.

-i interval Profil oluşturma zamanlayıcısının tetiklenme aralığını ayarlar (-t ile aynı zaman son eklerini destekler).

-n Profil oluşturma zamanlayıcısını tamamen devre dışı bırakır.

-b buffer-size-mb İzleme ara belleği boyutunu ayarlar.

-r İzlemeyi yapılandırır ve halka ara bellek modunda çalışır durumda bırakır.

-d group group adındaki grubu devre dışı bırakır. Grupların listesi için GRUPLAR bölümüne bakın.

-e group group adındaki grubu etkinleştirir. Grupların listesi için GRUPLAR bölümüne bakın.

--remote[=device-name] Ayrıca belirtilmemişse yerel köprüde (local bridge) veya sağlanan device-name üzerinde izleme yapar.

--type=full|profile|lite|morelite|none Belirtilen türü kullanarak izleme yapar. full varsayılandır; profile ise yalnızca profil oluşturma zamanlayıcısını etkinleştirir ancak zamanlama olaylarını yakından takip etmez. lite ve morelite izleme türleri, uzun süreli, düşük yüklü analizler için tasarlanmıştır ve nispeten uzun süreler boyunca engellenen iş parçacıklarının analiz edilmesine öncelik verir; bunun bedeli ise bir CPU'nun boşta (idle) durumdan çıkmasına neden olan iş parçacıklarına karşı taraflı olmayan bir örnektir.

‘lite’ modları, iş parçacıklarını engelleri kalktıkça tembelce (lazily) ve yalnızca belirlenen bir eşikten daha uzun süre engellenen iş parçacıklarını örnekleyerek çalışır. Ayrıca, tipik profil oluşturma zamanlayıcısı devre dışı bırakılır ve bunun yerine diğer kesmeler sırasında fırsatçı bir şekilde CPU'lar örneklenir. morelite modu, lite moduna göre daha kısıtlayıcı bir typefilter'a sahiptir. none modu ktrace dump gibi davranır.

--stackshot-flags extra-flags stackshot'ları kaydederken sağlanan extra-flags tam sayısını ek bayraklar olarak iletir.

-c command [...] command ile belirtilen komutu çalıştırır ve bu komut çıktığında izlemeyi durdurur. Bu seçenekten sonraki tüm argümanlar komuta iletilir.

--kperf=sampler-name[,sampler-name]@timer-period|timer-frequency|kdebug-filter-desc Verilen örnekleme açıklamasına göre kperf kullanarak örnekleme yapar. Örnekleme açıklamalarının sözdizimi için ÖRNEKLEME AÇIKLAMALARI bölümüne bakın.

Filtre Açıklamaları

Bir filtre açıklaması, hangi olayların izlenmesi gerektiğini belirten sınıf ve alt sınıf belirteçlerinin virgülle ayrılmış bir listesidir. Bir sınıf belirteci ‘C’ ile başlar ve ondalık veya onaltılık (hex) tabanda belirtilen tek bir bayt içerir. Bir alt sınıf belirteci ‘S’ ile başlar ve iki bayt alır. Yüksek bayt sınıfı, düşük bayt ise o sınıfın alt sınıfını temsil eder.

Örneğin, şu filtre açıklaması 1 ve 37 sınıflarını ve sınıf 5'in 33 ve 35 alt sınıflarını etkinleştirir: ‘C1,C0x25,S0x0521,S0x0523’. ‘ALL’ filtre açıklaması tüm sınıflardaki olayları etkinleştirir.

Örnekleme Açıklamaları

Bir örnekleme açıklaması filtre açıklamasına benzer, ancak örneklemeyi yapılandırır. İki bölümden oluşur: bir örnekleyiciler (samplers) bölümü ve @ ile ayrılmış bir tetikleyici (trigger) bölümü. Genel biçim sampler-name[,sampler-name]@ Ns timer-period|timer-frequency|kdebug-filter-desc şeklindedir. Örnekleyicilerin geçerli adları şunlardır: ‘ustack’, ‘kstack’, ‘thinfo’, ‘thsnapshot’, ‘meminfo’, ‘thsched’, ‘thdispatch’, ‘tksnapshot’, ‘sysmem’ ve ‘thinstrscycles’.

Örneğin, kullanıcı yığınlarını (user stacks) her 10 milisaniyede bir örneklemek için ‘ustack@10ms’ kullanın. ‘0xfeedfac0’ olayı her yayıldığında iş parçacığı zamanlama bilgilerini ve sistem belleğini örneklemek için ‘thsched,sysmem@D0xfeedfac0’ kullanın.

Gruplar

syscall-sampling Sistem çağrılarında geri izlemeleri (backtraces) örnekler.

fault-sampling Sayfa hatalarında (page faults) geri izlemeleri örnekler.

graphics Grafik olaylarını dahil eder.

Exit Status

ktrace aracı başarı durumunda 0, bir hata oluştuğunda ise >0 değeriyle çıkar.

Uyarılar

İzleme, init alt komutuyla (veya -r bayrağı ile trace ve artrace alt komutlarıyla) bir kez ilklendirildikten sonra, alan remove alt komutuyla geri kazanılana kadar kullanımda kalır. Bu durum, arka plan teşhis araçlarının izlemeyi kullanmasını engeller.

ktrace