8.4.6 The Audit Message Component (original) (raw)

This section describes theaudit_api_message_emit_udf() function implemented by theaudit_api_message_emit component.

• audit_api_message_emit_udf(component,producer,message[,key,value] ...)
  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.
  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.
  Arguments:
  • component: A string that specifies a component name.
  • producer: A string that specifies a producer name.
  • message: A string that specifies the event message.
  • key,value: Events may include 0 or more key-value pairs that specify an arbitrary application-provided data map. Each_key_ argument is a string that specifies a name for its immediately following_value_ argument. Each_value_ argument specifies a value for its immediately following_key_ argument. Each_value_ can be a string or numeric value, or NULL.
    Return value:
    The string OK to indicate success. An error occurs if the function fails.
    Example:

mysql> SELECT audit_api_message_emit_udf('component_text',  
                                         'producer_text',  
                                         'message_text',  
                                         'key1', 'value1',  
                                         'key2', 123,  
                                         'key3', NULL) AS 'Message';  
+---------+  
| Message |  
+---------+  
| OK      |  
+---------+  

Additional information:
Each audit plugin that receives an event posted byaudit_api_message_emit_udf() logs the event in plugin-specific format. For example, theaudit_log plugin (seeSection 8.4.5, “MySQL Enterprise Audit”) logs message values as follows, depending on the log format configured by theaudit_log_format system variable:

• JSON format (audit_log_format=JSON):

{  
  ...  
  "class": "message",  
  "event": "user",  
  ...  
  "message_data": {  
    "component": "component_text",  
    "producer": "producer_text",  
    "message": "message_text",  
    "map": {  
      "key1": "value1",  
      "key2": 123,  
      "key3": null  
    }  
  }  
}  

• New-style XML format (audit_log_format=NEW):

<AUDIT_RECORD>  
 ...  
 <NAME>Message</NAME>  
 ...  
 <COMMAND_CLASS>user</COMMAND_CLASS>  
 <COMPONENT>component_text</COMPONENT>  
 <PRODUCER>producer_text</PRODUCER>  
 <MESSAGE>message_text</MESSAGE>  
 <MAP>  
   <ELEMENT>  
     <KEY>key1</KEY>  
     <VALUE>value1</VALUE>  
   </ELEMENT>  
   <ELEMENT>  
     <KEY>key2</KEY>  
     <VALUE>123</VALUE>  
   </ELEMENT>  
   <ELEMENT>  
     <KEY>key3</KEY>  
     <VALUE/>  
   </ELEMENT>  
 </MAP>  
</AUDIT_RECORD>  

• Old-style XML format (audit_log_format=OLD):

<AUDIT_RECORD  
  ...  
  NAME="Message"  
  ...  
  COMMAND_CLASS="user"  
  COMPONENT="component_text"  
  PRODUCER="producer_text"  
  MESSAGE="message_text"/>  

Note
Message events logged in old-style XML format do not include the key-value map due to representational constraints imposed by this format.
Messages posted byaudit_api_message_emit_udf() have an event class ofMYSQL_AUDIT_MESSAGE_CLASS and a subclass of MYSQL_AUDIT_MESSAGE_USER. (Internally generated audit messages have the same class and a subclass of MYSQL_AUDIT_MESSAGE_INTERNAL; this subclass currently is unused.) To refer to such events inaudit_log filtering rules, use aclass element with aname value of message. For example:

{  
  "filter": {  
    "class": {  
      "name": "message"  
    }  
  }  
}  

Should it be necessary to distinguish user-generated and internally generated message events, test thesubclass value againstuser or internal.
Filtering based on the contents of the key-value map is not supported.
For information about writing filtering rules, seeSection 8.4.5.7, “Audit Log Filtering”.