共用方式為


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.trcmytrace_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 引數的描述中,新增了原始追蹤檔的名稱應避免使用底線字元的建議事項。