<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h3 class="title">
      <a name="audit-api-message-emit">
      </a>
      8.4.6 The Audit Message Component
     </h3>
    </div>
   </div>
  </div>
  <p>
   The
   <code class="literal">
    audit_api_message_emit
   </code>
   component enables
      applications to add their own message events to the audit log,
      using the
   <a class="link" href="audit-api-message-emit.html#function_audit-api-message-emit-udf">
    <code class="literal">
     audit_api_message_emit_udf()
    </code>
   </a>
   function.
  </p>
  <p>
   The
   <code class="literal">
    audit_api_message_emit
   </code>
   component cooperates
      with all plugins of audit type. For concreteness, examples use the
   <code class="literal">
    audit_log
   </code>
   plugin described in
   <a class="xref" href="audit-log.html" title="8.4.5 MySQL Enterprise Audit">
    Section 8.4.5, “MySQL Enterprise Audit”
   </a>
   .
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="audit-api-message-emit.html#audit-api-message-emit-install" title="Installing or Uninstalling the Audit Message Component">
       Installing or Uninstalling the Audit Message Component
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="audit-api-message-emit.html#audit-api-message-emit-functions" title="Audit Message Function">
       Audit Message Function
      </a>
     </p>
    </li>
   </ul>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="audit-api-message-emit-install">
       </a>
       Installing or Uninstalling the Audit Message Component
      </h4>
     </div>
    </div>
   </div>
   <p>
    To be usable by the server, the component library file must be
        located in the MySQL plugin directory (the directory named by
        the
    <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
     <code class="literal">
      plugin_dir
     </code>
    </a>
    system
        variable). If necessary, configure the plugin directory location
        by setting the value of
    <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
     <code class="literal">
      plugin_dir
     </code>
    </a>
    at server startup.
   </p>
   <p>
    To install the
    <code class="literal">
     audit_api_message_emit
    </code>
    component, use this statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa91798039"><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">INSTALL</span> <span class="token keyword">COMPONENT</span> <span class="token string">"file://component_audit_api_message_emit"</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    Component installation is a one-time operation that need not be
        done per server startup.
    <a class="link" href="install-component.html" title="15.7.4.3 INSTALL COMPONENT Statement">
     <code class="literal">
      INSTALL
        COMPONENT
     </code>
    </a>
    loads the component, and also registers it
        in the
    <code class="literal">
     mysql.component
    </code>
    system table to cause
        it to be loaded during subsequent server startups.
   </p>
   <p>
    To uninstall the
    <code class="literal">
     audit_api_message_emit
    </code>
    component, use this statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa79523706"><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">UNINSTALL</span> <span class="token keyword">COMPONENT</span> <span class="token string">"file://component_audit_api_message_emit"</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="uninstall-component.html" title="15.7.4.5 UNINSTALL COMPONENT Statement">
     <code class="literal">
      UNINSTALL COMPONENT
     </code>
    </a>
    unloads the
        component, and unregisters it from the
    <code class="literal">
     mysql.component
    </code>
    system table to cause it not
        to be loaded during subsequent server startups.
   </p>
   <p>
    Because installing and uninstalling the
    <code class="literal">
     audit_api_message_emit
    </code>
    component installs and
        uninstalls the
    <a class="link" href="audit-api-message-emit.html#function_audit-api-message-emit-udf">
     <code class="literal">
      audit_api_message_emit_udf()
     </code>
    </a>
    function that the component implements, it is not necessary to
        use
    <a class="link" href="create-function-loadable.html" title="15.7.4.1 CREATE FUNCTION Statement for Loadable Functions">
     <code class="literal">
      CREATE
        FUNCTION
     </code>
    </a>
    or
    <a class="link" href="drop-function-loadable.html" title="15.7.4.2 DROP FUNCTION Statement for Loadable Functions">
     <code class="literal">
      DROP
        FUNCTION
     </code>
    </a>
    to do so.
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h4 class="title">
       <a name="audit-api-message-emit-functions">
       </a>
       Audit Message Function
      </h4>
     </div>
    </div>
   </div>
   <p>
    This section describes the
    <a class="link" href="audit-api-message-emit.html#function_audit-api-message-emit-udf">
     <code class="literal">
      audit_api_message_emit_udf()
     </code>
    </a>
    function implemented by the
    <code class="literal">
     audit_api_message_emit
    </code>
    component.
   </p>
   <p>
    Before using the audit message function, install the audit
        message component according to the instructions provided at
    <a class="xref" href="audit-api-message-emit.html#audit-api-message-emit-install" title="Installing or Uninstalling the Audit Message Component">
     Installing or Uninstalling the Audit Message Component
    </a>
    .
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       <a name="function_audit-api-message-emit-udf">
       </a>
       <a class="link" href="audit-api-message-emit.html#function_audit-api-message-emit-udf">
        <code class="literal">
         audit_api_message_emit_udf(
         <em class="replaceable">
          <code>
           component
          </code>
         </em>
         ,
         <em class="replaceable">
          <code>
           producer
          </code>
         </em>
         ,
         <em class="replaceable">
          <code>
           message
          </code>
         </em>
         [,
         <em class="replaceable">
          <code>
           key
          </code>
         </em>
         ,
         <em class="replaceable">
          <code>
           value
          </code>
         </em>
         ] ...)
        </code>
       </a>
      </p>
      <a class="indexterm" name="idm46045234678448">
      </a>
      <a class="indexterm" name="idm46045234677344">
      </a>
      <p>
       Adds a message event to the audit log. Message events
            include component, producer, and message strings of the
            caller's choosing, and optionally a set of key-value
            pairs.
      </p>
      <p>
       An event posted by this function is sent to all enabled
            plugins of audit type, each of which handles the event
            according to its own rules. If no plugin of audit type is
            enabled, posting the event has no effect.
      </p>
      <p>
       Arguments:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          <em class="replaceable">
           <code>
            component
           </code>
          </em>
          : A string that
                specifies a component name.
         </p>
        </li>
        <li class="listitem">
         <p>
          <em class="replaceable">
           <code>
            producer
           </code>
          </em>
          : A string that
                specifies a producer name.
         </p>
        </li>
        <li class="listitem">
         <p>
          <em class="replaceable">
           <code>
            message
           </code>
          </em>
          : A string that
                specifies the event message.
         </p>
        </li>
        <li class="listitem">
         <p>
          <em class="replaceable">
           <code>
            key
           </code>
          </em>
          ,
          <em class="replaceable">
           <code>
            value
           </code>
          </em>
          : Events may include 0
                or more key-value pairs that specify an arbitrary
                application-provided data map. Each
          <em class="replaceable">
           <code>
            key
           </code>
          </em>
          argument is a string that
                specifies a name for its immediately following
          <em class="replaceable">
           <code>
            value
           </code>
          </em>
          argument. Each
          <em class="replaceable">
           <code>
            value
           </code>
          </em>
          argument specifies a
                value for its immediately following
          <em class="replaceable">
           <code>
            key
           </code>
          </em>
          argument. Each
          <em class="replaceable">
           <code>
            value
           </code>
          </em>
          can be a string or
                numeric value, or
          <code class="literal">
           NULL
          </code>
          .
         </p>
        </li>
       </ul>
      </div>
      <p>
       Return value:
      </p>
      <p>
       The string
       <code class="literal">
        OK
       </code>
       to indicate success. An
            error occurs if the function fails.
      </p>
      <p>
       Example:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa38067821"><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> audit_api_message_emit_udf<span class="token punctuation">(</span><span class="token string">'component_text'</span><span class="token punctuation">,</span>
                                         <span class="token string">'producer_text'</span><span class="token punctuation">,</span>
                                         <span class="token string">'message_text'</span><span class="token punctuation">,</span>
                                         <span class="token string">'key1'</span><span class="token punctuation">,</span> <span class="token string">'value1'</span><span class="token punctuation">,</span>
                                         <span class="token string">'key2'</span><span class="token punctuation">,</span> <span class="token number">123</span><span class="token punctuation">,</span>
                                         <span class="token string">'key3'</span><span class="token punctuation">,</span> <span class="token boolean">NULL</span><span class="token punctuation">)</span> <span class="token keyword">AS</span> <span class="token string">'Message'</span><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>
