sp_trace_create (Transact-SQL)

發行項
09/02/2015

建立追蹤定義。新追蹤會處於已停止狀態。

重要事項
未來的 Microsoft SQL Server 版本將移除這項功能。請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。請改用擴充事件。

主題連結圖示 Transact-SQL 語法慣例

語法

sp_trace_create [ @traceid = ] trace_id OUTPUT 
          , [ @options = ] option_value  
          , [ @tracefile = ] 'trace_file' 
     [ , [ @maxfilesize = ] max_file_size ]
     [ , [ @stoptime = ] 'stop_time' ]
     [ , [ @filecount = ] 'max_rollover_files' ]

引數

[ @traceid= ] trace_id
這是 Microsoft SQL Server 指派給新追蹤的號碼。系統會忽略任何使用者所提供的輸入。 trace_id 是 int，預設值是 NULL。使用者會利用這個 trace_id 值來識別、修改和控制這個預存程序所定義的追蹤。

[ @options= ] option_value
指定追蹤所設定的選項。 option_value 是 int，沒有預設值。使用者可以指定所取用選項的總值，來選擇這些選項的組合。例如，若要開啟 TRACE_FILE_ROLLOVER 和 SHUTDOWN_ON_ERROR 選項，請在 option_value 中指定 6。

下表列出選項、描述及其值。

選項名稱	選項值	描述
TRACE_FILE_ROLLOVER	2	指定在到達 max_file_size 時，關閉目前的追蹤檔，建立一個新檔案。所有新記錄都會寫入新檔案中。新檔案與先前的檔案同名，但會附加一個整數來表示順序。例如，如果原始追蹤檔的名稱是 filename.trc，下一個追蹤檔的名稱就是 filename_1.trc，再下一個追蹤檔的名稱就是 filename_2.trc，依此類推。在建立換用追蹤檔時，檔案名稱所附加的整數值也會循序增加。如果指定這個選項，但沒有指定 max_file_size 值，SQL Server 就會使用 max_file_size 的預設值 (5 MB)。
SHUTDOWN_ON_ERROR	4	指定追蹤因故無法寫入檔案時，SQL Server 便關機。當執行安全性稽核追蹤時，這個選項非常有用。
TRACE_PRODUCE_BLACKBOX	8	指定伺服器將所產生最後 5 MB 的追蹤資訊記錄儲存起來。 TRACE_PRODUCE_BLACKBOX 與所有其他選項不相容。

TRACE_FILE_ROLLOVER

指定在到達 max_file_size 時，關閉目前的追蹤檔，建立一個新檔案。所有新記錄都會寫入新檔案中。新檔案與先前的檔案同名，但會附加一個整數來表示順序。例如，如果原始追蹤檔的名稱是 filename.trc，下一個追蹤檔的名稱就是 filename_1.trc，再下一個追蹤檔的名稱就是 filename_2.trc，依此類推。

在建立換用追蹤檔時，檔案名稱所附加的整數值也會循序增加。

如果指定這個選項，但沒有指定 max_file_size 值，SQL Server 就會使用 max_file_size 的預設值 (5 MB)。

SHUTDOWN_ON_ERROR

指定追蹤因故無法寫入檔案時，SQL Server 便關機。當執行安全性稽核追蹤時，這個選項非常有用。

TRACE_PRODUCE_BLACKBOX

指定伺服器將所產生最後 5 MB 的追蹤資訊記錄儲存起來。 TRACE_PRODUCE_BLACKBOX 與所有其他選項不相容。

[ @tracefile= ] 'trace_file'
指定將寫入追蹤的位置和檔案名稱。 trace_file 是 nvarchar(245)，沒有預設值。 trace_file 可以是本機目錄 (如 N 'C:\MSSQL\Trace\trace.trc')，也可以是共用或路徑的 UNC (N'\\伺服器名稱\共用名稱\目錄\trace.trc')。

SQL Server 會在所有追蹤檔名稱中，附加 .trc 副檔名。如果指定了 TRACE_FILE_ROLLOVER 選項和 max_file_size，當原始追蹤檔成長到其大小上限時，SQL Server 會建立一個新的追蹤檔。新檔案的名稱與原始檔案相同，但此時會從 1 開始，附加 _n 來表示它的順序。例如，如果第一個追蹤檔的名稱是 filename.trc，第二個追蹤檔的名稱就是 filename_1.trc。

如果使用了 TRACE_FILE_ROLLOVER 選項，建議您不要在原始追蹤檔名稱中使用底線字元。若您使用底線字元，便會發生下列行為：
- SQL Server Profiler 不會自動載入或提示您載入換用檔案 (如果已經設定任何這些檔案換用選項)。
- 對於名稱以底線加上數值結尾的原始檔案，當使用 number_files 引數指定時，fn_trace_gettable函數不會載入換用檔案 (若為檔案換用時自動附加的底線及數值，則不在此列)。
[!附註]

