sp_trace_create (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 の 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 以下に保たれます。また、基本ファイル名に番号が付加され、トレース ファイルの世代が追跡されます。

  たとえば、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 Trace ストアド プロシージャ (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 権限が必要です。

変更履歴

関連項目

参照

その他の技術情報