Create Custom Instruments

?

內(nèi)置的工具提供了大量關(guān)于應(yīng)用程序內(nèi)部工作的信息。有時(shí)，您可能希望更緊密地將這些信息與自己的代碼相結(jié)合。例如，不是每次調(diào)用函數(shù)時(shí)收集數(shù)據(jù)，而是在收集數(shù)據(jù)時(shí)設(shè)置條件。或者，您可能希望深入了解自己的代碼，而不是內(nèi)置的工具允許。Built-in instruments provide a great deal of information about the inner workings of your app. Sometimes, though, you may want to tailor this information more closely to your own code. For example, instead of gathering data every time a function is called, you might set conditions on when data is gathered. Alternatively, you might want to dig deeper into your own code than the built-in instruments allow.

IMPORTANT

只要有可能，建議您使用現(xiàn)有的工具，而不是創(chuàng)建新的工具。創(chuàng)建自定義工具是一個(gè)高級(jí)特性。Whenever possible, it is recommended that you use an existing instrument instead of creating a new instrument. Creating custom instruments is an advanced feature.

有關(guān)自定義工具About Custom Instruments

自定義工具使用DTrace的實(shí)施。DTrace動(dòng)態(tài)跟蹤設(shè)備是由太陽(yáng)最初創(chuàng)建和移植到OS X，因?yàn)镈Trace嵌入操作系統(tǒng)內(nèi)核，它允許您訪問(wèn)底層信息的內(nèi)核和用戶在您的計(jì)算機(jī)上運(yùn)行的進(jìn)程。許多內(nèi)置工具已經(jīng)基于DTrace。DTrace本身是一個(gè)復(fù)雜的工具，但工具提供了一個(gè)簡(jiǎn)單的界面，讓您無(wú)需復(fù)雜訪問(wèn)DTrace的力量。Custom instruments use DTrace for their implementation. DTrace is a dynamic tracing facility originally created by Sun and ported to OS?X. Because DTrace taps into the operating system kernel, it allows you to access low-level information about the kernel itself and the user processes running on your computer. Many of the built-in instruments are already based on DTrace. DTrace is itself a complex tool, but Instruments provides a simple interface that lets you access the power of DTrace without the complexity.

DTrace沒(méi)有被移植到iOS，所以它是不可能的設(shè)備上運(yùn)行的iOS創(chuàng)建自定義工具。DTrace has not been ported to iOS, so it is not possible to create custom instruments for devices running iOS.

IMPORTANT

雖然簡(jiǎn)化了創(chuàng)建自定義工具制造商DTrace探測(cè)過(guò)程中，你還應(yīng)該熟悉DTrace和它如何工作之前，創(chuàng)造新的工具。許多更強(qiáng)大的調(diào)試和數(shù)據(jù)采集行動(dòng)需要你寫DTrace腳本。學(xué)習(xí)DTrace和D的腳本語(yǔ)言，看到Solaris動(dòng)態(tài)跟蹤指導(dǎo)，可以從Oracle技術(shù)網(wǎng)。關(guān)于dtrace命令行工具的信息，看到DTrace（1）Mac OS X的手冊(cè)頁(yè)。Although the custom instrument builder simplifies the process of creating DTrace probes, you should still be familiar with DTrace and how it works before creating new instruments. Many of the more powerful debugging and data gathering actions require you to write DTrace scripts. To learn about DTrace and the D scripting language, see the?Solaris Dynamic Tracing Guide, available from the?Oracle Technology Network. For information about the?dtrace?command-line tool, see the?dtrace(1) Mac OS X Manual Page.

NOTE

幾個(gè)蘋果應(yīng)用程序即iTunes，DVD播放器和應(yīng)用程序使用QuickTime防止數(shù)據(jù)采集通過(guò)DTrace（暫時(shí)或永久）為了保護(hù)敏感和受版權(quán)保護(hù)的資料。因此，不運(yùn)行這些應(yīng)用程序執(zhí)行時(shí)，系統(tǒng)數(shù)據(jù)采集。Several Apple apps—namely, iTunes, DVD Player, and apps that use QuickTime—prevent the collection of data through DTrace (either temporarily or permanently) in order to protect sensitive and copyrighted data. Therefore, do not run those apps when performing systemwide data collection.

自定義工具使用DTrace探測(cè)器建造。探針就像一個(gè)傳感器，放置在代碼中。它相當(dāng)于一個(gè)地點(diǎn)或事件，比如一個(gè)函數(shù)的入口點(diǎn)，而DTrace可以綁定。當(dāng)執(zhí)行函數(shù)或事件發(fā)生，相關(guān)的探測(cè)火災(zāi)，和DTrace運(yùn)行任何行動(dòng)與探頭有關(guān)。最簡(jiǎn)單的收集關(guān)于DTrace行動(dòng)操作系統(tǒng)和用戶應(yīng)用程序的行為在那一刻的數(shù)據(jù)。然而，作為操作的一部分運(yùn)行自定義腳本是可能的。腳本讓您使用DTrace功能微調(diào)你收集的資料。Custom instruments are built using DTrace probes. A probe is like a sensor that you place in your code. It corresponds to a location or event, such as a function entry point, to which DTrace can bind. When the function executes or the event is generated, the associated probe fires, and DTrace runs whatever actions are associated with the probe. Most DTrace actions simply collect data about the operating system and user app behavior at that moment. It is possible, however, to run custom scripts as part of an action. Scripts let you use the features of DTrace to fine tune the data you gather.

