既存の SQL トレース スクリプトから拡張イベント セッションへの変換Convert an Existing SQL Trace Script to an Extended Events Session

拡張イベント セッションに変換する SQL トレース スクリプトが既に手元にある場合は、このトピックの手順を使用して、等価な拡張イベント セッションを作成できます。If you have an existing SQL Trace script that you want to convert to an Extended Events session, you can use the procedures in this topic to create an equivalent Extended Events session. 変換を実行するために必要な情報は、trace_xe_action_map および trace_xe_event_map システム テーブル内の情報を使用して収集できます。By using the information in the trace_xe_action_map and trace_xe_event_map system tables, you can collect the information that you must have to do the conversion.

手順は次のとおりです。The steps include the following:

  1. 既存のスクリプトを実行して SQL トレース セッションを作成し、トレースの ID を取得します。Execute the existing script to create a SQL Trace session, and then obtain the ID of the trace.

  2. fn_trace_geteventinfo 関数を使用したクエリを実行して、SQL トレース イベント クラスとそれに関連付けられた列ごとに、等価な拡張イベントおよびアクションを探します。Run a query that uses the fn_trace_geteventinfo function to find the equivalent Extended Events events and actions for each SQL Trace event class and its associated columns.

  3. 使用するフィルターおよび等価な拡張イベントのアクションを、fn_trace_getfilterinfo 関数を使用して特定します。Use the fn_trace_getfilterinfo function to list the filters and the equivalent Extended Events actions to use.

  4. 拡張イベントにおける等価なイベント、アクション、および述語 (フィルター) を使用して、拡張イベント セッションを手動で作成します。Manually create an Extended Events session, using the equivalent Extended Events events, actions, and predicates (filters).

トレース ID を取得するにはTo obtain the trace ID

  1. クエリ エディターで SQL トレース スクリプトを開き、スクリプトを実行してトレース セッションを作成します。Open the SQL Trace script in Query Editor, and then execute the script to create the trace session. この手順を実行するために必ずしもトレース セッションが実行されている必要はありません。Note that the trace session does not need to be running to complete this procedure.

  2. トレースの ID を取得します。Obtain the ID of the trace. そのためには、次のクエリを使用します。To do this, use the following query:

    SELECT * FROM sys.traces;  
    GO  
    

    注意

    トレース ID 1 は通常、既定のトレースを示します。Trace ID 1 typically indicates the default trace.

