May 4, 2012

Rough Ideas

On April 25th I had a first chat with my mentor. First, we got to know each other a bit. We then started to talk about the project. We agreed that I will post the results of our weekly meetings on this blog.

My next steps are to
  1. get familiar with git,
  2. start working with my fork of the sapphire framework and
  3. flesh out my project plan in more detail.
In this post, I will summarize my current understanding of the things I talked about with my mentor in our first chat.

In my original proposal I talked about a toolbar. This term is usually used for one or more rows of icons, but my toolbar will also contain other information, such as debug output. Therefore, I will talk about a dashboard instead. This dashboard contains several tabs, any tab can be a toolbar (in the conventional sense).

Debugging vs. logging

In the context of my project "debugging" will be short for "displaying debug information". Of course there is much more to debugging (like the ability to set breakpoints, inspect variables and to step through code, etc.), but this is excluded from the project. Logging is a more general form of displaying debug information, I will therefore treat debugging as a special type of logging.

Debugging is mostly concerned with what happens within one request. The data is usually displayed but not kept around. Logging is used to check for things that change between different requests. Debugging will therefore be concerned with things like displaying the values of variables, checking if a statement is reached ("I'm here") and viewing the generated SQL statements.

Logging is more about aggregating information from multiple requests to check if everything works, and what changes in a case that triggers a bug.

Role within SilverStripe

The project will touch several parts of sapphire (the SilverStripe framework). I will unify and improve upon the existing logging functionalities.

Front End

The front end part is the "developer dashboard". When a site is in development mode and an administrator is logged on, a button is displayed on the front end. If the admin clicks on this button, the dashboard opens. It contains tabs that display information, such as the output of debug statements, the contents of $_GET and $_POST and SQL queries. It also contains an easily way to access the urlvariabletools. This might be in form of a toolbar, i.e. a list of icons.

Some of the content and settings will have to be persisted in some way, to be available across different requests. This could be done in a log file or in the user session.

When dumping objects, it would be very nice to be able to
  • expand and collapse branches and to
  • explore their relations.
An open question is how to debug AJAX requests. One way of doing this would be to open a separate browser window that automatically refreshes to display lines added to the log, similar to the tail -f command in UNIX.

Grouping Information

In most cases, we would want to group information by type. All SQL statements are on the "SQL" tab, debug output is on the "Debug" tab, etc.
In some cases, however, it would be useful to have all information in one place. This would make it easier to see which value of a variable results in which SQL statement. I am not sure how well this fits with the way I imagine the toolbar to work.

Back End

The project basically breaks up into two parts. The first is responsible for collecting and displaying information for logging and debugging. The second part is the infrastructure that allows modules to add information to the developer dashboard.

Logging

One aim of this project is to unify the existing logging functionality, which is spread around SS_Log, Debug as well as many other places. Like the existing logging system, this will be based on Zend_Log.

One question is how feasible it is to generalize debugging/logging of objects. Dumping should be relatively straightforward, but in many cases it would be interesting to display only the relevant parts of an object's state. Usually only the object itself knows which information is most relevant in the current context.

Logging is possible on various levels (e.g. warn, info, debug), and the developer is able to configure the required level of detail on a per module basis, e.g. LoggerClass::setLogLevel('MyModule', LoggerClass::LEVEL_DEBUG).
So far I haven't had a look at the new way configuration is done in SS3, so the way that this works might be actually a little different. Regardless of the way configuration is done, a developer will be able to specify which type of information he is currently interested in.

Dashboard

The dashboard should in principle be agnostic of the rest of the logging functionality. It is a thing that displays information. Any module can display information on this dashboard. The urlvariabletools could add icons to a toolbar. The database driver could add the SQL tab. A custom module could add another tab.

Therefore, we need an API that allows modules to add tabs and content to the dashboard.

In between

Some things are needed in between these two parts. I currently think about:
  • A way to register URL parameters. Per module this can be done in the controller, but I don't know how "global" URL paramters, like isDev are currently handled.
  • A way to persist settings in the user session. Some of the global settings should be persisted. This way, a developer can navigate the site without having to apply a certain parameter to every URL.
  • Some general code to dump an object.
  • And probably many other things I overlooked.

Personal Notes

I am still trying to grasp the whole project, to come up with a list of the features that are needed and how they relate to the existing framework. It is quite difficult for me to turn the high level ideas into "bullet points", i.e. break them up into tasks and milestones.
For me, the front end features are much more tangible. Therefore, they are much easier to think and talk about. The back end components are much more vague.

2 comments:

  1. Hey Jakob, thanks for your elaborate posts, very interesting to follow! In terms of grouping logs, have you seen the DBProfiler module? https://github.com/amoebas/silverstripe-dbprofiler
    It groups duplicate SQL queries, which allows a quick overview of how often things are queried. Might be a bit out of scope for your project, but something to consider at least - particularly in terms of passing semi-structured data like the millisecond timings for each query into the log.

    ReplyDelete
  2. I'll have a look at that. Thanks for all your comments!

    ReplyDelete