Create Custom Instruments

?

內置的工具提供了大量關于應用程序內部工作的信息。有時，您可能希望更緊密地將這些信息與自己的代碼相結合。例如，不是每次調用函數時收集數據，而是在收集數據時設置條件。或者，您可能希望深入了解自己的代碼，而不是內置的工具允許。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

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

有關自定義工具About Custom Instruments

自定義工具使用DTrace的實施。DTrace動態跟蹤設備是由太陽最初創建和移植到OS X，因為DTrace嵌入操作系統內核，它允許您訪問底層信息的內核和用戶在您的計算機上運行的進程。許多內置工具已經基于DTrace。DTrace本身是一個復雜的工具，但工具提供了一個簡單的界面，讓您無需復雜訪問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沒有被移植到iOS，所以它是不可能的設備上運行的iOS創建自定義工具。DTrace has not been ported to iOS, so it is not possible to create custom instruments for devices running iOS.

IMPORTANT

雖然簡化了創建自定義工具制造商DTrace探測過程中，你還應該熟悉DTrace和它如何工作之前，創造新的工具。許多更強大的調試和數據采集行動需要你寫DTrace腳本。學習DTrace和D的腳本語言，看到Solaris動態跟蹤指導，可以從Oracle技術網。關于dtrace命令行工具的信息，看到DTrace（1）Mac OS X的手冊頁。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

幾個蘋果應用程序即iTunes，DVD播放器和應用程序使用QuickTime防止數據采集通過DTrace（暫時或永久）為了保護敏感和受版權保護的資料。因此，不運行這些應用程序執行時，系統數據采集。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探測器建造。探針就像一個傳感器，放置在代碼中。它相當于一個地點或事件，比如一個函數的入口點，而DTrace可以綁定。當執行函數或事件發生，相關的探測火災，和DTrace運行任何行動與探頭有關。最簡單的收集關于DTrace行動操作系統和用戶應用程序的行為在那一刻的數據。然而，作為操作的一部分運行自定義腳本是可能的。腳本讓您使用DTrace功能微調你收集的資料。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.

探針每遇到一次就開火，但每次探針點火時，與探針相關的動作不需要運行。謂詞是一個條件語句，允許在探測操作運行時限制它。例如，您可以將探針限制到特定的進程或用戶，或者當工具中的某個特定條件為真時，可以運行一個操作。默認情況下，探針沒有任何謂詞，這意味著每次探針觸發時關聯操作都會運行。但是，可以將任意數量的謂詞添加到探針中，并使用運算符和運算符將它們連接起來，從而創建復雜的決策樹。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.

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

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

• 一個或多個探針，每個探針包含其相關的動作和謂詞。One or more probes, each containing its associated actions and predicates

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

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

• 一個結束腳本，可選執行最終的清理操作。An End script, which optionally performs final cleanup actions

自定義儀器必須至少有一個具有相關動作的探針。類似地，自定義工具應該有一個適當的名稱和描述，將其標識給儀器用戶。工具在庫調色板中顯示此描述性信息。提供良好的信息使人們更容易記住儀器的用途和使用方法。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.

探針不需要有全局數據聲明，也不需要開始和結束腳本。當您想在探針之間共享數據或為儀器提供某種初始配置時，這些元素用于高級儀器設計。在編寫自定義腳本時描述了數據、開始和結束塊的創建。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.

創建自定義工具Create a Custom Instrument

創建一個自定義的DTrace工具，選擇工具>建立新的儀器。這個命令顯示儀表配置對話框，顯示在圖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

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

• 名稱。與庫中的自定義工具相關聯的名稱。Name. The name associated with your custom instrument in the library.

• 類別.你的樂器出現在圖書館的類別。可以指定現有類別的名稱，例如內存或創建自己的類。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.

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

• 探針供應商。探針類型和應該何時點火的細節。通常，這涉及指定探針應用的方法或函數。參見指定探測提供程序。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.