等価な拡張イベントを特定するにはTo determine the Extended Events equivalents

  1. 拡張イベントにおける等価なイベントとアクションを特定するには、次のクエリを実行します。 trace_id は、前の手順で取得したトレース ID の値に設定されています。To determine the equivalent Extended Events events and actions, run the following query, where trace_id is set to the value of the trace ID that you obtained in the previous procedure.

    注意

    この例では、既定のトレースの ID (1) が使用されます。In this example, the trace ID for the default trace (1) is used.

    USE MASTER;  
    GO  
    DECLARE @trace_id int;  
    SET @trace_id = 1;  
    SELECT DISTINCT el.eventid, em.package_name, em.xe_event_name AS 'event'  
       , el.columnid, ec.xe_action_name AS 'action'  
    FROM (sys.fn_trace_geteventinfo(@trace_id) AS el  
       LEFT OUTER JOIN sys.trace_xe_event_map AS em  
          ON el.eventid = em.trace_event_id)  
    LEFT OUTER JOIN sys.trace_xe_action_map AS ec  
       ON el.columnid = ec.trace_column_id  
    WHERE em.xe_event_name IS NOT NULL AND ec.xe_action_name IS NOT NULL;  
    

    拡張イベントにおける等価なイベント ID、パッケージ名、イベント名、列 ID、およびアクション名が返されます。The equivalent Extended Events event ID, package name, event name, column ID and action name are returned. この出力結果は、このトピックの「拡張イベント セッションを作成するには」の手順で使用します。You will use this output in the procedure "To create the Extended Events session" later in this topic.

    場合によっては、フィルター選択された列が、既定で含まれているイベント データ フィールドにマップされていることも考えられます。In some cases, the filtered column maps to an event data field that is included by default in the Extended Events event. このとき、"Extended_Events_action_name" 列は NULL になります。Therefore, the "Extended_Events_action_name" column will be NULL. この場合、次の手順に従って、フィルター選択された列に対応するデータ フィールドを特定する必要があります。If this occurs, you must do the following to determine which data field is equivalent to the filtered column:

    1. NULL を返すアクションに関して、スクリプト内のどの SQL トレース イベント クラスに、フィルター選択の対象となる列が含まれているかを特定します。For the actions that return NULL, identify which SQL Trace event classes in the script contain the column that is being filtered.

      たとえば、イベント クラス SP:StmtCompleted を使用し、トレース列名 Duration に対するフィルターを指定したとします (SQL トレース イベント クラス ID が 45 で、SQL トレースの列 ID が 13)。For example, you may have used the SP:StmtCompleted event class, and specified a filter on the Duration trace column name (SQL Trace event class ID 45, and SQL Trace column ID 13). この場合、クエリの結果には、アクション名が NULL として表示されます。In this case, the action name will appear as NULL in the query results.

    2. 前の手順で特定した SQL トレース イベント クラスごとに、拡張イベントにおける等価なイベント名を探します。For each SQL Trace event class that you identified in the previous step, find the equivalent Extended Events event name. (等価なイベント名がわからない場合は、「 SQL トレースのイベント クラスと等価な拡張イベントを確認する」のトピックに記載されているクエリを使用してください。)。(If you are not sure of the equivalent event name, use the query in the topic View the Extended Events Equivalents to SQL Trace Event Classes.)

    3. 次のクエリを使用して、前の手順で判明したイベントに使用する適切なデータ フィールドを特定します。Use the following query to identify the correct data fields to use for the events that you identified in the previous step. このクエリでは、拡張イベントのデータ フィールドが "event_field" 列に反映されます。The query shows the Extended Events data fields in the "event_field" column. クエリ内の <event_name> は、前の手順で指定したイベントの名前に置き換えてください。In the query, replace <event_name> with the name of an event that you specified in the previous step.

      SELECT xp.name package_name, xe.name event_name  
         ,xc.name event_field, xc.description  
      FROM sys.trace_xe_event_map AS em  
      INNER JOIN sys.dm_xe_objects AS xe  
         ON em.xe_event_name = xe.name  
      INNER JOIN sys.dm_xe_packages AS xp  
         ON xe.package_guid = xp.guid AND em.package_name = xp.name  
      INNER JOIN sys.dm_xe_object_columns AS xc  
         ON xe.name = xc.object_name  
      WHERE xe.object_type = 'event' AND xc.column_type <> 'readonly'  
         AND em.xe_event_name = '<event_name>';  
      

      たとえば、SP:StmtCompleted イベント クラスは、sp_statement_completed 拡張イベントに対応します。For example, the SP:StmtCompleted event class maps to the sp_statement_completed Extended Events event. クエリの中で、イベント名として sp_statement_completed を指定した場合、そのイベントに既定で含まれているフィールドが "event_field" 列に表示されます。If you specify sp_statement_completed as the event name in the query, the "event_field" column shows the fields that are included by default with the event. これらのフィールドを見ると、"duration" というフィールドが存在するのがわかります。Looking at the fields, you can see that there is a "duration" field. 等価な拡張イベント セッションにフィルターを作成するには、"WHERE duration > 0" などの述語を追加します。To create the filter in the equivalent Extended Events session, you would add a predicate such as "WHERE duration > 0". 例については、このトピックの「拡張イベント セッションを作成するには」の手順を参照してください。For an example, see the "To create the Extended Events session" procedure in this topic.