探針每遇到一次就開火，但每次探針點(diǎn)火時(shí)，與探針相關(guān)的動(dòng)作不需要運(yùn)行。謂詞是一個(gè)條件語(yǔ)句，允許在探測(cè)操作運(yùn)行時(shí)限制它。例如，您可以將探針限制到特定的進(jìn)程或用戶，或者當(dāng)工具中的某個(gè)特定條件為真時(shí)，可以運(yùn)行一個(gè)操作。默認(rèn)情況下，探針沒(méi)有任何謂詞，這意味著每次探針觸發(fā)時(shí)關(guān)聯(lián)操作都會(huì)運(yùn)行。但是，可以將任意數(shù)量的謂詞添加到探針中，并使用運(yùn)算符和運(yùn)算符將它們連接起來(lái)，從而創(chuàng)建復(fù)雜的決策樹。Probes fire each time they are encountered, but the action associated with the probe doesn’t need to run every time the probe fires. A predicate is a conditional statement that allows you to restrict when the probe’s action is run. For example, you can restrict a probe to a specific process or user, or you can run an action when a specific condition in your instrument is true. By default, probes do not have any predicates, meaning that the associated action runs every time the probe fires. You can add any number of predicates to a probe, however, and link them together using?AND?and?OR?operators to create complex decision trees.

一個(gè)定制的儀器由以下幾個(gè)模塊組成：A custom instrument consists of the following blocks:

• 一個(gè)描述塊，包含該儀器的名稱、類別和描述A description block, containing the name, category, and description of the instrument

• 一個(gè)或多個(gè)探針，每個(gè)探針包含其相關(guān)的動(dòng)作和謂詞。One or more probes, each containing its associated actions and predicates

• 一個(gè)數(shù)據(jù)聲明區(qū)域，用于可選地聲明所有探針共享的全局變量。A Data declaration area, for optionally declaring global variables shared by all probes

• 一個(gè)開始腳本，它可以選擇性地初始化全局變量并執(zhí)行該工具所需的啟動(dòng)任務(wù)。A Begin script, which optionally initializes global variables and performs startup tasks required by the instrument

• 一個(gè)結(jié)束腳本，可選執(zhí)行最終的清理操作。An End script, which optionally performs final cleanup actions

自定義儀器必須至少有一個(gè)具有相關(guān)動(dòng)作的探針。類似地，自定義工具應(yīng)該有一個(gè)適當(dāng)?shù)拿Q和描述，將其標(biāo)識(shí)給儀器用戶。工具在庫(kù)調(diào)色板中顯示此描述性信息。提供良好的信息使人們更容易記住儀器的用途和使用方法。A custom instrument must have at least one probe with associated actions. Similarly, a custom instrument should have an appropriate name and description that identifies it to Instruments users. Instruments displays this descriptive information in the Library palette. Providing good information makes it easier to remember what the instrument does and how it should be used.

探針不需要有全局?jǐn)?shù)據(jù)聲明，也不需要開始和結(jié)束腳本。當(dāng)您想在探針之間共享數(shù)據(jù)或?yàn)閮x器提供某種初始配置時(shí)，這些元素用于高級(jí)儀器設(shè)計(jì)。在編寫自定義腳本時(shí)描述了數(shù)據(jù)、開始和結(jié)束塊的創(chuàng)建。Probes are not required to have a global Data declaration, or Begin and End scripts. These elements are used in advanced instrument design when you want to share data among probes or provide some sort of initial configuration for your instrument. The creation of Data, Begin, and End blocks is described in?Write Custom Scripts.

創(chuàng)建自定義工具Create a Custom Instrument

創(chuàng)建一個(gè)自定義的DTrace工具，選擇工具>建立新的儀器。這個(gè)命令顯示儀表配置對(duì)話框，顯示在圖25-1。使用此表指定您的儀器信息，包括任何探針和自定義腳本。To create a custom DTrace instrument, choose Instrument > Build New Instrument. This command displays the instrument configuration dialog, shown in?Figure 25-1. You use this sheet to specify your instrument information, including any probes and custom scripts.

Figure 25-1The instrument configuration dialog

至少，為您創(chuàng)建的每個(gè)自定義工具提供以下信息：At a minimum, provide the following information for every custom instrument you create:

• 名稱。與庫(kù)中的自定義工具相關(guān)聯(lián)的名稱。Name. The name associated with your custom instrument in the library.

• 類別.你的樂(lè)器出現(xiàn)在圖書館的類別。可以指定現(xiàn)有類別的名稱，例如內(nèi)存或創(chuàng)建自己的類。Category. The category in which your instrument appears in the library. You can specify the name of an existing category—such as Memory—or create your own.

• 描述。在庫(kù)調(diào)色板和工具的工具提示中使用的工具描述。Description. The instrument description, used in both the Library palette and in the instrument’s tooltip.

• 探針供應(yīng)商。探針類型和應(yīng)該何時(shí)點(diǎn)火的細(xì)節(jié)。通常，這涉及指定探針應(yīng)用的方法或函數(shù)。參見指定探測(cè)提供程序。Probe provider. The probe type and the details of when it should fire. Typically, this involves specifying the method or function to which the probe applies. See?Specify the Probe Provider.

• 探頭的作用。當(dāng)探針觸發(fā)時(shí)要記錄的數(shù)據(jù)或要執(zhí)行的腳本。Probe action. The data to record or the script to execute when your probe fires; see?Add Actions to a Probe.

儀器應(yīng)該至少包含一個(gè)探頭，并且可能包含不止一個(gè)探頭。探針定義由提供者信息、謂詞信息和動(dòng)作組成。所有探測(cè)必須至少指定提供者信息，并且?guī)缀跛刑綔y(cè)都定義某種行為。探針定義的謂詞部分是可選的，但可以是一個(gè)非常有用的工具，用于將工具集中在正確的數(shù)據(jù)上。An instrument should contain at least one probe and may contain more than one. The probe definition consists of the provider information, predicate information, and action. All probes must specify the provider information at a minimum, and nearly all probes define some sort of action. The predicate portion of a probe definition is optional but can be a very useful tool for focusing your instrument on the correct data.

