<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h3 class="title">
      <a name="performance-schema-thread-filtering">
      </a>
      29.4.6 Pre-Filtering by Thread
     </h3>
    </div>
   </div>
  </div>
  <p>
   The
   <a class="link" href="performance-schema-threads-table.html" title="29.12.22.8 The threads Table">
    <code class="literal">
     threads
    </code>
   </a>
   table contains a row
        for each server thread. Each row contains information about a
        thread and indicates whether monitoring is enabled for it. For
        the Performance Schema to monitor a thread, these things must be
        true:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The
      <code class="literal">
       thread_instrumentation
      </code>
      consumer in
            the
      <a class="link" href="performance-schema-setup-consumers-table.html" title="29.12.2.2 The setup_consumers Table">
       <code class="literal">
        setup_consumers
       </code>
      </a>
      table must
            be
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      The
      <code class="literal">
       threads.INSTRUMENTED
      </code>
      column must be
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Monitoring occurs only for those thread events produced from
            instruments that are enabled in the
      <a class="link" href="performance-schema-setup-instruments-table.html" title="29.12.2.3 The setup_instruments Table">
       <code class="literal">
        setup_instruments
       </code>
      </a>
      table.
     </p>
    </li>
   </ul>
  </div>
  <p>
   The
   <a class="link" href="performance-schema-threads-table.html" title="29.12.22.8 The threads Table">
    <code class="literal">
     threads
    </code>
   </a>
   table also indicates
        for each server thread whether to perform historical event
        logging. This includes wait, stage, statement, and transaction
        events and affects logging to these tables:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-none"><div class="docs-select-all right" id="sa1634873"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">events_waits_history