拡張イベント セッションを作成するにはTo create the Extended Events session

クエリ エディターを使用して拡張イベント セッションを作成し、出力結果をファイル ターゲットに書き込みます。Use Query Editor to create the Extended Events session, and to write the output to a file target. 以降の手順は、単一のクエリについて記述したものです。クエリの実際の作成方法を交えて説明しています。The following steps describe a single query, with explanations to show you how to build the query. クエリ全体の例については、このトピックの「使用例」のセクションを参照してください。For the full query example, see the "Example" section of this topic.

  1. イベント セッションを作成するためのステートメントを追加します。session_name の部分は、拡張イベント セッションに使用する名前に置き換えてください。Add statements to create the event session, replacing session_name with the name that you want to use for the Extended Events session.

    IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='session_name')  
       DROP EVENT SESSION [Session_Name] ON SERVER;  
    CREATE EVENT SESSION [Session_Name]  
    ON SERVER;  
    
  2. 「等価な拡張イベントを特定するには」の手順の出力結果として返された拡張イベントのイベントとアクションを追加し、「スクリプトに使用されているフィルターを特定するには」の手順で特定した述語 (フィルター) を追加します。Add the Extended Events events and actions that were returned as output in the procedure "Determine the Extended Events equivalents", and add the predicates (filters) that you identified in the procedure "To determine the filters that were used in the script".

    次の例には、SQL:StmtStarting イベント クラスと SP:StmtCompleted イベント クラス、さらに、セッションの ID と実行時間 (duration) のフィルターを含んだ SQL トレース スクリプトが使用されています。The following example uses a SQL Trace script that includes the SQL:StmtStarting and SP:StmtCompleted event classes, with filters for session ID and duration. 「等価な拡張イベントを特定するには」の手順で紹介したクエリのサンプル出力では、次の結果セットが返されます。Sample output for the query in the "Determine the Extended Events equivalents" procedure returned the following result set:

    Eventid  package_name  event                   columnid  action  
    44       sqlserver     sp_statement_starting   6         nt_username  
    44       sqlserver     sp_statement_starting   9         client_pid  
    44       sqlserver     sp_statement_starting   10        client_app_name  
    44       sqlserver     sp_statement_starting   11        server_principal_name  
    44       sqlserver     sp_statement_starting   12        session_id  
    45       sqlserver     sp_statement_completed  6         nt_username  
    45       sqlserver     sp_statement_completed  9         client_pid  
    45       sqlserver     sp_statement_completed  10        client_app_name  
    45       sqlserver     sp_statement_completed  11        server_principal_name  
    45       sqlserver     sp_statement_completed  12        session_id  
    

    これを等価な拡張イベントに変換するには、sqlserver.sp_statement_starting イベントと sqlserver.sp_statement_completed events イベントを一連のアクションと共に追加します。To convert this to the Extended Events equivalent, the sqlserver.sp_statement_starting and the sqlserver.sp_statement_completed events are added, with a list of actions. 述語のステートメントは、WHERE 句として追加されています。Predicate statements are included as WHERE clauses.

    ADD EVENT sqlserver.sp_statement_starting  
       (ACTION  
          (  
          sqlserver.nt_username,  
          sqlserver.client_pid,  
          sqlserver.client_app_name,  
          sqlserver.server_principal_name,  
          sqlserver.session_id  
          )  
       WHERE sqlserver.session_id = 59   
       ),  
    
    ADD EVENT sqlserver.sp_statement_completed  
       (ACTION  
          (  
          sqlserver.nt_username,  
          sqlserver.client_pid,  
          sqlserver.client_app_name,  
          sqlserver.server_principal_name,  
          sqlserver.session_id  
          )  
       WHERE sqlserver.session_id = 59 AND duration > 0  
       )  
    
  3. 非同期のファイル ターゲットを追加します。ファイル パスは、出力結果の実際の保存場所に置き換えてください。Add the asynchronous file target, replacing the file paths with the location where you want to save the output. ファイル ターゲットを指定するときは、ログ ファイルとメタデータ ファイルのパス ファイルを含める必要があります。When specifying the file target, you must include a log file and metadata file path file.

    ADD TARGET package0.asynchronous_file_target(  
       SET filename='c:\temp\ExtendedEventsStoredProcs.xel', metadatafile='c:\temp\ExtendedEventsStoredProcs.xem');  
    