添加和刪除探針Add and Delete Probes

每臺(tái)新儀器都配有一個(gè)探頭，可以配置。若要添加更多的探針，請(qǐng)單擊工具配置對(duì)話框底部的Add按鈕（+）。參見圖25-2。Every new instrument comes with one probe that you can configure. To add more probes, click the Add button (+) at the bottom of the instrument configuration dialog. See?Figure 25-2.

要從工具中刪除探針，請(qǐng)單擊探針選擇它，然后單擊工具配置對(duì)話框底部的“刪除”按鈕（-）。To remove a probe from your instrument, click the probe to select it and click the Remove button (-) at the bottom of the instrument configuration dialog.

Figure 25-2在儀器配置對(duì)話框中添加或刪除探針Adding or removing probes in the instrument configuration dialog

添加探針時(shí)，為探針提供描述性名稱是個(gè)好主意。默認(rèn)情況下，儀器將每個(gè)探針?lè)峙湟粋€(gè)順序編號(hào)的名稱，如探針1和探針2。When adding a probe, it is a good idea to provide a descriptive name for the probe. By default, Instruments assigns each probe a sequentially numbered name, such as Probe 1 and Probe 2.

指定探針提供程序Specify the Probe Provider

若要指定觸發(fā)探針的位置點(diǎn)或事件，請(qǐng)將適當(dāng)?shù)奶峁┱吲c探針關(guān)聯(lián)起來(lái)。供應(yīng)商是內(nèi)核模塊，代理DTrace，提供必要?jiǎng)?chuàng)建探針的儀器。您不需要知道提供者如何操作來(lái)創(chuàng)建一個(gè)工具，但是您需要知道每個(gè)提供者的基本功能。表25-1列出的應(yīng)用程序和工具可用于自定義工具支持提供者。供應(yīng)商列在儀器配置對(duì)話框中顯示的名稱，和DTrace提供者列用于DTrace腳本提供者的名稱。To specify the location point or event that triggers a probe, associate the appropriate provider with the probe. Providers are kernel modules that act as agents for DTrace, providing the instrumentation necessary to create probes. You do not need to know how providers operate to create an instrument, but you do need to know the basic capabilities of each provider.?Table 25-1?lists the providers that are supported by the Instruments app and available for use in your custom instruments. The Provider column lists the name displayed in the instrument configuration dialog, and the DTrace provider column lists the actual name of the provider used in the corresponding DTrace script.

Table 25-1DTrace 供應(yīng)商providers

Provider

DTrace provider

Description

User Process	pid	The probe fires on entry (or return) of the specified function in your code. You must provide the function name and the name of the library that contains it.
Objective-C	objc	The probe fires on entry (or return) of the specified Objective-C method. You must provide the method name and the class to which it belongs.
System Call	syscall	The probe fires on entry (or return) of the specified system library function.
DTrace	DTrace	The probe fires when DTrace itself enters a Begin, End, or Error block.
Kernel Function Boundaries	fbt	The probe fires on entry (or return) of the specified kernel function in your code. You must provide the kernel function name and the name of the library that contains it.
Mach	mach_trap	The probe fires on entry (or return) of the specified Mach library function.
Profile	profile	The probe fires regularly at the specified time interval on each core of the machine. Profile probes can fire with a granularity that ranges from microseconds to days.
Tick	tick	The probe fires at periodic intervals on one core of the machine. Tick probes can fire with a granularity that ranges from microseconds to days. You might use this provider to perform periodic tasks that are not required to be on a particular core.
I/O	io	The probe fires at the start of the specified kernel routine. For a list of functions monitored by this probe, use the?dtrace -l?command from Terminal to get a list of probe points. You can then search this list for probes monitored by the?io?module.
Kernel Process	proc	The probe fires on the initiation of one of several kernel-level routines. For a list of functions monitored by this probe, use the?dtrace -l?command from Terminal to get a list of probe points. You can then search this list for functions monitored by the?proc?module.
User-Level Synchronization	plockstat	The probe fires at one of several synchronization points. You can use this provider to monitor mutex and read-write lock events.
CPU Scheduling	sched	The probe fires when CPU scheduling events occur.

在為探針選擇提供程序之后，指定探針?biāo)璧男畔ⅰ＠?#xff0c;對(duì)于某些函數(shù)級(jí)探測(cè)，提供者可能需要函數(shù)或方法名，以及您的代碼模塊或包含模塊的類。其他提供者可能只需要您從彈出菜單中選擇適當(dāng)?shù)氖录fter selecting the provider for your probe, specify the information needed by the probe. For example, for some function-level probes, providers may need function or method names, along with your code module or else the class containing your module. Other providers may only need you to select appropriate events from a pop-up menu.

在配置了一個(gè)探針之后，您可以向它添加額外的謂詞（以確定它應(yīng)該何時(shí)觸發(fā)），或者您可以繼續(xù)定義該探針的操作。After you have configured a probe, you can add additional predicates to it (to determine when it should fire) or you can go ahead and define the action for that probe.

向探針添加謂詞Add Predicates to a Probe