為了因應以上兩種行為，您可以重新命名檔案，移除原始檔案名稱中的底線。例如，如果原始檔案名稱是 my_trace.trc 而換用檔案名稱是 my_trace_1.trc，您即可先將檔案分別重新命名為 mytrace.trc 和 mytrace_1.trc，再從 SQL Server Profiler 中開啟檔案。

當使用 TRACE_PRODUCE_BLACKBOX 選項時，無法指定 trace_file。
[ @maxfilesize= ] max_file_size
指定追蹤檔所能成長的大小上限 (以 MB 為單位)。 max_file_size 是 bigint，預設值是 5。

如果指定這個參數時，並未設定 TRACE_FILE_ROLLOVER 選項，當所用的磁碟空間超出 max_file_size 所指定的大小時，追蹤就會停止記錄到檔案中。
[ @stoptime= ] 'stop_time'
指定追蹤的停止日期和時間。 stop_time 是 datetime，預設值是 NULL。如果是 NULL，追蹤就會執行到手動停止或伺服器關機為止。

如果同時指定了 stop_time 和 max_file_size，且沒有指定 TRACE_FILE_ROLLOVER，當到達指定的停止時間或檔案大小上限時，追蹤便會停止。如果指定了 stop_time、max_file_size 和 TRACE_FILE_ROLLOVER，假設追蹤並沒有填滿磁碟，便會在指定的停止時間停止。
[ @filecount= ] 'max_rollover_files'
指定利用相同的基礎檔案名稱來維護的最大追蹤檔數目。 max_rollover_files 是 int，大於 1。只有在指定了 TRACE_FILE_ROLLOVER 選項時，這個參數才有效。當指定 max_rollover_files 時，SQL Server 會在開啟新追蹤檔之前先刪除最舊的追蹤檔，嘗試使維護的追蹤檔數目不會超出 max_rollover_files。 SQL Server 會在基礎檔案名稱上附加數字來追蹤這些追蹤檔的存在時間。

例如，當 trace_file 參數指定為 "c:\mytrace" 時，名稱為 "c:\mytrace_123.trc" 的檔案比名稱為 "c:\mytrace_124.trc" 的檔案舊。如果 max_rollover_files 設為 2，SQL Server 便會先刪除 "c:\mytrace_123.trc" 檔，再建立追蹤檔 "c:\mytrace_125.trc"。

請注意，SQL Server 只會嘗試刪除各個檔案一次，且無法刪除有其他程序在使用的檔案。因此，如果您在進行追蹤時，有另一個應用程式在使用追蹤檔，SQL Server 會將這些追蹤檔保留在檔案系統中。

傳回碼值

下表描述在預存程序完成之後，使用者可能得到的代碼值。

傳回碼	描述
0	沒有錯誤。
1	未知的錯誤。
10	無效的選項。當指定的選項不相容時，便傳回這個代碼。
12	未建立檔案。
13	記憶體用完。當沒有足夠的記憶體可以執行指定的動作時，便傳回這個代碼。
14	無效停止時間。當指定的停止時間已發生過時，便傳回這個代碼。
15	無效的參數。當使用者提供不相容的參數時，便傳回這個代碼。

備註

sp_trace_create 是一個 SQL Server 預存程序，它會執行先前舊版 SQL Server 提供的 xp_trace_* 擴充預存程序所執行的許多動作。請用 sp_trace_create 來取代下列各項：

xp_trace_addnewqueue
xp_trace_setqueuecreateinfo
xp_trace_setqueuedestination

sp_trace_create 只會建立追蹤定義。您無法利用這個預存程序來啟動或變更追蹤。

所有 SQL 追蹤預存程序 (sp_trace_xx) 的參數都具備嚴格的類型。如果沒有依照引數描述所指定，以正確的輸入參數資料類型來呼叫這些參數，預存程序會傳回錯誤。

對於 sp_trace_create，SQL Server 服務帳戶必須有追蹤檔資料夾的寫入權限。如果 SQL Server 服務帳戶不是追蹤檔所在電腦的管理員，您就必須將寫入權限明確授與 SQL Server 服務帳戶。

[!附註]

您可以利用 fn_trace_gettable 系統函數，將 sp_trace_create 所建立的追蹤檔自動載入資料表中。如需有關如何使用這個系統函數的詳細資訊，請參閱＜sys.fn_trace_gettable (Transact-SQL)＞。

如需使用追蹤預存程序的範例，請參閱＜建立追蹤 (Transact-SQL)＞。

TRACE_PRODUCE_BLACKBOX 具有下列特性：

這是換用追蹤。 file_count 預設值為 2，但使用者可以利用 filecount 選項加以覆寫。
file_size 預設值與其他追蹤一樣是 5 MB，且可以變更。
不可指定任何檔名。檔案會儲存為：N'%SQLDIR%\MSSQL\DATA\blackbox.trc'
追蹤中只會包含下列事件及其資料行：
- RPC starting
- Batch starting
- 例外狀況
- Attention
無法從這項追蹤加入或移除事件或資料行。
無法針對這項追蹤指定篩選器。