Some more requirements
In our chat we came across some requirements that I had not taken into account before:- Debugging and logging should happen around streams. Each module can either write to an existing stream or start a new one. This way, a developer can pick and choose the level of debugging info he wants to receive.
- Log Streams are loosely coupled to modules by a naming convention: sapphire_sql.
- The developer needs to be able to choose what he is interested in. For that, there needs to be a list of all available streams. Therefore, any module (including the sapphire framework code itself) that can publish debug streams needs a way to say "I generate this, this and this". It should be able to tell the logging framework what streams they generate. Setup could be a matter of classes implementing an interface, or calling a method to register the stream.
- Performance: When debugging is disabled, we should cause only a low
overhead . The modules need to be aware of what streams of debugging
they should be producing. Sometimes it is expensive for modules to
generate and collect the debugging information, so they shouldn't do
anything if nobody wants to look at the result. Something like:
if(Debug::streamEnabled($streamID)) Debug::log(blah);
- Debugging info can be generated in the framework before the framework is set up. e.g. before there is a DB connection. So the mechanism should not be at too high a level of abstraction. Early parts of the request have to be able to generate debugging info too, in case the developer has enabled the streams.
- The dashboard controller could record the debug events in the session, and maybe keep the last n requests there. That way, the developer dashboard could show details across multiple requests.
- Easy way to print out debugging information. It should be as simple as calling Debug::show().
- Filtering / sorting into tabs probably has to be done client side, because a interleaved display is also possible (i.e. output from all streams, sorted by time).
Structure
Starting from these requirements, the logging framework breaks down into three components:- Registering a capability to generate debugging events.
- Capturing those debugging events while a request is processing.
- Forwarding them to the dashboard and displaying them.
For information gathering we need to come up with a way of representing objects that should be logged. The logger should be context aware and support both HTML and command line output. The functions that call the logger should not include HTML output.
Workflow
- The developer selects a control somewhere to turn on the dashboard
- The dashboard has a list of debugging streams to choose from.
- The dashboard saves the developer's preferences to his session.
- During the processing of the next requests (could be a normal page view or via AJAX), code on the execution path writes to it's debug stream (in case the stream is enabled).
- The dashboard controller sends the event data to the dashboard.
- the dashboard displays that event data in an organized way.
Setup
We discussed two versions how the setup could work:- The code that wants to have something logged can just say "put this text there" and the logging code sorts out the rest - Much like you currently add fields to the CMS back end
- Modules generate data streams.
In the initial implementation, the dashboard will use the stream identifier as the tab name. If needed, we could extend it later by separating the tab concept out from the stream identifier.
Timeline
Not all things that are discussed here might end up in the project. Nevertheless, this blog is a first step to documented them as future enhancements.Before Midterm
In the first two weeks I will work on a proof of concept (POC) implementation. It consist of an implementation of the log writer including the log() support method and a simple front end with no fancy bits. It writes the event data to a simple list in session. This will include some basic AJAX capability. Furthermore, I want to complete ticket 2644. Therefore, I will write a global error handler and provide event streams for exceptions and user errors.At the midterm goal I will have completed the POC, fleshed out the server side debugging capabilities, and a basic interaction with the front end working. This includes a view to display some of the current debugging options in the new dashboard and an expanded ajax handler to provide this additional data to the dashboard.
After Midterm
After the midterm I will be away for a week, so I only have three weeks. In the second part, I will flesh out the UI of the dashboard itself. This consist of:- organization of events by tab,
- an option to view the events sequentially (i.e. information from all tabs combined, ordered by time),
- ability to expand and collapse different parts to control the level of detail,
- ability for the developer to select the streams they want to have generated and displayed (client side UI) and
- server side preference storage - number of requests to store, which streams should be generated, etc.
- May 21st - June 3rd: Proof of Concept Implementation
- June 4th - June 17th: Server Side debugging: Reorganize the way debugging is done.
- June 18th - July 1st: Front End Interaction, include existing urlvariabletools in dashboard
- July 2nd - July 13th: Finish leftovers from previous tasks, start working on frontend UI
- July 13th: Mid term
- July 15th-July 21st: Not working on GSOC
- July 22nd-August 5th: Work on frontend UI
- August 6th-August 9th: Cleanup
- August 9th: Pencils down
- August 10th-August 19th: Not working on GSOC