謂詞使您能夠控制探針動(dòng)作何時(shí)由儀器執(zhí)行。您可以使用謂詞來(lái)防止工具在不需要時(shí)收集數(shù)據(jù)，或者認(rèn)為數(shù)據(jù)可能是錯(cuò)誤的。例如，如果代碼只有在堆棧達(dá)到一定深度時(shí)才會(huì)顯示異常行為，則使用謂詞指定最小目標(biāo)堆棧深度。每當(dāng)探針觸發(fā)時(shí)，儀器都會(huì)對(duì)相關(guān)謂詞進(jìn)行評(píng)估。只有當(dāng)他們?cè)u(píng)估為true是DTrace執(zhí)行相關(guān)行動(dòng)。Predicates give you control over when a probe’s action is executed by Instruments. You can use predicates to prevent Instruments from gathering data when you don’t want it or think the data might be erroneous. For example, if your code exhibits unusual behavior only when the stack reaches a certain depth, use a predicate to specify the minimum target stack depth. Every time a probe fires, Instruments evaluates the associated predicates. Only if they evaluate to true does DTrace perform the associated actions.

向探針添加一個(gè)謂詞To add a predicate to a probe

在探測(cè)條件下單擊Add按鈕（+）。Click the Add button (+) in the probe conditions.

選擇謂詞類型。Select the type of predicate.

定義謂詞值。Define the predicate values.

可以使用探針或謂詞的Add按鈕（+）添加后續(xù)謂詞。若要?jiǎng)h除謂詞，請(qǐng)單擊謂詞旁邊的“刪除”按鈕（-）。You can add subsequent predicates using the Add buttons (+) of either the probe or the predicate. To remove a predicate, click the Remove button (-) next to the predicate.

儀器根據(jù)它們出現(xiàn)的順序從上到下對(duì)謂詞進(jìn)行求值。若要重新排列謂詞，請(qǐng)單擊謂詞行，并將其拖到表中的新位置。可以使用和或運(yùn)算符鏈接謂詞，但不能將它們分組以創(chuàng)建嵌套條件塊。相反，要謹(jǐn)慎地排列謂詞，以確保檢查適當(dāng)?shù)臈l件。Instruments evaluates predicates from top to bottom in the order in which they appear. To rearrange predicates, click the predicate’s row and drag it to a new location in the table. You can link predicates using?AND?and?OR?operators, but you cannot group them to create nested condition blocks. Instead, order your predicates carefully to ensure that the appropriate conditions are checked.

使用謂詞行中的第一個(gè)彈出菜單選擇要檢查的數(shù)據(jù)作為條件的一部分。表25-2列出DTrace定義的標(biāo)準(zhǔn)變量，您可以使用您的謂詞或腳本代碼。可變列列出的名字出現(xiàn)在儀器的配置面板，和“DTrace變量”列對(duì)應(yīng)的DTrace腳本中使用的變量的名稱。除了測(cè)試標(biāo)準(zhǔn)變量之外，還可以通過(guò)在謂詞字段中指定自定義變量類型來(lái)測(cè)試腳本代碼中的自定義變量和常量。Use the first pop-up menu in a predicate row to choose the data to inspect as part of the condition.?Table 25-2?lists the standard variables defined by DTrace that you can use in your predicates or script code. The Variable column lists the name as it appears in the instrument configuration panel, and the “DTrace variable” column lists the actual name of the variable used in corresponding DTrace scripts. In addition to testing the standard variables, you can test against custom variables and constants from your script code by specifying the Custom variable type in the predicate field.

Table 25-2DTrace variables

Variable

DTrace variable

Description

Caller	caller	The value of the current thread’s program counter just before entering the probe. This variable contains an integer value.
Chip	chip	The identifier for the physical chip executing the probe. This is a 0-based integer indicating the index of the current core. For example, a four-core machine has cores 0 through 3.
CPU	cpu	The identifier for the CPU executing the probe. This is a 0-based integer indicating the index of the current core. For example, a four-core machine has cores 0 through 3.
Current Working Directory	cwd	The current working directory of the current process. This variable contains a string value.
Last Error #	errno	The error value returned by the last system call made on the current thread. This variable contains an integer value.
Executable	execname	The name that was passed to?exec?to execute the current process. This variable contains a string value.
User ID	uid	The real user ID of the current process. This variable contains an integer value.
Group ID	gid	The real group ID of the current process. This variable contains an integer value.
Process ID	pid	The process ID of the current process. This variable contains an integer value.
Parent ID	ppid	The process ID of the parent process. This variable contains an integer value.
Interrupt Priority Level	ipl	The interrupt priority level on the current CPU at the time the probe fired. This variable contains an unsigned integer value.
Function	probefunc	The function name part of the probe’s description. This variable contains a string value.
Module	probemod	The module name part of the probe’s description. This variable contains a string value.
Name	probename	The name portion of the probe’s description. This variable contains a string value.
Provider	probeprov	The provider name part of the probe’s description. This variable contains a string value.
Root Directory	root	The root directory of the process. This variable contains a string value.
Stack Depth	stackdepth	The stack frame depth of the current thread at the time the thread fired. This variable contains an unsigned integer value.
User Stack Depth	ustackdepth	The stack frame depth for user frames (omitting kernel mode frames) of the current thread at the time the thread fired. This variable contains an unsigned integer value.
Relative Timestamp	timestamp	The current value of the system’s timestamp counter, in nanoseconds. Because this counter increments from an arbitrary point in the past, use it to calculate only relative time differences. This variable contains an unsigned 64-bit integer value.
Virtual Timestamp	vtimestamp	The amount of time the current thread has been running, in nanoseconds. This value does not include time spent in DTrace predicates and actions. This variable contains an unsigned 64-bit integer value.
Timestamp	walltimestamp/1000	The current number of nanoseconds that have elapsed since 00:00 Universal coordinated Time, January 1, 1970. This variable contains an unsigned 64-bit integer value.
arg0?through?arg9	arg0?through?arg9	The first 10 arguments to the probe, represented as raw 64-bit integers. If fewer than ten arguments were passed to the probe, the remaining variables contain the value 0.
Custom	The name of your variable	Use this option to specify a variable or constant from one of your scripts.

