sp_trace_create (Transact-SQL)

  • [アーティクル]

適用対象:SQL Server

トレース定義を作成します。 新しいトレースは停止状態になります。

重要

この機能は、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_idMicrosoft 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 となります。

追加のロールオーバー トレース ファイルが作成されると、ファイル名に追加される整数値が順番に増加します。

SQL Serverは、max_file_sizeの値を指定せずにこのオプションを指定した場合、既定値の 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' など) または共有またはパス (N'\\Servername Sharename\\Directory\trace.trc' への UNC) のいずれかです。

SQL Serverは、すべてのトレース ファイル名に .trc 拡張子を追加します。 TRACE_FILE_ROLLOVER オプションとmax_file_sizeを指定SQL Server、元のトレース ファイルが最大サイズまで大きくなると、新しいトレース ファイルが作成されます。 新しいファイルの名前は元のファイルと同じですが、シーケンスを示す _n が 1 から始まります。 たとえば、最初のトレース ファイルの名前が filename.trc の場合、2 番目のトレース ファイルの名前は filename_1.trc になります。

TRACE_FILE_ROLLOVER オプションを使用する場合、元のトレース ファイル名にアンダースコア文字を使用しないことをお勧めします。 アンダースコアを使用すると、次の動作が発生します。

  • SQL Server Profilerは、ロールオーバー ファイルを自動的に読み込んだり、ロールオーバー ファイルの読み込みを求めたりすることはありません (これらのファイル ロールオーバー オプションのいずれかが構成されている場合)。

  • fn_trace_gettable関数は、元のファイル名がアンダースコアと数値で終わるロールオーバー ファイル ( number_files 引数を使用して指定した場合) は読み込まれません。 ただし、この状況は、ファイルがロールオーバーされるときに自動的に追加されたアンダースコアおよび数値については該当しません。

注意

このような動作に対処するには、元のファイル名のアンダースコアを削除してトレース ファイルの名前を変更します。 たとえば、元のファイルに my_trace.trc という名前が付けられ、ロールオーバー ファイルの名前が my_trace_1.trc である場合は、SQL Server Profilerでファイルを開く前に、ファイルの名前を mytrace.trc と mytrace_1.trc に変更できます。

TRACE_PRODUCE_BLACKBOX オプションを使用する場合、trace_fileを指定できません。

[ @maxfilesize = ] max_file_size トレース ファイルを拡張できる最大サイズ (MB) を 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 に設定されている場合、トレース ファイル "c:\mytrace_125.trc" を作成する前に、SQL Serverはファイル "c:\mytrace_123.trc" を削除します。

SQL Serverは各ファイルの削除を 1 回だけ試行し、別のプロセスで使用されているファイルを削除できないことに注意してください。 そのため、トレースの実行中に別のアプリケーションがトレース ファイルを操作している場合、SQL Serverこれらのトレース ファイルはファイル システムに残る可能性があります。

リターン コードの値

次の表は、このストアド プロシージャの完了時に返されるコード値を示しています。

リターン コード 説明
0 エラーなし。
1 不明なエラー。
10 無効なオプションです。 指定したオプションが一致しない場合に返されます。
12 ファイルが作成されていない。
13 メモリが不足しています。 指定したアクションを実行するのに十分なメモリがない場合に返されます。
14 停止時間が無効です。 指定された停止時間が既に発生したときに返されます。
15 パラメーターが無効。 ユーザーが互換性のないパラメーターを指定したときに返されます。

解説

sp_trace_createは、以前のバージョンのSQL Serverで使用できるxp_trace_* 拡張ストアド プロシージャによって以前に実行されたアクションの多くを実行するSQL Server ストアド プロシージャです。 次の代わりに 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 サービス アカウントに書き込みアクセス許可を明示的に付与する必要があります。

注意

sp_trace_createを使用して作成されたトレース ファイルは、 fn_trace_gettable システム関数を使用してテーブルに自動的 に 読み込むことができます。 このシステム関数の使用方法については、「 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

    • バッチ開始

    • Exception

    • 注意

  • イベントまたは列は、このトレースに追加または削除できません。

  • このトレースにはフィルターを指定できません。

アクセス許可

ユーザーには ALTER TRACE 権限が必要です。

参照

sp_trace_generateevent (Transact-SQL)
sp_trace_setevent (Transact-SQL)
sp_trace_setfilter (Transact-SQL)
sp_trace_setstatus (Transact-SQL)
SQL トレース (SQL Trace)