sp_trace_create (Transact-SQL)

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

重要

この機能は、将来のバージョンの Microsoft SQL Server では削除される予定です。新しい開発作業では、この機能の使用を避け、現在この機能を使用しているアプリケーションは修正するようにしてください。代わりに拡張イベントを使用します。

適用対象: SQL Server (SQL Server 2008 から現在のバージョンまで)

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 の 2 つのオプションをオンにするには、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 では、元のトレース ファイルが指定の最大サイズに達したときに、新しいトレース ファイルが作成されます。 新しいファイルには元のファイルと同じ名前が付けられますが、その順番を示すため _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 である場合、ファイル名を 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_125.trc" というファイルが作成されるときには、先に "c:\mytrace_123.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

• このトレースからイベントまたは列を追加または削除することはできません。

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

権限

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

関連項目

参照

sp_trace_generateevent (Transact-SQL)

sp_trace_setevent (Transact-SQL)

sp_trace_setfilter (Transact-SQL)

sp_trace_setstatus (Transact-SQL)

概念

SQL トレース