除了指定要檢查的變量外，還必須指定比較運(yùn)算符（等于、不等于等）和用于與變量進(jìn)行比較的值。In addition to specifying a variable to inspect, you must specify a comparison operator (equals, does not equal, etc.) and a value to use for comparison against the variable.

向探針添加操作Add Actions to a Probe

當(dāng)一個(gè)探測(cè)點(diǎn)定義你的樂(lè)器打探頭的謂詞條件評(píng)估為true，DTrace運(yùn)行與探針相關(guān)的動(dòng)作。您使用探針的操作來(lái)收集數(shù)據(jù)或執(zhí)行附加處理。例如，如果您的探針監(jiān)視特定的函數(shù)或方法，則可以將該函數(shù)的調(diào)用方和任何堆棧跟蹤信息返回到儀表。如果您想要稍微高級(jí)一些的操作，您可以使用腳本變量來(lái)跟蹤調(diào)用函數(shù)的次數(shù)，并報(bào)告該信息。如果你想要一個(gè)更高級(jí)的動(dòng)作，你可以寫一個(gè)腳本，使用內(nèi)核級(jí)DTrace功能確定的函數(shù)使用鎖的狀態(tài)。在后一種情況下，腳本代碼也可能返回鎖的當(dāng)前所有者（如果有的話），以幫助您確定代碼不同線程之間的交互。When a probe point defined by your instrument is hit and the probe’s predicate conditions evaluate to true, DTrace runs the actions associated with the probe. You use your probe’s actions to gather data or to perform additional processing. For example, if your probe monitors a specific function or method, you could have it return the caller of that function and any stack trace information to Instruments. If you wanted a slightly more advanced action, you could use a script variable to track the number of times the function was called and report that information as well. And if you wanted an even more advanced action, you could write a script that uses kernel-level DTrace functions to determine the status of a lock used by your function. In this latter case, your script code might also return the current owner of the lock (if there is one) to help you determine the interactions among your code’s different threads.

圖25-3展示儀器配置對(duì)話框讓你指定你的探索行動(dòng)的部分。腳本部分只包含一個(gè)文本字段，供您鍵入腳本代碼。（儀器不驗(yàn)證你的代碼之前通過(guò)DTrace，那么仔細(xì)，檢查你的代碼）底部包含指定你想要回到工具DTrace數(shù)據(jù)控件。你可以使用彈出式菜單配置內(nèi)置DTrace變量你想回來(lái)。當(dāng)?shù)谝粋€(gè)彈出菜單設(shè)置為記錄在儀器中時(shí)，您可以選擇從第二個(gè)彈出菜單中選擇自定義，并返回其中一個(gè)腳本變量。Figure 25-3?shows the portion of the instrument configuration dialog where you specify your probe’s actions. The script portion simply contains a text field for you to type in your script code. (Instruments does not validate your code before passing it to DTrace, so check your code carefully.) The bottom section contains controls for specifying the data you want DTrace to return to Instruments. You can use the pop-up menus to configure the built-in DTrace variables you want to return. When the first pop-up menu is set to Record in Instruments, you can optionally choose Custom from the second pop-up menu and return one of your script variables.

Figure 25-3配置探測(cè)的動(dòng)作Configuring a probe’s action

當(dāng)您配置工具返回一個(gè)自定義變量時(shí)，儀器要求您提供以下信息：When you configure your instrument to return a custom variable, Instruments asks you to provide the following information:

• 包含數(shù)據(jù)的腳本變量The script variable containing the data

• 應(yīng)用于儀表接口中變量的名稱。The name to apply to the variable in your instrument interface

• 變量的類型The type of the variable

您的探針?lè)祷氐絻x器的任何數(shù)據(jù)都被收集并顯示在儀器的詳細(xì)窗格中。細(xì)節(jié)窗格顯示所有數(shù)據(jù)變量，無(wú)論類型如何。如果堆棧跟蹤信息可用于特定的探針，則儀器將在儀表板的擴(kuò)展詳細(xì)區(qū)域顯示該信息。此外，儀器自動(dòng)查找由工具返回的整數(shù)數(shù)據(jù)類型，并將這些類型添加到您的工具可以在軌道窗格中顯示的統(tǒng)計(jì)列表中。Any data your probe returned to Instruments is collected and displayed in your instrument’s detail pane. The detail pane displays all data variables regardless of type. If stack trace information is available for a specific probe, Instruments displays that information in the extended detail area of the inspector pane for your instrument. In addition, Instruments automatically looks for integer data types returned by your instrument and adds those types to the list of statistics your instrument can display in the track pane.

