sp_trace_create (Transact-SQL)

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

重要
この機能は、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_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 ではそれらのトレース ファイルがファイル システムに残されることがあります。

リターン コード値

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

説明

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 トレース