<span class="token output"><span class="token punctuation">|</span> Message <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>
<span class="token output"><span class="token punctuation">|</span> OK      <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></code></pre>
      </div>
      <p>
       Additional information:
      </p>
      <p>
       Each audit plugin that receives an event posted by
       <a class="link" href="audit-api-message-emit.html#function_audit-api-message-emit-udf">
        <code class="literal">
         audit_api_message_emit_udf()
        </code>
       </a>
       logs the event in plugin-specific format. For example, the
       <code class="literal">
        audit_log
       </code>
       plugin (see
       <a class="xref" href="audit-log.html" title="8.4.5 MySQL Enterprise Audit">
        Section 8.4.5, “MySQL Enterprise Audit”
       </a>
       ) logs message values as follows,
            depending on the log format configured by the
       <a class="link" href="audit-log-reference.html#sysvar_audit_log_format">
        <code class="literal">
         audit_log_format
        </code>
       </a>
       system
            variable:
      </p>
      <div class="itemizedlist">
       <ul class="itemizedlist" style="list-style-type: circle; ">
        <li class="listitem">
         <p>
          JSON format
                (
          <a class="link" href="audit-log-reference.html#sysvar_audit_log_format">
           <code class="literal">
            audit_log_format=JSON
           </code>
          </a>
          ):
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-json"><div class="docs-select-all right" id="sa18327302"><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-json"><span class="token punctuation">{</span>
  ...
  <span class="token property">"class"</span><span class="token operator">:</span> <span class="token string">"message"</span><span class="token punctuation">,</span>
  <span class="token property">"event"</span><span class="token operator">:</span> <span class="token string">"user"</span><span class="token punctuation">,</span>
  ...
  <span class="token property">"message_data"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"component"</span><span class="token operator">:</span> <span class="token string">"component_text"</span><span class="token punctuation">,</span>
    <span class="token property">"producer"</span><span class="token operator">:</span> <span class="token string">"producer_text"</span><span class="token punctuation">,</span>
    <span class="token property">"message"</span><span class="token operator">:</span> <span class="token string">"message_text"</span><span class="token punctuation">,</span>
    <span class="token property">"map"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token property">"key1"</span><span class="token operator">:</span> <span class="token string">"value1"</span><span class="token punctuation">,</span>
      <span class="token property">"key2"</span><span class="token operator">:</span> <span class="token number">123</span><span class="token punctuation">,</span>
      <span class="token property">"key3"</span><span class="token operator">:</span> <span class="token null">null</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span></code></pre>
         </div>
        </li>
        <li class="listitem">
         <p>
          New-style XML format
                (
          <a class="link" href="audit-log-reference.html#sysvar_audit_log_format">
           <code class="literal">
            audit_log_format=NEW
           </code>
          </a>
          ):
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-xml"><div class="docs-select-all right" id="sa64997184"><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-xml"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>AUDIT_RECORD</span><span class="token punctuation">&gt;</span></span>
 ...
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>NAME</span><span class="token punctuation">&gt;</span></span>Message<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>NAME</span><span class="token punctuation">&gt;</span></span>
 ...
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>COMMAND_CLASS</span><span class="token punctuation">&gt;</span></span>user<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>COMMAND_CLASS</span><span class="token punctuation">&gt;</span></span>
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>COMPONENT</span><span class="token punctuation">&gt;</span></span>component_text<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>COMPONENT</span><span class="token punctuation">&gt;</span></span>
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>PRODUCER</span><span class="token punctuation">&gt;</span></span>producer_text<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>PRODUCER</span><span class="token punctuation">&gt;</span></span>
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>MESSAGE</span><span class="token punctuation">&gt;</span></span>message_text<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>MESSAGE</span><span class="token punctuation">&gt;</span></span>
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>MAP</span><span class="token punctuation">&gt;</span></span>
   <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>ELEMENT</span><span class="token punctuation">&gt;</span></span>
     <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>KEY</span><span class="token punctuation">&gt;</span></span>key1<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>KEY</span><span class="token punctuation">&gt;</span></span>
     <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>VALUE</span><span class="token punctuation">&gt;</span></span>value1<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>VALUE</span><span class="token punctuation">&gt;</span></span>
   <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>ELEMENT</span><span class="token punctuation">&gt;</span></span>
   <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>ELEMENT</span><span class="token punctuation">&gt;</span></span>
     <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>KEY</span><span class="token punctuation">&gt;</span></span>key2<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>KEY</span><span class="token punctuation">&gt;</span></span>
     <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>VALUE</span><span class="token punctuation">&gt;</span></span>123<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>VALUE</span><span class="token punctuation">&gt;</span></span>
   <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>ELEMENT</span><span class="token punctuation">&gt;</span></span>
   <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>ELEMENT</span><span class="token punctuation">&gt;</span></span>
     <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>KEY</span><span class="token punctuation">&gt;</span></span>key3<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>KEY</span><span class="token punctuation">&gt;</span></span>
     <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>VALUE</span><span class="token punctuation">/&gt;</span></span>
   <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>ELEMENT</span><span class="token punctuation">&gt;</span></span>
 <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>MAP</span><span class="token punctuation">&gt;</span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>AUDIT_RECORD</span><span class="token punctuation">&gt;</span></span></code></pre>
         </div>
        </li>
        <li class="listitem">
         <p>
          Old-style XML format
                (
          <a class="link" href="audit-log-reference.html#sysvar_audit_log_format">
           <code class="literal">
            audit_log_format=OLD
           </code>
          </a>
          ):
         </p>
         <div class="copytoclipboard-wrapper">
          <pre class="programlisting language-xml"><div class="docs-select-all right" id="sa96701187"><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-xml"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>AUDIT_RECORD</span>
  <span class="token attr-name">...</span>
  <span class="token attr-name">NAME</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Message<span class="token punctuation">"</span></span>
  <span class="token attr-name">...</span>
  <span class="token attr-name">COMMAND_CLASS</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>user<span class="token punctuation">"</span></span>
  <span class="token attr-name">COMPONENT</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>component_text<span class="token punctuation">"</span></span>
  <span class="token attr-name">PRODUCER</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>producer_text<span class="token punctuation">"</span></span>
  <span class="token attr-name">MESSAGE</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>message_text<span class="token punctuation">"</span></span><span class="token punctuation">/&gt;</span></span></code></pre>
         </div>
         <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <div class="admon-title">
           Note
          </div>
          <p>
           Message events logged in old-style XML format do not
                  include the key-value map due to representational
                  constraints imposed by this format.
          </p>
         </div>
        </li>
       </ul>
      </div>
      <p>
       Messages posted by
       <a class="link" href="audit-api-message-emit.html#function_audit-api-message-emit-udf">
        <code class="literal">
         audit_api_message_emit_udf()
        </code>
       </a>
       have an event class of
       <code class="literal">
        MYSQL_AUDIT_MESSAGE_CLASS
       </code>
       and a subclass
            of
       <code class="literal">
        MYSQL_AUDIT_MESSAGE_USER
       </code>
       . (Internally
            generated audit messages have the same class and a subclass
            of
       <code class="literal">
        MYSQL_AUDIT_MESSAGE_INTERNAL
       </code>
       ; this
            subclass currently is unused.) To refer to such events in
       <code class="literal">
        audit_log
       </code>
       filtering rules, use a
       <code class="literal">
        class
       </code>
       element with a
       <code class="literal">
        name
       </code>
       value of
       <code class="literal">
        message
       </code>
       .
            For example:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-json"><div class="docs-select-all right" id="sa55743967"><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-json"><span class="token punctuation">{</span>
  <span class="token property">"filter"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"class"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token property">"name"</span><span class="token operator">:</span> <span class="token string">"message"</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span></code></pre>
      </div>
      <p>
       Should it be necessary to distinguish user-generated and
            internally generated message events, test the
       <code class="literal">
        subclass
       </code>
       value against
       <code class="literal">
        user
       </code>
       or
       <code class="literal">
        internal
       </code>
       .
      </p>
      <p>
       Filtering based on the contents of the key-value map is not
            supported.
      </p>
      <p>
       For information about writing filtering rules, see
       <a class="xref" href="audit-log-filtering.html" title="8.4.5.7 Audit Log Filtering">
        Section 8.4.5.7, “Audit Log Filtering”
       </a>
       .
      </p>
     </li>
    </ul>
   </div>
  </div>
 </div>
 <br/>
</div>