因?yàn)镈Trace腳本運(yùn)行在內(nèi)核空間和儀器的應(yīng)用程序運(yùn)行在用戶空間中，如果要返回一個(gè)自定義的指針的值基于腳本的變量工具，您必須創(chuàng)建一個(gè)緩沖區(qū)來(lái)保存變量的數(shù)據(jù)。最簡(jiǎn)單的方法來(lái)創(chuàng)建一個(gè)緩沖區(qū)使用制作或找到DTrace copyinstr函數(shù)子程序。子程序的copyinstr函數(shù)接受指向字符串并返回字符串中的一種形式，你可以返回到儀器的內(nèi)容。同樣，在制作子程序接受一個(gè)指針和大小的值，并返回一個(gè)緩沖區(qū)的數(shù)據(jù)，你可以稍后格式轉(zhuǎn)化為字符串使用的系列關(guān)鍵詞。這兩個(gè)子程序的DTrace環(huán)境的一部分，可以從你的行動(dòng)定義的任何部分使用探針。例如，返回C風(fēng)格字符串指針的字符串，你只需把變量名與copyinstr函數(shù)子程序，如圖25-4所示。Because DTrace scripts run in kernel space and the Instruments app runs in user space, if you want to return the value of a custom pointer-based script variable to Instruments, you must create a buffer to hold the variable’s data. The simplest way to create a buffer is to use the?copyin?or?copyinstr?subroutines found in DTrace. The?copyinstr?subroutine takes a pointer to a C string and returns the contents of the string in a form you can return to Instruments. Similarly, the?copyin?subroutine takes a pointer and size value and returns a buffer to the data, which you can later format into a string using the?stringof?keyword. Both of these subroutines are part of the DTrace environment and can be used from any part of your probe’s action definition. For example, to return the string from a C-style string pointer, you simply wrap the variable name with the?copyinstr?subroutine, as shown in?Figure 25-4.

Figure 25-4Returning a string pointer

IMPORTANT

儀器自動(dòng)將內(nèi)置變量（如通過(guò)函數(shù)參數(shù)arg0 Arg9）與調(diào)用copyinstr函數(shù)如果變量類型設(shè)置為字符串。然而，工具不會(huì)自動(dòng)包裝腳本的自定義變量。您負(fù)責(zé)確保自定義變量中的數(shù)據(jù)與該變量指定的類型實(shí)際匹配。Instruments automatically wraps built-in variables (such as the?arg0?through?arg9?function arguments) with a call to?copyinstr?if the variable type is set to?string. Instruments does not automatically wrap a script’s custom variables, however. You are responsible for ensuring that the data in a custom variable actually matches the type specified for that variable.

在一系列的內(nèi)置變量支持的工具，見表25-2。有關(guān)腳本和腳本變量的更多信息，請(qǐng)參見編寫自定義腳本。在DTrace子程序的更多信息，包括制作與copyinstr函數(shù)子程序，看到Solaris動(dòng)態(tài)跟蹤指導(dǎo)，可以從Oracle技術(shù)網(wǎng)。For a list of the built-in variables supported by Instruments, see?Table 25-2. For more information on scripts and script variables, see?Write Custom Scripts. For more information on DTrace subroutines, including the?copyin?and?copyinstr?subroutines, see the?Solaris Dynamic Tracing Guide, available from the?Oracle Technology Network.

Write Custom Scripts

你寫的DTrace腳本使用的腳本語(yǔ)言，其語(yǔ)法是從C語(yǔ)言編程的一個(gè)大的子集。D語(yǔ)言將C語(yǔ)言的編程結(jié)構(gòu)與一組特殊的函數(shù)和變量結(jié)合起來(lái)，幫助您跟蹤應(yīng)用程序中的信息。You write DTrace scripts using the D scripting language, whose syntax is derived from a large subset of the C programming language. The D language combines the programming constructs of the C language with a special set of functions and variables to help you trace information in your app.

下面的小節(jié)描述了在自定義工具中使用腳本的常用方法。這部分沒(méi)有寫DTrace腳本提供一個(gè)全面的概述的語(yǔ)言或過(guò)程。有關(guān)腳本和d語(yǔ)言的信息，請(qǐng)參見從Oracle技術(shù)網(wǎng)絡(luò)中獲得的Solaris動(dòng)態(tài)跟蹤指南。The following sections describe common ways to use scripts in your custom instruments. These sections do not provide a comprehensive overview of the D language or the process for writing DTrace scripts. For information about scripting and the D language, see the?Solaris Dynamic Tracing Guide, available from the?Oracle Technology Network.

編寫開始和結(jié)束腳本W(wǎng)rite Begin and End Scripts

如果你想做更多的返回信息的內(nèi)置變量工具DTrace每當(dāng)你行動(dòng)的火災(zāi)，你需要編寫自定義腳本。腳本直接與在內(nèi)核級(jí)DTrace，提供有關(guān)核和活動(dòng)過(guò)程的底層信息。大多數(shù)儀器使用腳本來(lái)收集信息不易從DTrace。還可以使用腳本在返回原始數(shù)據(jù)之前對(duì)原始數(shù)據(jù)進(jìn)行操作。例如，您可以使用腳本將數(shù)據(jù)值標(biāo)準(zhǔn)化為特定的范圍，如果您希望更容易地將該值與您的工具的跟蹤窗格中的其他值進(jìn)行圖形比較。If you want to do more than return the information in DTrace’s built-in variables to Instruments whenever your action fires, you need to write custom scripts. Scripts interact directly with DTrace at the kernel level, providing access to low-level information about the kernel and the active process. Most instruments use scripts to gather information not readily available from DTrace. You can also use scripts to manipulate raw data before returning it to Instruments. For example, you can use a script to normalize a data value to a specific range if you want to make it easier to compare that value graphically with other values in your instrument’s track pane.

在儀器儀表配置，自定義對(duì)話框提供了幾個(gè)地方，你可以寫DTrace腳本：In Instruments, the custom instrument configuration dialog provides several areas where you can write DTrace scripts:

• 數(shù)據(jù)部分包含要在工具中使用的所有全局變量的定義。The Data section contains definitions of any global variables you want to use in your instrument.

• 開始部分包含工具的任何初始化代碼。The Begin section contains any initialization code for your instrument.

• 每個(gè)探針都包含腳本代碼作為動(dòng)作的一部分。Each probe contains script code as part of its action.

• 結(jié)束部分包含用于工具的任何清理代碼。The End section contains any cleanup code for your instrument.