• 探頭的作用。當探針觸發時要記錄的數據或要執行的腳本。Probe action. The data to record or the script to execute when your probe fires; see?Add Actions to a Probe.

儀器應該至少包含一個探頭，并且可能包含不止一個探頭。探針定義由提供者信息、謂詞信息和動作組成。所有探測必須至少指定提供者信息，并且幾乎所有探測都定義某種行為。探針定義的謂詞部分是可選的，但可以是一個非常有用的工具，用于將工具集中在正確的數據上。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

每臺新儀器都配有一個探頭，可以配置。若要添加更多的探針，請單擊工具配置對話框底部的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.

要從工具中刪除探針，請單擊探針選擇它，然后單擊工具配置對話框底部的“刪除”按鈕（-）。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在儀器配置對話框中添加或刪除探針Adding or removing probes in the instrument configuration dialog

添加探針時，為探針提供描述性名稱是個好主意。默認情況下，儀器將每個探針分配一個順序編號的名稱，如探針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

若要指定觸發探針的位置點或事件，請將適當的提供者與探針關聯起來。供應商是內核模塊，代理DTrace，提供必要創建探針的儀器。您不需要知道提供者如何操作來創建一個工具，但是您需要知道每個提供者的基本功能。表25-1列出的應用程序和工具可用于自定義工具支持提供者。供應商列在儀器配置對話框中顯示的名稱，和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 供應商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.

在為探針選擇提供程序之后，指定探針所需的信息。例如，對于某些函數級探測，提供者可能需要函數或方法名，以及您的代碼模塊或包含模塊的類。其他提供者可能只需要您從彈出菜單中選擇適當的事件。After 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.

在配置了一個探針之后，您可以向它添加額外的謂詞（以確定它應該何時觸發），或者您可以繼續定義該探針的操作。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

謂詞使您能夠控制探針動作何時由儀器執行。您可以使用謂詞來防止工具在不需要時收集數據，或者認為數據可能是錯誤的。例如，如果代碼只有在堆棧達到一定深度時才會顯示異常行為，則使用謂詞指定最小目標堆棧深度。每當探針觸發時，儀器都會對相關謂詞進行評估。只有當他們評估為true是DTrace執行相關行動。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.

向探針添加一個謂詞To add a predicate to a probe

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

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

定義謂詞值。Define the predicate values.

可以使用探針或謂詞的Add按鈕（+）添加后續謂詞。若要刪除謂詞，請單擊謂詞旁邊的“刪除”按鈕（-）。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.

儀器根據它們出現的順序從上到下對謂詞進行求值。若要重新排列謂詞，請單擊謂詞行，并將其拖到表中的新位置。可以使用和或運算符鏈接謂詞，但不能將它們分組以創建嵌套條件塊。相反，要謹慎地排列謂詞，以確保檢查適當的條件。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.

使用謂詞行中的第一個彈出菜單選擇要檢查的數據作為條件的一部分。表25-2列出DTrace定義的標準變量，您可以使用您的謂詞或腳本代碼。可變列列出的名字出現在儀器的配置面板，和“DTrace變量”列對應的DTrace腳本中使用的變量的名稱。除了測試標準變量之外，還可以通過在謂詞字段中指定自定義變量類型來測試腳本代碼中的自定義變量和常量。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.

除了指定要檢查的變量外，還必須指定比較運算符（等于、不等于等）和用于與變量進行比較的值。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