events_waits_history_long
events_stages_history
events_stages_history_long
events_statements_history
events_statements_history_long
events_transactions_history
events_transactions_history_long</code></pre>
  </div>
  <p>
   For historical event logging to occur, these things must be
        true:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The appropriate history-related consumers in the
      <a class="link" href="performance-schema-setup-consumers-table.html" title="29.12.2.2 The setup_consumers Table">
       <code class="literal">
        setup_consumers
       </code>
      </a>
      table must be
            enabled. For example, wait event logging in the
      <a class="link" href="performance-schema-events-waits-history-table.html" title="29.12.4.2 The events_waits_history Table">
       <code class="literal">
        events_waits_history
       </code>
      </a>
      and
      <a class="link" href="performance-schema-events-waits-history-long-table.html" title="29.12.4.3 The events_waits_history_long Table">
       <code class="literal">
        events_waits_history_long
       </code>
      </a>
      tables requires the corresponding
      <code class="literal">
       events_waits_history
      </code>
      and
      <code class="literal">
       events_waits_history_long
      </code>
      consumers to be
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      The
      <code class="literal">
       threads.HISTORY
      </code>
      column must be
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Logging occurs only for those thread events produced from
            instruments that are enabled in the
      <a class="link" href="performance-schema-setup-instruments-table.html" title="29.12.2.3 The setup_instruments Table">
       <code class="literal">
        setup_instruments
       </code>
      </a>
      table.
     </p>
    </li>
   </ul>
  </div>
  <p>
   For foreground threads (resulting from client connections), the
        initial values of the
   <code class="literal">
    INSTRUMENTED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   columns in
   <a class="link" href="performance-schema-threads-table.html" title="29.12.22.8 The threads Table">
    <code class="literal">
     threads
    </code>
   </a>
   table rows are determined
        by whether the user account associated with a thread matches any
        row in the
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   table. The
        values come from the
   <code class="literal">
    ENABLED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   columns of the matching
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   table row.
  </p>
  <p>
   For background threads, there is no associated user.
   <code class="literal">
    INSTRUMENTED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   are
   <code class="literal">
    YES
   </code>
   by default and
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   is not consulted.
  </p>
  <p>
   The initial
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   contents
        look like this:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa50900419"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> <span class="token operator">*</span> <span class="token keyword">FROM</span> performance_schema<span class="token punctuation">.</span>setup_actors<span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> HOST <span class="token punctuation">|</span> USER <span class="token punctuation">|</span> ROLE <span class="token punctuation">|</span> ENABLED <span class="token punctuation">|</span> HISTORY <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> %    <span class="token punctuation">|</span> %    <span class="token punctuation">|</span> %    <span class="token punctuation">|</span> YES     <span class="token punctuation">|</span> YES     <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
  </div>
  <p>
   The
   <code class="literal">
    HOST
   </code>
   and
   <code class="literal">
    USER
   </code>
   columns
        should contain a literal host or user name, or
   <code class="literal">
    '%'
   </code>
   to match any name.
  </p>
  <p>
   The
   <code class="literal">
    ENABLED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   columns indicate whether to enable instrumentation and
        historical event logging for matching threads, subject to the
        other conditions described previously.
  </p>
  <p>
   When the Performance Schema checks for a match for each new
        foreground thread in
   <code class="literal">
    setup_actors
   </code>
   , it tries
        to find more specific matches first, using the
   <code class="literal">
    USER
   </code>
   and
   <code class="literal">
    HOST
   </code>
   columns
        (
   <code class="literal">
    ROLE
   </code>
   is unused):
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Rows with
      <code class="literal">
       USER='
       <em class="replaceable">
        <code>
         literal
        </code>
       </em>
       '
      </code>
      and
      <code class="literal">
       HOST='
       <em class="replaceable">
        <code>
         literal
        </code>
       </em>
       '
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Rows with
      <code class="literal">
       USER='
       <em class="replaceable">
        <code>
         literal
        </code>
       </em>
       '
      </code>
      and
      <code class="literal">
       HOST='%'
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Rows with
      <code class="literal">
       USER='%'
      </code>
      and
      <code class="literal">
       HOST='
       <em class="replaceable">
        <code>
         literal
        </code>
       </em>
       '
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Rows with
      <code class="literal">
       USER='%'
      </code>
      and
      <code class="literal">
       HOST='%'
      </code>
      .
     </p>
    </li>
   </ul>
  </div>
  <p>
   The order in which matching occurs matters because different
        matching
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   rows can have
        different
   <code class="literal">
    USER
   </code>
   and
   <code class="literal">
    HOST
   </code>
   values. This enables instrumenting and historical event logging
        to be applied selectively per host, user, or account (user and
        host combination), based on the
   <code class="literal">
    ENABLED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   column values:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      When the best match is a row with
      <code class="literal">
       ENABLED=YES
      </code>
      , the
      <code class="literal">
       INSTRUMENTED
      </code>
      value for the thread becomes
      <code class="literal">
       YES
      </code>
      . When the best match is a row with
      <code class="literal">
       HISTORY=YES
      </code>
      , the
      <code class="literal">
       HISTORY
      </code>
      value for the thread becomes
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      When the best match is a row with
      <code class="literal">
       ENABLED=NO
      </code>
      , the
      <code class="literal">
       INSTRUMENTED
      </code>
      value for the thread becomes
      <code class="literal">
       NO
      </code>
      . When the best match is a row with
      <code class="literal">
       HISTORY=NO
      </code>
      , the
      <code class="literal">
       HISTORY
      </code>
      value for the thread becomes
      <code class="literal">
       NO
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      When no match is found, the
      <code class="literal">
       INSTRUMENTED
      </code>
      and
      <code class="literal">
       HISTORY
      </code>
      values for the thread become
      <code class="literal">
       NO
      </code>
      .
     </p>
    </li>
   </ul>
  </div>
  <p>
   The
   <code class="literal">
    ENABLED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   columns in
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   rows can be
        set to
   <code class="literal">
    YES
   </code>
   or
   <code class="literal">
    NO
   </code>
   independent of one another. This means you can enable
        instrumentation separately from whether you collect historical
        events.
  </p>
  <p>
   By default, monitoring and historical event collection are
        enabled for all new foreground threads because the
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   table initially
        contains a row with
   <code class="literal">
    '%'
   </code>
   for both
   <code class="literal">
    HOST
   </code>
   and
   <code class="literal">
    USER
   </code>
   . To perform
        more limited matching such as to enable monitoring only for some
        foreground threads, you must change this row because it matches
        any connection, and add rows for more specific
   <code class="literal">
    HOST
   </code>
   /
   <code class="literal">
    USER
   </code>
   combinations.
  </p>
  <p>
   Suppose that you modify
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   as follows:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa33745681"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">UPDATE</span> performance_schema<span class="token punctuation">.</span>setup_actors
<span class="token keyword">SET</span> ENABLED <span class="token operator">=</span> <span class="token string">'NO'</span><span class="token punctuation">,</span> <span class="token keyword">HISTORY</span> <span class="token operator">=</span> <span class="token string">'NO'</span>
<span class="token keyword">WHERE</span> <span class="token keyword">HOST</span> <span class="token operator">=</span> <span class="token string">'%'</span> <span class="token operator">AND</span> <span class="token keyword">USER</span> <span class="token operator">=</span> <span class="token string">'%'</span><span class="token punctuation">;</span>
<span class="token keyword">INSERT</span> <span class="token keyword">INTO</span> performance_schema<span class="token punctuation">.</span>setup_actors
<span class="token punctuation">(</span><span class="token keyword">HOST</span><span class="token punctuation">,</span><span class="token keyword">USER</span><span class="token punctuation">,</span><span class="token keyword">ROLE</span><span class="token punctuation">,</span>ENABLED<span class="token punctuation">,</span><span class="token keyword">HISTORY</span><span class="token punctuation">)</span>
<span class="token keyword">VALUES</span><span class="token punctuation">(</span><span class="token string">'localhost'</span><span class="token punctuation">,</span><span class="token string">'joe'</span><span class="token punctuation">,</span><span class="token string">'%'</span><span class="token punctuation">,</span><span class="token string">'YES'</span><span class="token punctuation">,</span><span class="token string">'YES'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">INSERT</span> <span class="token keyword">INTO</span> performance_schema<span class="token punctuation">.</span>setup_actors
<span class="token punctuation">(</span><span class="token keyword">HOST</span><span class="token punctuation">,</span><span class="token keyword">USER</span><span class="token punctuation">,</span><span class="token keyword">ROLE</span><span class="token punctuation">,</span>ENABLED<span class="token punctuation">,</span><span class="token keyword">HISTORY</span><span class="token punctuation">)</span>
<span class="token keyword">VALUES</span><span class="token punctuation">(</span><span class="token string">'hosta.example.com'</span><span class="token punctuation">,</span><span class="token string">'joe'</span><span class="token punctuation">,</span><span class="token string">'%'</span><span class="token punctuation">,</span><span class="token string">'YES'</span><span class="token punctuation">,</span><span class="token string">'NO'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">INSERT</span> <span class="token keyword">INTO</span> performance_schema<span class="token punctuation">.</span>setup_actors
<span class="token punctuation">(</span><span class="token keyword">HOST</span><span class="token punctuation">,</span><span class="token keyword">USER</span><span class="token punctuation">,</span><span class="token keyword">ROLE</span><span class="token punctuation">,</span>ENABLED<span class="token punctuation">,</span><span class="token keyword">HISTORY</span><span class="token punctuation">)</span>
<span class="token keyword">VALUES</span><span class="token punctuation">(</span><span class="token string">'%'</span><span class="token punctuation">,</span><span class="token string">'sam'</span><span class="token punctuation">,</span><span class="token string">'%'</span><span class="token punctuation">,</span><span class="token string">'NO'</span><span class="token punctuation">,</span><span class="token string">'YES'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
  </div>
  <p>
   The
   <a class="link" href="update.html" title="15.2.17 UPDATE Statement">
    <code class="literal">
     UPDATE
    </code>
   </a>
   statement changes the
        default match to disable instrumentation and historical event
        collection. The
   <a class="link" href="insert.html" title="15.2.7 INSERT Statement">
    <code class="literal">
     INSERT
    </code>
   </a>
   statements
        add rows for more specific matches.
  </p>
  <p>
   Now the Performance Schema determines how to set the
   <code class="literal">
    INSTRUMENTED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   values for new connection threads as follows:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      If
      <code class="literal">
       joe
      </code>
      connects from the local host, the
            connection matches the first inserted row. The
      <code class="literal">
       INSTRUMENTED
      </code>
      and
      <code class="literal">
       HISTORY
      </code>
      values for the thread become
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      If
      <code class="literal">
       joe
      </code>
      connects from
      <code class="literal">
       hosta.example.com
      </code>
      , the connection matches
            the second inserted row. The
      <code class="literal">
       INSTRUMENTED
      </code>
      value for the thread becomes
      <code class="literal">
       YES
      </code>
      and the
      <code class="literal">
       HISTORY
      </code>
      value becomes
      <code class="literal">
       NO
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      If
      <code class="literal">
       joe
      </code>
      connects from any other host,
            there is no match. The
      <code class="literal">
       INSTRUMENTED
      </code>
      and
      <code class="literal">
       HISTORY
      </code>
      values for the thread become
      <code class="literal">
       NO
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      If
      <code class="literal">
       sam
      </code>
      connects from any host, the
            connection matches the third inserted row. The
      <code class="literal">
       INSTRUMENTED
      </code>
      value for the thread becomes
      <code class="literal">
       NO
      </code>
      and the
      <code class="literal">
       HISTORY
      </code>
      value becomes
      <code class="literal">
       YES
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      For any other connection, the row with
      <code class="literal">
       HOST
      </code>
      and
      <code class="literal">
       USER
      </code>
      set to
      <code class="literal">
       '%'
      </code>
      matches. This row now has
      <code class="literal">
       ENABLED
      </code>
      and
      <code class="literal">
       HISTORY
      </code>
      set to
      <code class="literal">
       NO
      </code>
      , so the
      <code class="literal">
       INSTRUMENTED
      </code>
      and
      <code class="literal">
       HISTORY
      </code>
      values for the thread become
      <code class="literal">
       NO
      </code>
      .
     </p>
    </li>
   </ul>
  </div>
  <p>
   Modifications to the
   <a class="link" href="performance-schema-setup-actors-table.html" title="29.12.2.1 The setup_actors Table">
    <code class="literal">
     setup_actors
    </code>
   </a>
   table affect only foreground threads created subsequent to the
        modification, not existing threads. To affect existing threads,
        modify the
   <code class="literal">
    INSTRUMENTED
   </code>
   and
   <code class="literal">
    HISTORY
   </code>
   columns of
   <a class="link" href="performance-schema-threads-table.html" title="29.12.22.8 The threads Table">
    <code class="literal">
     threads
    </code>
   </a>
   table rows.
  </p>
 </div>
 <br/>
</div>