所有腳本部分都是可選的。如果您的工具不需要它們，則不需要初始化腳本或清除腳本。但是，如果您的工具在其數(shù)據(jù)部分定義了全局變量，建議您還提供一個(gè)初始化腳本，將這些變量設(shè)置為已知值。d語(yǔ)言不允許您在全局變量聲明中內(nèi)聯(lián)值，因此必須將這些賦值放在開始部分。例如，一個(gè)簡(jiǎn)單的數(shù)據(jù)段可能由一個(gè)變量聲明組成，如以下：All script sections are optional. You are not required to have initialization scripts or cleanup scripts if your instrument does not need them. If your instrument defines global variables in its Data section, however, it is recommended that you also provide an initialization script to set those variables to a known value. The D language does not allow you to assign values inline with your global variable declarations, so you must put those assignments in your Begin section. For example, a simple Data section might consist of a single variable declaration, such as the following:

int myVariable;

相應(yīng)的開始部分將包含以下代碼來(lái)初始化該變量：The corresponding Begin section would then contain the following code to initialize that variable:

myVariable = 0;

如果你的行動(dòng)改變相應(yīng)的探針myVariable的值，你可以使用你的頭端部分的格式和打印出變量的最終值。If your corresponding probe actions change the value of?myVariable, you can use the End section of your probe to format and print out the final value of the variable.

大多數(shù)腳本代碼很可能與單個(gè)探針相關(guān)聯(lián)。每個(gè)探針都有一個(gè)與其動(dòng)作相關(guān)聯(lián)的腳本。執(zhí)行的時(shí)候一個(gè)探頭的動(dòng)作，DTrace運(yùn)行腳本代碼然后再返回所請(qǐng)求的任何數(shù)據(jù)恢復(fù)工具。因?yàn)閷?shù)據(jù)傳遞給儀器需要將數(shù)據(jù)從內(nèi)核空間復(fù)制到工具應(yīng)用程序空間，所以您應(yīng)該通過(guò)在“儀表配置”對(duì)話框中記錄“以下數(shù)據(jù)”部分中配置適當(dāng)?shù)臈l目，將數(shù)據(jù)返回給儀器。從腳本代碼手動(dòng)返回的變量可能無(wú)法正確返回到儀表。Most of your script code is likely to be associated with individual probes. Each probe can have a script associated with its action. When it comes time to execute a probe’s action, DTrace runs your script code first and then returns any requested data back to Instruments. Because passing data back to Instruments involves copying data from the kernel space back to the Instruments app space, you should always pass data back to Instruments by configuring the appropriate entries in the “Record the following data” section of the instrument configuration dialog. Variables returned manually from your script code may not be returned correctly to Instruments.

從自定義腳本訪問(wèn)內(nèi)核數(shù)據(jù)Access Kernel Data from Custom Scripts

因?yàn)镈Trace腳本執(zhí)行系統(tǒng)內(nèi)核，他們可以訪問(wèn)內(nèi)核符號(hào)。看看全球的核心變量和數(shù)據(jù)在你的DTrace腳本自定義儀器結(jié)構(gòu)，在與反引號(hào)字符的變量名（`）。的反引號(hào)字符告訴DTrace尋找指定的變量的當(dāng)前腳本之外。Because DTrace scripts execute inside the system kernel, they have access to kernel symbols. To look at a global kernel variable and data structure from your custom instrument in your DTrace scripts, precede the name of the variable with the backquote character (`). The backquote character tells DTrace to look for the specified variable outside of the current script.

上市25-1說(shuō)明動(dòng)作腳本檢索當(dāng)前的負(fù)載信息從avenrun核心變量，使用變量來(lái)計(jì)算一分鐘內(nèi)的平均負(fù)載的系統(tǒng)。如果使用配置文件提供程序創(chuàng)建一個(gè)探針，您可以讓此腳本定期收集負(fù)載數(shù)據(jù)，然后在儀器中繪制該信息。Listing 25-1?shows a sample action script that retrieves the current load information from the?avenrun?kernel variable and uses that variable to calculate a one-minute average load of the system. If you create a probe using the Profile provider, you can have this script gather load data periodically and then graph that information in Instruments.

Listing 25-1從DTrace腳本訪問(wèn)內(nèi)核變量Accessing kernel variables from a DTrace script

this->load1a = `avenrun[0]/1000;

this->load1b = ((`avenrun[0] % 1000) * 100) / 1000;

this->load1 = (100 * this->load1a) + this->load1b;

范圍變量的合理Scope Variables Appropriately

DTrace腳本有一個(gè)基本上平的結(jié)構(gòu)，由于缺乏流程控制語(yǔ)句和欲望保持探頭的執(zhí)行時(shí)間降到最低。就是說(shuō)，你可以在DTrace腳本變量范圍的不同取決于你的需要。表25-3列表范圍級(jí)別變量和使用在每個(gè)級(jí)別的變量的語(yǔ)法。DTrace scripts have an essentially flat structure, due to a lack of flow control statements and the desire to keep probe execution time to a minimum. That said, you can scope the variables in DTrace scripts to different levels depending on your need.?Table 25-3?lists the scoping levels for variables and the syntax for using variables at each level.

Table 25-3Variable scope in DTrace scripts

Scope

Syntax example

Description

Global	myGlobal = 1;	Global variables are identified by the variable name. All probe actions on all system threads have access to variables in this space.
Thread	self->myThreadVar = 1;	Thread-local variables are dereferenced from the?self?keyword. All probe actions running on the same thread have access to variables in this space. You might use this scope to collect data over the course of several runs of a probe’s action on the current thread.
Probe	this->myLocalVar = 1;	Probe-local variables are dereferenced using the?this?keyword. Only the current running probe has access to variables in this space. Typically, you use this scope to define temporary variables that you want the kernel to clean up when the current action ends.