當一個探測點定義你的樂器打探頭的謂詞條件評估為true，DTrace運行與探針相關的動作。您使用探針的操作來收集數據或執行附加處理。例如，如果您的探針監視特定的函數或方法，則可以將該函數的調用方和任何堆棧跟蹤信息返回到儀表。如果您想要稍微高級一些的操作，您可以使用腳本變量來跟蹤調用函數的次數，并報告該信息。如果你想要一個更高級的動作，你可以寫一個腳本，使用內核級DTrace功能確定的函數使用鎖的狀態。在后一種情況下，腳本代碼也可能返回鎖的當前所有者（如果有的話），以幫助您確定代碼不同線程之間的交互。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展示儀器配置對話框讓你指定你的探索行動的部分。腳本部分只包含一個文本字段，供您鍵入腳本代碼。（儀器不驗證你的代碼之前通過DTrace，那么仔細，檢查你的代碼）底部包含指定你想要回到工具DTrace數據控件。你可以使用彈出式菜單配置內置DTrace變量你想回來。當第一個彈出菜單設置為記錄在儀器中時，您可以選擇從第二個彈出菜單中選擇自定義，并返回其中一個腳本變量。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配置探測的動作Configuring a probe’s action

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

• 包含數據的腳本變量The script variable containing the data

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

• 變量的類型The type of the variable

您的探針返回到儀器的任何數據都被收集并顯示在儀器的詳細窗格中。細節窗格顯示所有數據變量，無論類型如何。如果堆棧跟蹤信息可用于特定的探針，則儀器將在儀表板的擴展詳細區域顯示該信息。此外，儀器自動查找由工具返回的整數數據類型，并將這些類型添加到您的工具可以在軌道窗格中顯示的統計列表中。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.

因為DTrace腳本運行在內核空間和儀器的應用程序運行在用戶空間中，如果要返回一個自定義的指針的值基于腳本的變量工具，您必須創建一個緩沖區來保存變量的數據。最簡單的方法來創建一個緩沖區使用制作或找到DTrace copyinstr函數子程序。子程序的copyinstr函數接受指向字符串并返回字符串中的一種形式，你可以返回到儀器的內容。同樣，在制作子程序接受一個指針和大小的值，并返回一個緩沖區的數據，你可以稍后格式轉化為字符串使用的系列關鍵詞。這兩個子程序的DTrace環境的一部分，可以從你的行動定義的任何部分使用探針。例如，返回C風格字符串指針的字符串，你只需把變量名與copyinstr函數子程序，如圖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

儀器自動將內置變量（如通過函數參數arg0 Arg9）與調用copyinstr函數如果變量類型設置為字符串。然而，工具不會自動包裝腳本的自定義變量。您負責確保自定義變量中的數據與該變量指定的類型實際匹配。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.

在一系列的內置變量支持的工具，見表25-2。有關腳本和腳本變量的更多信息，請參見編寫自定義腳本。在DTrace子程序的更多信息，包括制作與copyinstr函數子程序，看到Solaris動態跟蹤指導，可以從Oracle技術網。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腳本使用的腳本語言，其語法是從C語言編程的一個大的子集。D語言將C語言的編程結構與一組特殊的函數和變量結合起來，幫助您跟蹤應用程序中的信息。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.

下面的小節描述了在自定義工具中使用腳本的常用方法。這部分沒有寫DTrace腳本提供一個全面的概述的語言或過程。有關腳本和d語言的信息，請參見從Oracle技術網絡中獲得的Solaris動態跟蹤指南。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.

編寫開始和結束腳本Write Begin and End Scripts

如果你想做更多的返回信息的內置變量工具DTrace每當你行動的火災，你需要編寫自定義腳本。腳本直接與在內核級DTrace，提供有關核和活動過程的底層信息。大多數儀器使用腳本來收集信息不易從DTrace。還可以使用腳本在返回原始數據之前對原始數據進行操作。例如，您可以使用腳本將數據值標準化為特定的范圍，如果您希望更容易地將該值與您的工具的跟蹤窗格中的其他值進行圖形比較。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.

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

• 數據部分包含要在工具中使用的所有全局變量的定義。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.

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

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

所有腳本部分都是可選的。如果您的工具不需要它們，則不需要初始化腳本或清除腳本。但是，如果您的工具在其數據部分定義了全局變量，建議您還提供一個初始化腳本，將這些變量設置為已知值。d語言不允許您在全局變量聲明中內聯值，因此必須將這些賦值放在開始部分。例如，一個簡單的數據段可能由一個變量聲明組成，如以下：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;

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

