sp_trace_create (Transact-SQL)
適用於：
SQL Server
建立追蹤定義。 新的追蹤處於已停止狀態。
重要
SQL Server 的未來版本將移除此功能。 請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。 請改用擴充事件。
語法
sp_trace_create
[ @traceid = ] traceid OUTPUT
, [ @options = ] options
, [ @tracefile = ] N'tracefile'
[ , [ @maxfilesize = ] maxfilesize ]
[ , [ @stoptime = ] 'stoptime' ]
[ , [ @filecount = ] filecount ]
[ ; ]
引數
[ @traceid = ] traceid OUTPUT
SQL Server 指派給新追蹤的數位。 會忽略任何使用者提供的輸入。 @traceid是 int 類型的 OUTPUT 參數，預設值為 NULL。 用戶會採用 @traceid 值來識別、修改及控制這個預存程式所定義的追蹤。
[ @options = ] 選項
指定追蹤的選項集。 @options為 int，沒有預設值。 您可以藉由指定所挑選的選項總和，來選擇這些選項的組合。 例如，若要同時開啟 選項TRACE_FILE_ROLLOVER和 SHUTDOWN_ON_ERROR，請為 @options 指定 。6
下表列出選項、描述及其值。
| 選項名稱 | 選項值 | 描述 |
|---|---|---|
TRACE_FILE_ROLLOVER |
2 |
指定到達@filecount時，會關閉目前的追蹤檔案，並建立新的檔案。 所有新記錄都會寫入新檔案。 新檔案的名稱與上一個檔案相同，但會附加整數來表示其序列。 例如，如果原始追蹤檔案命名為 ，則下一個追蹤檔案會命名filename.trcfilename_1.trc為 ，下列追蹤檔案為 filename_2.trc，依序顯示。隨著建立更多變換追蹤檔案，附加至檔名的整數值會循序增加。 如果指定此選項而不指定@filecount的值，則 SQL Server 會使用預設值 @filecount （5 MB）。 |
SHUTDOWN_ON_ERROR |
4 |
指定如果因為任何原因而無法將追蹤寫入檔案，SQL Server 就會關閉。 執行安全性稽核追蹤時，此選項很有用。 |
TRACE_PRODUCE_BLACKBOX |
8 |
指定伺服器所產生的最後 5 MB 追蹤資訊記錄會由伺服器儲存。 TRACE_PRODUCE_BLACKBOX 與其他所有選項不相容。 |
[ @tracefile = ] N'tracefile'
指定寫入追蹤的位置和檔案名。 @tracefile為 nvarchar（245），沒有預設值。 @tracefile可以是本機目錄（例如N'C:\MSSQL\Trace\trace.trc'）或共用或路徑的 UNC（例如 ）。N'\\<servername>\<sharename>\<directory>\trace.trc'
SQL Server 會將 .trc 擴展名附加至所有追蹤檔名。 TRACE_FILE_ROLLOVER如果指定選項和@filecount，SQL Server 會在原始追蹤檔案成長到其大小上限時，建立新的追蹤檔案。 新檔案的名稱與源檔相同，但會附加 _n 來表示其序列，開頭為 1。 例如，如果第一個追蹤檔案命名為 filename.trc，則第二個追蹤檔案會命名為 filename_1.trc。
如果您使用 TRACE_FILE_ROLLOVER 選項，建議您不要在原始追蹤檔名中使用底線字元。 如果您使用底線，就會發生下列行為：
SQL Server Profiler 不會自動載入或提示您載入變換檔案（如果已設定其中一個檔案變換選項）。
sys.fn_trace_gettable函式不會載入換用檔案（使用 @number_files 自變數指定時），其中源檔名稱以底線和數值結尾。 （這不適用於檔案變換時自動附加的底線和數位。
注意
作為這兩種行為的因應措施，您可以將檔案重新命名為移除源檔名稱中的底線。 例如，如果源檔名為 my_trace.trc，而換用檔案的名稱為 my_trace_1.trc，您可以在 SQL Server Profiler 中開啟檔案之前，將檔案重新命名為 mytrace.trc 和 mytrace_1.trc 。
使用 選項時TRACE_PRODUCE_BLACKBOX，無法指定@tracefile。
[ @maxfilesize = ] maxfilesize
指定追蹤檔案可成長的大小上限，以 MB 為單位。 @maxfilesize為 bigint，預設值為 5。
如果未指定此參數，TRACE_FILE_ROLLOVER當使用的磁碟空間超過@maxfilesize所指定的數量時，追蹤會停止錄製到檔案。
[ @stoptime = ] 'stoptime'
指定追蹤將停止的日期和時間。 @stoptime為 datetime，預設值為 NULL。 如果 NULL為 ，則追蹤會執行，直到其手動停止，或直到伺服器關閉為止。
如果同時 指定了@stoptime 和 @maxfilesize ，而且 TRACE_FILE_ROLLOVER 未指定，則會在達到指定的停止時間或檔案大小上限時，追蹤頂端。 如果 @stoptime、 @maxfilesize和 TRACE_FILE_ROLLOVER 指定，則追蹤會在指定的停止時間停止，假設追蹤未填滿磁碟驅動器。
[ @filecount = ] 'filecount'
指定要以相同基底檔名維護的最大數目或追蹤檔案。 @filecount為 int，大於 1。 只有在指定 選項時， TRACE_FILE_ROLLOVER 這個參數才有效。 指定@filecount時，SQL Server 會先刪除最舊的追蹤檔案，再開啟新的追蹤檔案，嘗試維護不超過@filecount個追蹤檔案。 SQL Server 會將數位附加至基底檔名，以追蹤追蹤檔案的存留期。
例如，當@tracefile參數指定為 C:\mytrace時，名稱為的檔案比名稱 C:\mytrace_123.trc C:\mytrace_124.trc為的檔案還舊。 如果@filecount設定為 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_addnewqueuexp_trace_setqueuecreateinfoxp_trace_setqueuedestination
sp_trace_create 只會建立追蹤定義。 此預存程式無法用來啟動或變更追蹤。
所有 SQL 追蹤預存程式的參數 （sp_trace_*） 都是嚴格類型。 如果沒有依照引數描述所指定，以正確的輸入參數資料類型來呼叫這些參數，預存程序會傳回錯誤。
針對 sp_trace_create，SQL Server 服務帳戶必須具有 追蹤檔案資料夾的寫入 許可權。 如果 SQL Server 服務帳戶不是追蹤檔案所在電腦上的系統管理員，您必須明確授與 SQL Server 服務帳戶的寫入許可權。
注意
您可以使用系統函式，自動將 建立 sp_trace_create 的追蹤檔案載入數據表 fn_trace_gettable 中。 如需詳細資訊，請參閱 sys.fn_trace_gettable。
如需使用追蹤預存程式的範例，請參閱 建立追蹤。
TRACE_PRODUCE_BLACKBOX 具有下列特性：
這是變換追蹤。 默認 @filecount 為 2，但可以使用 @filecount 選項來覆寫使用者。
默認@maxfilesize與其他追蹤一樣，是5 MB且可以變更。
無法指定檔名。 檔案會儲存為：
N'%SQLDIR%\MSSQL\DATA\blackbox.trc'。追蹤中只會包含下列事件及其資料列：
- RPC 啟動
- 批次啟動
- 例外狀況
- 注意
無法從此追蹤新增或移除事件或數據行。
無法為此追蹤指定篩選。
權限
需要 ALTER TRACE 許可權。