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
  Microsoft SQL Server 2005 によって新しいトレースに割り当てられる番号です。ユーザーの入力はすべて無視されます。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_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 2005 のストアド プロシージャで、以前のバージョンの 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)」を参照してください。

権限

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

戻り値

次の表は、このストアド プロシージャの完了時に返されるコード値の説明です。

戻り値	説明
0	エラーなし。
1	不明なエラー。
10	オプションが無効。指定したオプションが一致しない場合に返されます。
12	ファイルが作成されていない。
13	メモリ不足。指定した操作を実行するために十分なメモリがない場合に返されます。
14	停止時刻が無効。指定した停止時刻が既に過ぎている場合に返されます。
15	パラメータが無効。ユーザーが一致しないパラメータを指定した場合に返されます。

参照

関連項目

sp_trace_generateevent (Transact-SQL)
sp_trace_setevent (Transact-SQL)
sp_trace_setfilter (Transact-SQL)
sp_trace_setstatus (Transact-SQL)

その他の技術情報

SQL トレースの概要

ヘルプおよび情報

SQL Server 2005 の参考資料の入手