sp_trace_create (Transact-SQL)

適用対象: SQL Server

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

Transact-SQL 構文表記規則

構文

sp_trace_create
    [ @traceid = ] traceid OUTPUT
    , [ @options = ] options
    , [ @tracefile = ] N'tracefile'
    [ , [ @maxfilesize = ] maxfilesize ]
    [ , [ @stoptime = ] 'stoptime' ]
    [ , [ @filecount = ] filecount ]
[ ; ]

引数

[ @traceid = ] traceid OUTPUT

新しいトレースに SQL Server によって割り当てられた番号。 ユーザー指定の入力は無視されます。 @traceid は、 int 型の OUTPUT パラメーターで、既定値は NULL です。 ユーザーは、 @traceid 値を使用して、このストアド プロシージャによって定義されたトレースを識別、変更、および制御します。

[ @options = ] options

トレースのオプション セットを指定します。 @options は int で、既定値はありません。 選択したオプションの合計値を指定することで、これらのオプションの組み合わせを選択できます。 たとえば、オプションTRACE_FILE_ROLLOVERとSHUTDOWN_ON_ERRORの両方をオンにするには、@optionsの6を指定します。

次の表に、オプション、説明、およびその値を示します。

[ @tracefile = ] N'tracefile'

トレースの書き込み先となる場所とファイル名を指定します。 @tracefile は既定値なしで nvarchar(245) です。 @tracefile には、ローカル ディレクトリ ( N'C:\MSSQL\Trace\trace.trc' など) または共有またはパスへの UNC ( N'\\<servername>\<sharename>\<directory>\trace.trc' など) を指定できます。

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

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

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

• sys.fn_trace_gettable関数では、元のファイル名がアンダースコアと数値で終わるロールオーバー ファイル (@number_files引数を使用して指定した場合) は読み込まれません。 (これは、ファイルのロール オーバー時に自動的に追加されるアンダースコアと数字には適用されません)。

TRACE_PRODUCE_BLACKBOX オプションを使用する場合、@tracefileを指定することはできません。

[ @maxfilesize = ] maxfilesize

トレース ファイルの最大サイズを MB 単位で指定します。 @maxfilesize は bigint で、既定値は 5 です。

このパラメーターを TRACE_FILE_ROLLOVER オプションなしで指定した場合、使用されるディスク領域が @maxfilesizeで指定された量を超えると、トレースはファイルへの記録を停止します。

[ @stoptime = ] 'stoptime'

トレースを停止する日時を指定します。 @stoptime は datetime で、既定値は NULL です。 NULL場合、トレースは手動で停止するか、サーバーがシャットダウンするまで実行されます。

@stoptimeと@maxfilesizeの両方が指定されていて、TRACE_FILE_ROLLOVERが指定されていない場合は、指定した停止時間または最大ファイル サイズに達したときにトレースが上位になります。 @stoptime、@maxfilesize、およびTRACE_FILE_ROLLOVERが指定されている場合、トレースがドライブを満たしていないと仮定して、トレースは指定された停止時間に停止します。

[ @filecount = ] 'filecount'

同じ基本ファイル名で保持するトレース ファイルの最大数を指定します。 @filecountは 1 より大きい int です。 このパラメーターは、 TRACE_FILE_ROLLOVER オプションが指定されている場合にのみ有効です。 @filecountが指定されている場合、SQL Server は、新しいトレース ファイルを開く前に最も古いトレース ファイルを削除することで、@filecountトレース ファイル以下を維持しようとします。 SQL Server では、基本ファイル名に数値を追加することで、トレース ファイルの有効期間を追跡します。

たとえば、 @tracefile パラメーターが C:\mytrace として指定されている場合、名前 C:\mytrace_123.trc を持つファイルが、 C:\mytrace_124.trcという名前のファイルよりも古くなります。 @filecountが 2 に設定されている場合、SQL Server はトレース ファイル C:\mytrace_125.trcを作成する前にファイル C:\mytrace_123.trcを削除します。

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

リターン コードの値

次の表では、ストアド プロシージャの完了後に取得できるコード値について説明します。

解説

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_*) のパラメーターは厳密に型指定されます。 これらのパラメーターが、引数の説明で指定されている正しいデータ型で呼び出されないと、このストアド プロシージャではエラーが返されます。

sp_trace_createの場合、SQL Server サービス アカウントには、トレース ファイル フォルダーに対する write アクセス許可が必要です。 SQL Server サービス アカウントがトレース ファイルが配置されているコンピューターの管理者でない場合は、SQL Server サービス アカウントに書き込みアクセス許可を明示的に付与する必要があります。

トレース ストアド プロシージャの使用例については、「トレースの作成を参照してください。

TRACE_PRODUCE_BLACKBOX には、次の特性があります。

• ロールオーバー トレースです。 既定の @filecount は 2 ですが、 @filecount オプションを使用してユーザーによってオーバーライドできます。

• 他のトレースと同様に、既定の @maxfilesizeは 5 MB であり、変更できます。

• ファイル名を指定できません。 ファイルは次のように保存されます: N'%SQLDIR%\MSSQL\DATA\blackbox.trc'。

• トレースには、次のイベントとその列のみが含まれます。

  • RPC の開始
  • バッチ開始
  • 例外
  • アテンション

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

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

アクセス許可

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)