Difference between revisions of "Writing to the Event Log"

From The Foundry MODO SDK wiki
Jump to: navigation, search
(Direct Log System Access)
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
Status of the running plug-in can be written to the event log, either for the user or for the developer to examine debug state.
 
Status of the running plug-in can be written to the event log, either for the user or for the developer to examine debug state.
  
==== CLxLogMessage ====
+
== When to use the Event Log ==
 +
 
 +
The event log should be used to report useful state for an advanced user.  It should be used relatively sparingly.  Otherwise you're just going to overload the user with a flood of information.
 +
 
 +
If you choose to use the event log for debugging purposes, you should make sure that you've disabled this in shipping builds.  Otherwise you will just be polluting the event log with information that isn't relevant to the user. 
 +
 
 +
Things that should not go to the event log:
 +
* Status messages like "Plug-in has been added", or "File saved" when it's a direct result of a user's action (like saving an image or scene).
 +
* Errors from commands (use the command's ILxMessage (CLxUser_Message) interface instead, obtained via the command's ''basic_Message()'' method).
 +
* Progress updates (use ILxMonitor (CLxUser_Monitor) instead).
 +
 
 +
== Using the Event Log ==
 +
 
 +
==== [[CLxLogMessage (index)|CLxLogMessage]] ====
  
 
This utility class is the easiest way to write to the log, although it was designed for file I/O and still has some of that legacy. You need to declare your own sub-class which implements the ''Format()'' and ''Version()'' methods for your plug-in.
 
This utility class is the easiest way to write to the log, although it was designed for file I/O and still has some of that legacy. You need to declare your own sub-class which implements the ''Format()'' and ''Version()'' methods for your plug-in.
  
 +
<syntaxhighlight lang="cpp">
 
  class CMyLogMessage : public CLxLogMessage
 
  class CMyLogMessage : public CLxLogMessage
 
  {
 
  {
Line 18: Line 32:
 
         }
 
         }
 
  };
 
  };
 +
</syntaxhighlight>
  
 
Declare your class as a persistent object somewhere, and you can then output info and errors to the event log.
 
Declare your class as a persistent object somewhere, and you can then output info and errors to the event log.
  
 +
<syntaxhighlight lang="cpp">
 
         CMyLogMessage        my_log;
 
         CMyLogMessage        my_log;
 
         ...
 
         ...
Line 26: Line 42:
 
         my_log.Error ("Help! Something scary!");
 
         my_log.Error ("Help! Something scary!");
 
         my_log.Info ("Nevermind -- just my own shadow");
 
         my_log.Info ("Nevermind -- just my own shadow");
 +
</syntaxhighlight>
  
 
These messages will be tagged with your format and version. If you don't care for that you can compose messages more directly. It's also possible to append sub-messages in the log, which will be appear as collapsible sub-items in the event log viewport.
 
These messages will be tagged with your format and version. If you don't care for that you can compose messages more directly. It's also possible to append sub-messages in the log, which will be appear as collapsible sub-items in the event log viewport.
  
 +
<syntaxhighlight lang="cpp">
 
         my_log.Message ("CMyPlug", "MyMethod", "Multiple values already set:");
 
         my_log.Message ("CMyPlug", "MyMethod", "Multiple values already set:");
 
         my_log.SubMessage (0, 0, "Value 1");
 
         my_log.SubMessage (0, 0, "Value 1");
 
         my_log.SubMessage (0, 0, "Value 2");
 
         my_log.SubMessage (0, 0, "Value 2");
 +
</syntaxhighlight>
  
 
==== Custom Logs ====
 
==== Custom Logs ====
Line 37: Line 56:
 
By default the CLxLogMessage implementation writes to the "io-status" event log. That can be overwritten in the constructor:
 
By default the CLxLogMessage implementation writes to the "io-status" event log. That can be overwritten in the constructor:
  
 +
