David Le Mesurier writes:<\/p>\n
Hi Lisa,
\nI have been looking at your log4fox<\/a> code as I want to instrument my applications.
\nBasically I want to be able to instrument them at a client’s site by setting an ini file setting to turn on the code.
\nI don’t want the user to have to do anything other than tick a box in my application’s preference form.
\nTo log it to a table, what do I need to set in the application to:<\/p>\n\n
- A. Instantiate the logging object to log to the table<\/li>\n
- B. Make a call to the logging code.<\/li>\n<\/ul>\n
I have looked at the sample prg, but I’m afraid that I can’t seem to get my head around what is needed.<\/p><\/blockquote>\n
<\/h4>\n
And it’s no wonder<\/h4>\n
Sorry David, this is entirely my fault.<\/p>\n
Not because the code I published had any bugs in it; it’s perfectly fine.\u00a0 But, when I wrote that article<\/a> and published the test program<\/a>,\u00a0I was interested in\u00a0showing the depth and breadth of a complex API, and maybe this doesn’t show you how you’d call the logging API in real life.<\/p>\n
There were a couple of other details, now that I look at it, that could be improved or further explained, to help David use the API according to his specification:<\/p>\n
\n
- I didn’t include an Appender class that logs to a Fox table.\u00a0 I did include a SQL Appender, but it addresses an external\u00a0table using a handle to a SQL connection.<\/li>\n
- The SQL Appender I wrote didn’t (and I really didn’t have any reason for this, other than performance\/efficiency) write individual rows to a table.\u00a0 It accumulated log events and then wrote the whole log to a text value (much like a stored version of the file you get from the File Appender) when you closed the log.<\/li>\n<\/ul>\n
Maybe it wasn’t clear in the article that writing other Appenders and Formatter objects, if necessary, is really easy.<\/p>\n
You’re not likely to need to write Formatters very often, but there isn’t much required if you do.\u00a0 To write an Appender, you really only have to implement one required method, as the article does explain: the .SendLog method that actually addresses your chosen output device.<\/p>\n
In many cases you will also need to implement .OpenLog and .CloseLog.\u00a0 For each of these methods you’re going to consider: what does it mean to “open”, “close” and “send” information to my output type? How do these ideas apply?<\/p>\n
The ideas of .Open and .Close don’t apply to every output type; for example an Appender that wrote to _SCREEN might decide to CLEAR the _VFP application window and set some font properties, or it might do nothing at all.\u00a0 But .Send applies to every output, because that is the point at which the log message gets rendered.<\/p>\n
Hmmm. Anybody see a resemblance to ReportListener design questions here?<\/p>\n
You don’t need to worry about anything else.\u00a0 The Logger maintains your Appenders\u00a0and calls their .DoLog methods.\u00a0 You don’t need to touch the .DoLog method, which simply figures out whether the Appender is supposed to log this event, based on the level of log events it’s currently configured to handle.\u00a0\u00a0 The Appender base class is going to take care of all the\u00a0shared\u00a0details for you.\u00a0You only need to touch .SendLog, because your method of rendering the output device is specific to that device.<\/p>\n
I’ll write a quick Fox Cursor Appender in this post, as a kind of a walkthrough for you.<\/p>\n
The published test program instantiates many Appender objects to the Logger’s collection, to show you how they each handle log events according to their own\u00a0output types\u00a0and current logging level.\u00a0 This, by the way, is<\/em> a real\u00a0life scenario: it is perfectly normal to configure a file Appender to log verbosely while only sending Fatal-level events to an email Appender.<\/p>\n
<\/h4>\n
How does the Logger figure out what Appenders your user wants, and what their levels should be?<\/h4>\n
In the article, I addressed\u00a0configuration by deriving a specialized class from\u00a0Log4Fox, which I called Log4FoxConfigAlias.\u00a0 The idea here was that the logger would read a configuration table or cursor, to which you’d point it by telling it the alias containing this information.<\/p>\n
The published test program creates that cursor on the fly, with a bunch of records holding instructions about different Appenders.\u00a0 Then it creates a Log4FoxConfigAlias Logger instance, and tells\u00a0the new object\u00a0about the cursor.\u00a0 The Log4FoxConfigAlias instance reads the cursor, adds the Appenders to its collection, and configures them, based on the records in that cursor.<\/p>\n
David could use Log4FoxConfigAlias if he wants.\u00a0 In fact, he might even instantiate it on-the-fly, as I did, using information from his INI file.\u00a0 But he could also derive a different class, Log4FoxConfigFromINI, which would read his INI file directly.<\/p>\n
In this blog-walkthrough, I won’t do either one.\u00a0 I’ll just use the ancestor Logger class, Log4Fox, which doesn’t know how to do any configuration.\u00a0 I’ll do some work in the calling program that you’ll have to imagine is being done by your startup code, or your Application object, or however you<\/em> normally do this type of thing.<\/p>\n
Sidebar: VFP\u00a0Helper Object techniques<\/h5>\n
Again, I don’t want to over-complicate things here, but you may want to remember that all these objects are derived from an ancestor called VFPHelperObject.<\/p>\n
This\u00a0class’ raison d’\u00eatre\u00a0— which really has nothing to do with Log4Fox or log4j — is to help you integrate a library like this one into your overall application strategy.
\nVFPHelperObject expresses this principle by handing off error-handling behavior to its “owner object” — presumably your application object — so that its behavior matches the rest of your code when an error occurs.<\/p>\nIn the calling program here, and in the published test program, I have to explicitly turn off that behavior, since there is no external owner object.\u00a0 But I hope you can see how useful this practice can be, when you’re assembling a full-scale application from a bunch of pre-built and externally-designed components.<\/p>\n
Now for that walkthrough<\/h4>\n
David wants to know how to log to a table.\u00a0 Well, first you need an Appender that knows how to log to a (presumably Fox) table.<\/p>\n
I didn’t write one of those before, so I’ll do one now, and this time it will log each event to a separate row in the table rather than writing the full log to a memo field, as I did in the SQL Appender before.<\/p>\n
For this walkthrough I’ll specify as follows:<\/p>\n
\n
- You tell the Appender where to log by telling it what alias to use. You also tell the Appender in what DataSession the Appender should find the LogAlias (I figure most people use an Application object with a private data session for work like this)<\/li>\n
- Because this Appender is writing separate rows to the table for each event, you should be able to find the Open and Close events in the table easily.\u00a0 However, we’ll add a member property to the Appender called LogRunName, because multiple instances of the application may be writing to the same table, and we’ll include this value in a separate column of the LogAlias table.
\nFor this walkthrough, I’ll use GETENV(“UserName”) to distinguish rows between different users logging to a network table, which would work if the application was a singleton for each user — you could also generate a unique key for this purpose.<\/li>\n- The Appender will expect, and validate, a LogAlias structure that\u00a0looks like this:
\nCREATE CURSOR <\/span>(THIS<\/span>.LogAlias) ;
\n(event_run char<\/span>(50), event_date datetime<\/span>, event_log varchar<\/span>(250))<\/li>\n<\/ul>\nReady?<\/p>\n
DEFINEing Class log4FoxCursorAppender AS log4FoxAbstractAppender<\/h5>\n
<\/p>\n
What will our new Appender class need to do?\u00a0 Well, it’s going to need a few member properties, matching our specification:<\/p>\n
LogDataSession = 1
\nLogAlias = “EventLog”
\nLogRunName = “Log Run Name”<\/p>\nRemember what I said before? There’s definitely\u00a0one method we have to implement: .SendLog.\u00a0\u00a0 It will look like this:<\/p>\n
PROTECTED PROCEDURE <\/span>SendLog(whatever)
\nIF THIS<\/span>.LogOpen
\n\u00a0\u00a0\u00a0\u00a0\u00a0 LOCAL <\/span>iSession
\niSession = SET<\/span>(“DATASESSION”)
\n\u00a0\u00a0\u00a0\u00a0\u00a0 SET DATASESSION TO <\/span>(THIS<\/span>.LogDataSession)
\nINSERT INTO <\/span>(THIS<\/span>.LogAlias) VALUES <\/span>;
\n(THIS<\/span>.LogRunName, DATETIME<\/span>(), whatever)
\nSET DATASESSION TO <\/span>(iSession)
\n\u00a0\u00a0\u00a0ENDIF<\/span>
\nENDPROC <\/span><\/p>\n… really only a few obvious lines of code.<\/p>\n
You may think the check for .LogOpen is unnecessary (why isn’t this behavior somewhere else, like .DoLog in the ancestor class?). But some output destinations don’t really have a need for the concept of a log being opened at all.\u00a0 SQL Appender, for example, doesn’t care whether you’ve previously opened a log by checking for a handle; it can accumulate contents and open the log later, if it wants.\u00a0 What a log being “open” means, and whether you care about it, as well as at what <\/em>moments you care about it, is highly dependent on output device, and therefore is handled by each Appender.<\/p>\n
In this<\/em> class, THIS.LogOpen means that the class has previously checked for its alias and either verified its structure or opened a cursor with the right structure, in the correct data session, of course.<\/p>\n
So how do you suppose it does\u00a0that?\u00a0 Let’s look at the rest of the class code, which is similarly straightforward:<\/p>\n
PROCEDURE <\/span>OpenLog()
\n* Let’s set some values here that probably<\/span>
\n* aren’t useful to expose, since this
\n* class is always going to want them set
\n* a certain way.
\n* If you create a different Formatter (Layout)
\n* object you probably will have different need
\n<\/span>THIS<\/span>.Layout.IncludeDateTimeStamp = .F. && because this Appender<\/span>
\n&& has a separate column for it
\n<\/span>THIS<\/span>.Layout.IncludeLogEvent = .T.<\/p>\n\u00a0\u00a0 * in real life you would probably expose *this*<\/span>
\n* one, or else generate a unique key for the run here: <\/span>
\n\u00a0\u00a0 THIS<\/span>.LogRunName = “Log run: ” + GETENV<\/span>(“UserName”)<\/p>\n\u00a0\u00a0 IF THIS<\/span>.loglevel < LOGLEVEL_NONE
\n\u00a0\u00a0\u00a0\u00a0\u00a0 LOCAL <\/span>iSession, iSelect,iArea
\niSession = SET<\/span>(“DATASESSION”)
\n\u00a0\u00a0\u00a0\u00a0\u00a0 SET DATASESSION TO <\/span>(THIS<\/span>.LogDataSession)
\niSelect = SELECT<\/span>(0)
\niArea = SELECT<\/span>(THIS<\/span>.LogAlias)
\nIF <\/span>iArea > 0 AND THIS<\/span>.ValidateLogCursor(iArea)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 SELECT <\/span>(THIS<\/span>.LogAlias)
\nELSE<\/span>
\nIF iArea > 0
\n<\/span>USE IN <\/span>(iArea)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ENDIF
\nSELECT <\/span>0
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 CREATE CURSOR <\/span>(THIS<\/span>.LogAlias) ;
\n(event_run char<\/span>(50), ;
\nevent_date datetime<\/span>, ;
\nevent_log varchar<\/span>(250))
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0ENDIF
\nTHIS<\/span> .LogOpen = .T.
\n\u00a0\u00a0\u00a0\u00a0\u00a0 SELECT <\/span>(iSelect)
\nSET DATASESSION TO <\/span>(iSession)
\n\u00a0\u00a0\u00a0\u00a0\u00a0 THIS<\/span>.DoLog(THIS<\/span>.GetStandardLogOpenedMessage(),LOGLEVEL_INFO)
\nENDIF<\/span>
\nENDPROC <\/span><\/p>\nPROTECTED PROCEDURE <\/span>ValidateLogCursor(iArea)
\n\u00a0\u00a0 * validate to suit your needs<\/span>
\nRETURN <\/span>;
\n\u00a0\u00a0 LEN<\/span>(FIELD<\/span>(“event_run”,iArea)) > 0 AND ;
\nLEN<\/span>(FIELD<\/span>(“event_date”,iArea)) > 0 AND ;
\n\u00a0\u00a0\u00a0LEN<\/span>(FIELD<\/span>(“event_log”,iArea)) > 0
\nENDPROC<\/span><\/p>\nPROCEDURE CloseLog()
\n\u00a0\u00a0 IF THIS<\/span>.LogOpen
\n\u00a0\u00a0\u00a0\u00a0\u00a0 THIS<\/span>.DoLog(THIS<\/span>.GetStandardLogClosedMessage(),LOGLEVEL_INFO)
\n\u00a0\u00a0\u00a0\u00a0\u00a0 * we won’t close the cursor, we’ll just indicate that
\n* something\u00a0in the calling code decided to close the
\n* log at this moment.\u00a0 It isn’t necessarily the end
\n* of an application run; perhaps there is going to be
\n* some activity that doesn’t need to be logged.<\/span><\/p>\n* What will *your* class do when you decide it’s
\n* time to close the log?
\n* You might decide it’s a good time to
\n* run a report form on the log contents,
\n* if you are in LOGLEVEL_DEBUG…
\n* you might store the contents of the cursor
\n* to a SQL table…<\/p>\n* Of course you could perform that activity
\n* at a different time, using a separate
\n* public method.<\/p>\nTHIS<\/span>.LogOpen = .F.
\n\u00a0\u00a0 ENDIF
\nDODEFAULT<\/span> ()
\nENDPROC\u00a0\u00a0\u00a0<\/span><\/p>\n… and that’s the whole class.<\/p>\n
Note: I will be adding this class to the log4fox.prg in the standard article download, and I will also add the code for the sample invocation of the class, that we’ll look at next.<\/p>\n
How do we instantiate it at runtime?<\/h5>\n
David wants to know how to “instantiate the logging object to log to the table”.<\/p>\n
You do that by creating a Log4Fox object (or a derived class, such as Log4FoxConfigAlias) and ensuring that it has an Appender in its collection that knows how to log to a table.\u00a0(We have one of those now.)<\/p>\n
If we’re using Log4FoxConfigAlias as our Logger object, as I did for the article, we can put a row in Log4FoxConfigAlias’s configuration table that says we want our new Appender.\u00a0 Log4FoxConfigAlias does this work in its Configuration_Assign method.\u00a0 As I explained in the article, it just has to instantiate each Appender object in its table and pass the Appender a reference to itself.<\/p>\n
<\/p>\n
loX = CREATEOBJECT<\/span>(ALLTRIM<\/span>(logger), THIS<\/span>)<\/p>\n
<\/p>\n
… the Appenders know how to add themselves into the Logger’s collection.\u00a0 (Remember: these two object types are tightly coupled.)<\/p>\n
Log4FoxConfigAlias passes other information to each Appender it creates, too, using information in its configuration table: for example, it tells each\u00a0Appender what level of log events it should include.<\/p>\n
If David writes a Log4FoxConfigINI derived class that looks in an INI file, it will do pretty much the same thing, using the INI file instead of a table for its resource.<\/p>\n
However, David doesn’t really have to do that.\u00a0 He can use the ancestor\u00a0class Log4Fox if he wants, and that’s what I’ve done in the simple DAVID_LOG4FOX.PRG:<\/p>\n
loLogger = NEWOBJECT<\/span>(“Log4Fox”,”Log4Fox.PRG”,””,NULL<\/span>,.T.)
\n*&* but ordinarily this object would belong to an owner, like so:
\n*&* loLogger = CREATEOBJECT(“Log4Fox”,THIS.Application,.F.) <\/span><\/p>\n… and then he can (presumably, having read some information from his INI file externally) add the Appenders he’d like to use to his Logger object, and configure them as needed,\u00a0like this:<\/p>\n
NEWOBJECT(“log4foxEmailAppender”,”Log4Fox.PRG”,””,loLogger) <\/span>
\nNEWOBJECT<\/span>(“log4foxCursorAppender”,”Log4Fox.PRG”,””,loLogger) <\/span><\/span>&& new!<\/span><\/p>\n* read from configuration info here<\/span><\/p>\n
* for now I’ll suggest some useful values that
\n* aren’t actually being read from anywhere, but
\n* obviously could be<\/p>\n* I am going to assume that David wants
\n* his application preference form
\n* to write to the INI with this or
\n* any other information this class needs, but
\n* I’ll skip that part too.<\/p>\nFOR EACH loX <\/span>AS FoxOBJECT IN loLogger.Appenders
\nloX.SetLogLevel(LOGLEVEL_DEBUG)
\n<\/span>ENDFOR<\/span> <\/span><\/p>\n<\/h5>\n
How do I\u00a0 log stuff?<\/h5>\n
<\/p>\n
This was David’s last question, and it’s probably so<\/em> simple he just didn’t believe it.<\/p>\n
You’ve got your Logger object, and you just tell it to log whenever you feel like it.\u00a0 You forget all about the mechanics about how each Appender will output the logging information, and how each Appender’s Formatter object will construct the information to be sent to the Appender’s output device.<\/p>\n
You just instrument your code with calls that look like this:<\/p>\n
loLogger.OPEN<\/span><\/span>() && or MyApplicationObject.Logger.OPEN(), etc<\/span>
\n<\/span>loLogger.LOG<\/span><\/span>(“This is a test at level LOGLEVEL_INFO”, LOGLEVEL_INFO)
\nloLogger.LOG<\/span><\/span>(“This is a test at level LOGLEVEL_FATAL”, LOGLEVEL_FATAL)
\nloLogger.CLOSE<\/span><\/span>()<\/p>\n… honestly, that’s all you have to do.<\/p>\n
The .Open call will cause each of the Appenders to do whatever it needs to do to initialize a log run (some Appenders will need to do a lot of work, some will do none.)<\/p>\n
The first .Log call above will be logged by any Appender that successfully initialized its device and is set to log events all the way down to the “info” level, which is pretty verbose.<\/p>\n
The second .Log call above will be logged by pretty much any Appender that successfully initialized, considering that it’s hard to imagine wanting any Appender not wanting to include a “fatal” level event in its log.<\/p>\n
Okay?<\/h5>\n
<\/p>\n
Did I leave anything out?<\/p>\n
I did tell David that I generally use XML configuration files, rather than INIs or configuration tables.\u00a0 In a follow-up post, he asked me, “What sort of stuff does the xml config file contain”?\u00a0 Here’s a simple example:<\/p>\n
<log4j:configuration xmlns:log4j=”http:\/\/jakarta.apache.org\/log4j\/”><\/p>\n
<appender name=”appender” class=”org.apache.log4j.FileAppender”>
\n<param name=”File” value=”Indentify-Log.txt”\/>
\n<param name=”Append” value=”false”\/>
\n<layout class=”org.apache.log4j.PatternLayout”>
\n<param name=”ConversionPattern” value=”%d [%t] %p – %m%n”\/>
\n<\/layout>
\n<\/appender><\/p>\n<root>
\n<priority value =”debug”\/>
\n<appender-ref ref=”appender”\/>
\n<\/root><\/p>\n<\/log4j:configuration>
\nBut I don’t have to explain it.\u00a0 You can read many, many, beautifully detailed explanations of the architecture written by other people about log4j, log4net, or any of the other variants, and get an idea of how such a configuration file exposes the API’s features; I really did follow the log4j principles in my VFP implementation, albeit in a simplified form.<\/p>\nNote: log4j also allows configuration programmatically, or by “property files”, which are similar to INIs.\u00a0 You can see an extensive example of a log4j property file here<\/a>.<\/p>\n
Have event-filled, and fully-loggable, fun.<\/p>\n","protected":false},"excerpt":{"rendered":"
David Le Mesurier writes: Hi Lisa, I have been looking at your log4fox code as I want to instrument my applications. Basically I want to be able to instrument them at a client’s site by setting an ini file setting to turn on the code. I don’t want the user to have to do anythingRead more<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[9],"tags":[],"class_list":["post-114","post","type-post","status-publish","format-standard","hentry","category-visual-foxpro"],"_links":{"self":[{"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/posts\/114","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/comments?post=114"}],"version-history":[{"count":2,"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/posts\/114\/revisions"}],"predecessor-version":[{"id":392,"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/posts\/114\/revisions\/392"}],"wp:attachment":[{"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/media?parent=114"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/categories?post=114"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/spacefold.com\/lisa\/wp-json\/wp\/v2\/tags?post=114"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}