myVariable = 0;

如果你的行動改變相應的探針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.

大多數腳本代碼很可能與單個探針相關聯。每個探針都有一個與其動作相關聯的腳本。執行的時候一個探頭的動作，DTrace運行腳本代碼然后再返回所請求的任何數據恢復工具。因為將數據傳遞給儀器需要將數據從內核空間復制到工具應用程序空間，所以您應該通過在“儀表配置”對話框中記錄“以下數據”部分中配置適當的條目，將數據返回給儀器。從腳本代碼手動返回的變量可能無法正確返回到儀表。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.

從自定義腳本訪問內核數據Access Kernel Data from Custom Scripts

因為DTrace腳本執行系統內核，他們可以訪問內核符號。看看全球的核心變量和數據在你的DTrace腳本自定義儀器結構，在與反引號字符的變量名（`）。的反引號字符告訴DTrace尋找指定的變量的當前腳本之外。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說明動作腳本檢索當前的負載信息從avenrun核心變量，使用變量來計算一分鐘內的平均負載的系統。如果使用配置文件提供程序創建一個探針，您可以讓此腳本定期收集負載數據，然后在儀器中繪制該信息。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腳本訪問內核變量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腳本有一個基本上平的結構，由于缺乏流程控制語句和欲望保持探頭的執行時間降到最低。就是說，你可以在DTrace腳本變量范圍的不同取決于你的需要。表25-3列表范圍級別變量和使用在每個級別的變量的語法。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.

找到腳本錯誤Find Script Errors

如果一個自定義工具腳本代碼包含一個錯誤，儀器會顯示一條錯誤信息在編譯時跟蹤窗格DTrace腳本。當您在跟蹤文檔中單擊記錄按鈕，但在實際開始跟蹤之前，儀器會報告錯誤。在錯誤消息氣泡內部是一個編輯按鈕。單擊此按鈕打開儀器配置對話框，該對話框現在標識帶有錯誤的探針。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.

出口和進口DTrace腳本Export and Import DTrace Scripts

雖然儀器提供了收集跟蹤數據接口方便，有時它是收集跟蹤數據，直接使用DTrace更方便。如果你是系統管理員或是例如編寫自動化測試腳本，，你可能喜歡DTrace命令行界面發射過程和數據收集。使用命令行工具需要你寫你自己的DTrace腳本，可耗費的時間，可能會導致錯誤。如果你已經有了一個跟蹤文件與一個或多個DTrace為基礎的工具，你可以使用工具軟件生成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腳本只對其中所有的儀器都是基于DTrace文件。這意味著，您的文檔可以包含自定義工具和少數內置的工具，如在圖書館調色板中的文件系統相關的核心數據工具。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腳本導出命令地方腳本命令你的儀器在一個文本文件，然后你可以通過DTrace命令行工具使用-選擇。例如，如果你出口腳本命名myinstrumentsscript。D、運行終端使用下面的命令：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

你必須有超級用戶權限運行在大多數情況下，DTrace，這就是為什么sudo命令用于在前面的例子中運行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.

從工具導出腳本（而不是手動編寫腳本）的另一個好處是，在運行腳本之后，您可以將結果數據導入到工具中并在那里進行檢查。出口從儀器腳本打印開始標記（與文本dtrace_output_begin）在DTrace輸出開始。收集的數據，簡單地復制所有的DTrace輸出（包括開始標記）從終端并粘貼到一個文本文件，或者將輸出重定向從DTrace工具直接到文件。在儀器導入數據，選擇跟蹤文件，你生成的原始劇本，并選擇文件> DTrace數據導入。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.

轉載于:https://www.cnblogs.com/zyingn/p/Create_Custom_Instruments.html

總結

以上是生活随笔為你收集整理的Create Custom Instruments的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。