<syntaxhighlight lang="cpp">
 
  class CMyLogMessage : public CLxLogMessage
 
  class CMyLogMessage : public CLxLogMessage
 
  {
 
  {
Line 42: Line 62:
 
         CMyLogMessage() : CLxLogMessage ("myLog") {}
 
         CMyLogMessage() : CLxLogMessage ("myLog") {}
 
         ...
 
         ...
 +
</syntaxhighlight>
  
 
The name can be any existing log, but if the log doesn't otherwise exist it has to be declared by the server. This can be done by adding the name(s) of logs that the server wants to use to the server's tags.
 
The name can be any existing log, but if the log doesn't otherwise exist it has to be declared by the server. This can be done by adding the name(s) of logs that the server wants to use to the server's tags.
  
 +
<syntaxhighlight lang="cpp">
 
     { LXsSRV_LOGSUBSYSTEM,  "myLog" },
 
     { LXsSRV_LOGSUBSYSTEM,  "myLog" },
 +
</syntaxhighlight>
  
 
==== Direct Log System Access ====
 
==== Direct Log System Access ====
  
If the log message helper class is unsuitable or you want more control over the formatting of your events, you can access the log more directly. You initialize a log wrapper by using the allocate-by-name method.
+
If the log message helper class is unsuitable or you want more control over the formatting of your events, you can access the log more directly. You initialize a [[Log Interface|log]] wrapper by using the allocate-by-name method.
  
 +
<syntaxhighlight lang="cpp">
 
         CLxUser_Log      my_log;
 
         CLxUser_Log      my_log;
 
   
 
   
 
         my_log.setByName ("myLog");
 
         my_log.setByName ("myLog");
 +
</syntaxhighlight>
  
 
You can then allocate log entries from the service and post them to the log.
 
You can then allocate log entries from the service and post them to the log.
  
 +
<syntaxhighlight lang="cpp">
 
         CLxUser_LogService log_svc;
 
         CLxUser_LogService log_svc;
 
         CLxUser_LogEntry  entry;
 
         CLxUser_LogEntry  entry;
Line 62: Line 88:
 
         log_svc.NewEntry (LXe_INFO, "My Info Message", entry);
 
         log_svc.NewEntry (LXe_INFO, "My Info Message", entry);
 
         my_log.AddEntry (entry);
 
         my_log.AddEntry (entry);
 +
</syntaxhighlight>
  
 
Adding sub-entries is done by making the same ''AddEntry()'' call on the parent entry.
 
Adding sub-entries is done by making the same ''AddEntry()'' call on the parent entry.
  
 +
<syntaxhighlight lang="cpp">
 
         CLxUser_LogEntry  sub;
 
         CLxUser_LogEntry  sub;
 
   
 
   
 
         log_svc.NewEntry (LXe_INFO, "My Sub-message", sub);
 
         log_svc.NewEntry (LXe_INFO, "My Sub-message", sub);
 
         entry.AddEntry (sub);
 
         entry.AddEntry (sub);
 +
</syntaxhighlight>
  
 
[[Category:Usage]]
 
[[Category:Usage]]
 +
 +
== More Information ==
 +
* [[SDK]]

Latest revision as of 15:44, 30 May 2012

Status of the running plug-in can be written to the event log, either for the user or for the developer to examine debug state.

When to use the Event Log

The event log should be used to report useful state for an advanced user. It should be used relatively sparingly. Otherwise you're just going to overload the user with a flood of information.

If you choose to use the event log for debugging purposes, you should make sure that you've disabled this in shipping builds. Otherwise you will just be polluting the event log with information that isn't relevant to the user.

Things that should not go to the event log:

  • Status messages like "Plug-in has been added", or "File saved" when it's a direct result of a user's action (like saving an image or scene).
  • Errors from commands (use the command's ILxMessage (CLxUser_Message) interface instead, obtained via the command's basic_Message() method).
  • Progress updates (use ILxMonitor (CLxUser_Monitor) instead).

Using the Event Log

CLxLogMessage

This utility class is the easiest way to write to the log, although it was designed for file I/O and still has some of that legacy. You need to declare your own sub-class which implements the Format() and Version() methods for your plug-in.

 class CMyLogMessage : public CLxLogMessage
 {
     public:
         const char * GetFormat ()
         {
                 return "My Format";
         }
 
         const char * GetVersion ()
         {
                 return "My Version";
         }
 };

Declare your class as a persistent object somewhere, and you can then output info and errors to the event log.

         CMyLogMessage        my_log;
         ...
 
         my_log.Error ("Help! Something scary!");
         my_log.Info ("Nevermind -- just my own shadow");

These messages will be tagged with your format and version. If you don't care for that you can compose messages more directly. It's also possible to append sub-messages in the log, which will be appear as collapsible sub-items in the event log viewport.

         my_log.Message ("CMyPlug", "MyMethod", "Multiple values already set:");
         my_log.SubMessage (0, 0, "Value 1");
         my_log.SubMessage (0, 0, "Value 2");

Custom Logs

By default the CLxLogMessage implementation writes to the "io-status" event log. That can be overwritten in the constructor:

 class CMyLogMessage : public CLxLogMessage
 {
     public:
         CMyLogMessage() : CLxLogMessage ("myLog") {}
         ...

The name can be any existing log, but if the log doesn't otherwise exist it has to be declared by the server. This can be done by adding the name(s) of logs that the server wants to use to the server's tags.

    { LXsSRV_LOGSUBSYSTEM,  "myLog" },

Direct Log System Access

If the log message helper class is unsuitable or you want more control over the formatting of your events, you can access the log more directly. You initialize a log wrapper by using the allocate-by-name method.

         CLxUser_Log       my_log;
 
         my_log.setByName ("myLog");

You can then allocate log entries from the service and post them to the log.

         CLxUser_LogService log_svc;
         CLxUser_LogEntry   entry;
 
         log_svc.NewEntry (LXe_INFO, "My Info Message", entry);
         my_log.AddEntry (entry);

Adding sub-entries is done by making the same AddEntry() call on the parent entry.

         CLxUser_LogEntry   sub;
 
         log_svc.NewEntry (LXe_INFO, "My Sub-message", sub);
         entry.AddEntry (sub);

More Information