結果を表示するにはTo view the results

  1. 出力結果は、sys.fn_xe_file_target_read_file 関数を使用して表示できます。You can use the sys.fn_xe_file_target_read_file function to view the output. そのためには、次のクエリを実行します。ファイル パスは、実際に指定したパスに置き換えてください。To do this, run the following query, replacing the file paths with the paths that you specified:

    SELECT *, CAST(event_data as XML) AS 'event_data_XML'  
    FROM sys.fn_xe_file_target_read_file('c:\temp\ExtendedEventsStoredProcs*.xel', 'c:\temp\ExtendedEventsStoredProcs*.xem', NULL, NULL);  
    
    

    注意

    イベント データを XML としてキャストしていますが、これは任意です。Casting the event data as XML is optional.

    sys.fn_xe_file_target_read_file 関数の詳細については、「sys.fn_xe_file_target_read_file (Transact-SQL)」を参照してください。For more information about the sys.fn_xe_file_target_read_file function, see sys.fn_xe_file_target_read_file (Transact-SQL).

    IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='session_name')  
       DROP EVENT SESSION [session_name] ON SERVER;  
    CREATE EVENT SESSION [session_name]  
    ON SERVER  
    
    ADD EVENT sqlserver.sp_statement_starting  
       (ACTION  
       (  
          sqlserver.nt_username,  
          sqlserver.client_pid,  
          sqlserver.client_app_name,  
          sqlserver.server_principal_name,  
          sqlserver.session_id  
       )  
       WHERE sqlserver.session_id = 59   
       ),  
    
    ADD EVENT sqlserver.sp_statement_completed  
       (ACTION  
       (  
          sqlserver.nt_username,  
          sqlserver.client_pid,  
          sqlserver.client_app_name,  
          sqlserver.server_principal_name,  
          sqlserver.session_id  
       )  
       WHERE sqlserver.session_id = 59 AND duration > 0  
       );  
    
    ADD TARGET package0.asynchronous_file_target  
       (SET filename='c:\temp\ExtendedEventsStoredProcs.xel', metadatafile='c:\temp\ExtendedEventsStoredProcs.xem');  
    

Example

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='session_name')  
   DROP EVENT SESSION [session_name] ON SERVER;  
CREATE EVENT SESSION [session_name]  
ON SERVER  
  
ADD EVENT sqlserver.sp_statement_starting  
   (ACTION  
   (  
      sqlserver.nt_username,  
      sqlserver.client_pid,  
      sqlserver.client_app_name,  
      sqlserver.server_principal_name,  
      sqlserver.session_id  
   )  
   WHERE sqlserver.session_id = 59   
   ),  
  
ADD EVENT sqlserver.sp_statement_completed  
   (ACTION  
   (  
      sqlserver.nt_username,  
      sqlserver.client_pid,  
      sqlserver.client_app_name,  
      sqlserver.server_principal_name,  
      sqlserver.session_id  
   )  
   WHERE sqlserver.session_id = 59 AND duration > 0  
   )  
  
ADD TARGET package0.asynchronous_file_target  
   (SET filename='c:\temp\ExtendedEventsStoredProcs.xel', metadatafile='c:\temp\ExtendedEventsStoredProcs.xem');  

参照See Also

SQL トレースのイベント クラスと等価な拡張イベントを確認するView the Extended Events Equivalents to SQL Trace Event Classes