找到腳本錯(cuò)誤Find Script Errors

如果一個(gè)自定義工具腳本代碼包含一個(gè)錯(cuò)誤，儀器會(huì)顯示一條錯(cuò)誤信息在編譯時(shí)跟蹤窗格DTrace腳本。當(dāng)您在跟蹤文檔中單擊記錄按鈕，但在實(shí)際開始跟蹤之前，儀器會(huì)報(bào)告錯(cuò)誤。在錯(cuò)誤消息氣泡內(nèi)部是一個(gè)編輯按鈕。單擊此按鈕打開儀器配置對(duì)話框，該對(duì)話框現(xiàn)在標(biāo)識(shí)帶有錯(cuò)誤的探針。If the script code for one of your custom instruments contains an error, Instruments displays an error message in the track pane when DTrace compiles the script. Instruments reports the error after you click the Record button in your trace document but before tracing actually begins. Inside the error message bubble is an Edit button. Clicking this button opens the instrument configuration dialog, which now identifies the probe with the error.

出口和進(jìn)口DTrace腳本Export and Import DTrace Scripts

雖然儀器提供了收集跟蹤數(shù)據(jù)接口方便，有時(shí)它是收集跟蹤數(shù)據(jù)，直接使用DTrace更方便。如果你是系統(tǒng)管理員或是例如編寫自動(dòng)化測(cè)試腳本，，你可能喜歡DTrace命令行界面發(fā)射過(guò)程和數(shù)據(jù)收集。使用命令行工具需要你寫你自己的DTrace腳本，可耗費(fèi)的時(shí)間，可能會(huì)導(dǎo)致錯(cuò)誤。如果你已經(jīng)有了一個(gè)跟蹤文件與一個(gè)或多個(gè)DTrace為基礎(chǔ)的工具，你可以使用工具軟件生成DTrace腳本提供相同的行為在你的跟蹤文件的工具。Although Instruments provides a convenient interface for gathering trace data, sometimes it is more convenient to gather trace data directly using DTrace. If you are a system administrator or are writing automated test scripts, for example, you might prefer the DTrace command-line interface to launch a process and gather the data. Using the command-line tool requires you to write your own DTrace scripts, which can be time consuming and can lead to errors. If you already have a trace document with one or more DTrace-based instruments, you can use the Instruments app to generate a DTrace script that provides the same behavior as the instruments in your trace document.

儀器支持出口的DTrace腳本只對(duì)其中所有的儀器都是基于DTrace文件。這意味著，您的文檔可以包含自定義工具和少數(shù)內(nèi)置的工具，如在圖書館調(diào)色板中的文件系統(tǒng)相關(guān)的核心數(shù)據(jù)工具。Instruments supports exporting DTrace scripts only for documents in which all of the instruments are based on DTrace. This means that your document can include custom instruments and a handful of the built-in instruments, such as the file system-related and Core Data instruments in the Library palette.

出口DTrace腳本To export a DTrace script

選擇跟蹤文檔。Select the trace document.

Choose File > DTrace Script Export.

Enter a name for the DTrace script.

Select a location for the DTrace script.

Click Save.

DTrace腳本導(dǎo)出命令地方腳本命令你的儀器在一個(gè)文本文件，然后你可以通過(guò)DTrace命令行工具使用-選擇。例如，如果你出口腳本命名myinstrumentsscript。D、運(yùn)行終端使用下面的命令：The DTrace Script Export command places the script commands for your instruments in a text file that you can then pass to the?dtrace?command-line tool using the?-soption. For example, if you export a script named?MyInstrumentsScript.d, run it from Terminal using the following command:

sudo dtrace -s MyInstrumentsScript.d

NOTE

你必須有超級(jí)用戶權(quán)限運(yùn)行在大多數(shù)情況下，DTrace，這就是為什么sudo命令用于在前面的例子中運(yùn)行DTrace。You must have superuser privileges to run?dtrace?in most instances, which is why the?sudo?command is used to run?dtrace?in the preceding example.

從工具導(dǎo)出腳本（而不是手動(dòng)編寫腳本）的另一個(gè)好處是，在運(yùn)行腳本之后，您可以將結(jié)果數(shù)據(jù)導(dǎo)入到工具中并在那里進(jìn)行檢查。出口從儀器腳本打印開始標(biāo)記（與文本dtrace_output_begin）在DTrace輸出開始。收集的數(shù)據(jù)，簡(jiǎn)單地復(fù)制所有的DTrace輸出（包括開始標(biāo)記）從終端并粘貼到一個(gè)文本文件，或者將輸出重定向從DTrace工具直接到文件。在儀器導(dǎo)入數(shù)據(jù)，選擇跟蹤文件，你生成的原始劇本，并選擇文件> DTrace數(shù)據(jù)導(dǎo)入。Another advantage of exporting your scripts from Instruments (as opposed to writing them manually) is that after running the script, you can import the resulting data back into Instruments and review it there. Scripts exported from Instruments print a start marker (with the text?dtrace_output_begin) at the beginning of the DTrace output. To gather the data, simply copy all of the DTrace output (including the start marker) from Terminal and paste it into a text file, or just redirect the output from the?dtrace?tool directly to a file. To import the data in Instruments, select the trace document from which you generated the original script, and choose File > DTrace Data Import.

轉(zhuǎn)載于:https://www.cnblogs.com/zyingn/p/Create_Custom_Instruments.html

總結(jié)

以上是生活随笔為你收集整理的Create Custom Instruments的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。