共用方式為

  • 發行項

sp_trace_create (Transact-SQL)

建立追蹤定義。新追蹤會在已停止的狀態中。

主題連結圖示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
    這是 MicrosoftSQL 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 與所有其他選項不相容。

  • [ @tracefile= ] 'trace_file'
    指定將寫入追蹤的位置和檔案名稱。trace_file 是 nvarchar(245)，沒有預設值。trace_file 可以是本機目錄 (如 N 'C:\MSSQL\Trace\trace.trc')，也可以是共用或路徑的 UNC (N'\\Servername\Sharename\Directory\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 所建立的追蹤檔自動載入資料表中。如需有關如何使用這個系統函數的詳細資訊，請參閱＜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

    • Exception

    • Attention

  • 無法從這項追蹤加入或移除事件或資料行。

  • 無法針對這項追蹤指定篩選器。

權限

使用者必須有 ALTER TRACE 權限。

變更記錄

更新的內容

在 @tracefile 引數的描述中，新增了原始追蹤檔的名稱應避免使用底線字元的建議事項。