L4NDash - Help (DataSource: XML Text file)

LOG4NET Dashboard Version: 2.2 © faktnet.com

Help

Show help on pages

The Dashboard Page

Purpose

The Dashboard page is the most used page in the application, most users bookmark this page and use it as the starting page.

On the Dashboard page you can:

Get an overview of the logging events available in the logging table.
Drill down to see the logging evens within the category / time frame of your interest.
Narrow one a single logging event, by choosing a row.
Define a global filter

How to use

The summary table gives you an overview. Cells, row heading and column heading are selectable. If you click in a cell logging evens within this cell will be displayed. If you click in a column heading all logging evens for the cells in this column will be displayed, likewise if you click in a row heading.
In the Log Rows table, you can select a logging event (row) to display the details about this logging event.
If the Log Rows table contains more than one page of rows, you can move between the pages with the "previous page" and "next page" buttons on the bottom of the table.
You may create a filter to fine grain your search, a filter will have impact from the summary table and when drilling down. The filter may be created for one ore more log columns. Each column filter is defined through choosing a filter type (“Starts with”, “Contains”, “Ends with” and “Equal to”), and specifying a text to match according to the filter type.

New's log events

Purpose

Use this page to get a snapshot of the latest (new's) log events.

How to use

You can select number of rows to retrieve from the database and the number of rows to shop on one page.
In the Log Rows table, you can select a logging event (row) to display the details about this logging event.
If the Log Rows table contains more than one page of rows, you can move between the pages with the "previous page" and "next page" buttons on the bottom of the table.
You may create a filter to fine grain your search.

Filter

You may create a filter to fine grain your search; a filter will have impact in the Dashboard page and in the New log event’s page.

On log levels, a filter is defined through choosing the log levels to include, putting check marks next to level. Default is that all levels included.

On Logger, Thread, Message and Exception a filter is defined through defining a filter text, and choosing a filter type:

Starts with: The text in the column must start with the same text as in the filter.
Contains: The text in the column must contain the same text as in the filter.
Ends with: The Text in the column must ends with the same text as in the filter.
Equal: The text in the column must exactly match the text as in the filter.

On the right side of the Logger and Thread input fields is a right arrow, clicking this will give you a list of possible values (i.e. a distinct collection of values that exists in the log table). You can click on a value in the list to copy it to the filter input field.

In the top of the panel you can have a drop down with predefined filters (that is if any filters are predefined), by selecting a predefined filter, all the input fields will be filled accordingly to the content of the predefined filter. You may change the content of the different input field before you click the use button.

If you want to create a predefined filter, you can put a check mark in the SaveAs check box and specifying a name. The values of the input fields will then be saved to a predefined filter.

The predefined filters are saved to an xml file which is stored in the Filters folder (in the application directory). The filters can be stored per data source. This means that you can have different predefine filters for each data source (The name of the file is defined in the web.config file).

The Clean Up page

Purpose

On the Clean up page you can:

Get an overview of the size of the log table, i.e. how much space is occupied in the database, and the distribution of the space used among the different log levels.
Decide which log-rows are obsolete, and delete them.

How to use

Select the time frame, you can choose among several predefined intervals or specify a date. In the later rows older than the date specified will be deleted.
Select the log levels you will delete. You may choose to delete several log levels, or only one.
Click the checkbox (Delete log rows from the database) and click the Execute button.

The Settings Page

Purpose

On the Settings page you can:

Select the style-sheet you prefer. Style sheets are kept in the StyleSheet subdirectory. Based on the style-sheet files defined in this directory you may also define your own. If you save your personal style-sheet in the StyleSheet subdirectory it will be populated into this page and made available for users to use.
Select the data source L4NDash use. Some development organizations prefer to keep the log table for different projects separated. It is therefore possible to configure several data sources in L4NDash. The available data sources are defined in the web.config file.

How to use

Select the style-sheet you prefer from the style-sheet list box.
Select the data source you will use form the data source list box.
If you want L4NDash to remember your settings until next time you use L4NDash, check the check box � Remember settings�� L4NDash will then create at cookie on our computer to store your settings in.
If you only want to change the settings for the current session, leave the �Remember check box� blank.
Click the Save button

Setup

1. System requirements (L4NDash version 2.2)

Internet Information Server
Microsoft SQL Server (only if you are using SQL Server as logging storage).
One MB free disk space
.Net Framework version 2.0

2. Run the setup program

The setup program will install the L4Ndash application, and create a virtual directory in Internet Information server.

If you are upgrading from a previous version, please install to a new directory, do not upgrad an old version. After innstallation migrate your settings from the old web.config to the new web.config file.

3. Configuration of L4NDash / Modify the web.config file

The web.config file of L4NDash controls the behavior of the application, and it gives you a lot of possibilities to change and customized L4NDash.

Define new data sources
Change the periods used in the summary table
Change the appearance of column values that are retrieved form the log
Define custom columns you want to display

Customizing the SummaryTable in the Dashboard page

The summary table in the dashboard page is defined in the web.config file under the <l4ndash> section. Each row in the summary table is define through a <summarytableperiod Name="periodname"> section, as shown in the example below:

<summarytableperiod name="Last Hour"> 

   <comment value="Shows events for the past hour"/>

   <timediff value="1" valuetype="hour" start="now"/>

</summarytableperiod>

The parameter timedif defines the timespan for the period by specifying value (a numeric value) and valuetype (hour, day, month and year).
The start of the period is defined in the start attribute of the tiediff, the start attribute can be one of the three values "now", "previousperiodstart" and "previousperiodend".
The default definition of the summary table in the web.config file, is a good starting point for understanding how to customize the table.

Defining data sources

For most users it is sufficient to define one data source, however L4NDash gives you the possibility to define several data sources, the first data source will be the default. In the settings page the user can choose to use one of the others.

The data sources is defined in the <l4ndash> section, for each data source you must define a <datasource> section. Currently L4NDash is capable to read log events form:

Microsoft SQL Server
Windows Event Log
Text file (containing log events formated with the log4net.Layout.XmlLayout).

You may of course define several data sources per datasource type, for example if you have several applications logging to several different log storages.

The different data source types, are implemented through a provider interface. This gives you or other the possibility to program new providers for any kind of logs you need to view through the Dashboard.

One definition of a datasource can contain several sub sections:

Parameters for defining the data source provider
Provider parameters
Custom columns
Visualizers

Generalized the data source section can look like:

<datasource name="DataSourcUniqueName" Description="Data source description">



   <provider type="typename" assembly="assembly refernec"/>

   <predefinedsearchfilter value="relativ path to the fil storing predefined filters"/>

   <providersettings>

      <!-- provider dependent settings parameters -->

   </providersettings>



   <customcolumns>

      <customcolumn name="Columnname">

         <label value="label value"/>

        <rowstabledisplay value="yes|no"/>

        <rowsdetaildisplay value="yes|no"/>

        <filter value="yes|no"/>

      </customcolumn>



      <!-- more custom columns -->



   </customcolumns>



   <columnvisualizers>

      <visualizer Columnname="Date">

         <provider type="typename" assembly="assembly refernec"/>

         <providersettings>

            <!-- provider dependent settings parameters -->

         </providersettings>

      </visualizer>



      <!-- more visualizers -->



   </columnvisualizers>





</datasource>

If you need to define several data source, you create several <datasource> sections, the first section will be the default data source, and the one L4NDash display when a user opens l4ndash. The user can choose another datasource and save the choice as a client cookie (see the settings page).

A configuration section for one data source must always include

<datasource name="Unique name" Description="Description of the datasource">

   <provider type="providerclass (type)" assembly="assembly reference"/>

   <providersettings>

      <!-- provider dependent parameteres -->

   </providersettings>

The SqlServer provider

The SqlServer provider reads log rows from a SqlServer database.

<datasource name="LocalSql" Description="Log4Net log rows stored in SQLServer">

   <provider type="L4NDashSqlServerProvider.SqlServerProvider" 

      assembly="L4NDashSqlServerProvider, Version=2.2,Culture=neutral"/>

   <providersettings>

      <connectionstring 

       value="Data Source=(local); initial Catalog=Log4Net;Integrated Security=True;"/>

      <tablename value="Log4Net"/>

      <SqlCommandTimeout value="60"/>

      <MaxNoOfRowsToRetrieve value="1000"/>

   </providersettings>




</datasource>

The Log table (the table named in the table name parameter) must contain the standard log4Net columns (i.e. Id, Date, Logger, Thread, Message and Exception), in addition you can of course define custom columns.

The TextFile provider

The TextFile provider reads log rows from a text file. The text file must be created/generated from Log4Net using the "log4net.Layour.XmlLayout".

<datasource name="LocalXMLFile" Description="Local XML file">

   <provider type="L4NDashXmlTextFileProvider.XmlTextFileProvider" 

      assembly="L4NDashXmlTextFileProvider, Version=2.2, Culture=neutral"/>

   <predefinedsearchfilter value="Filters\DefaultSearchFilters.xml"/>

   <providersettings>

      <filename value="c:\Logs\Log.xml"/>

      <cachetime value="3600"/>

   </providersettings>





</datasource>

For the TextFile provider the cach time can be high. The provider will add new log rows form the text file to the cache if the text file is altered.

Below is a example of a log4net appender definition that will produce a log file compatible with the L4NDash text file provider.

<appender name="FileAppender" type="log4net.Appender.FileAppender">

   <file value="c:\\Logs\\Log.xml"/>

   <appendToFile value="true"/>

   <locationinfo value="false"/>

   <layout type="log4net.Layout.XmlLayout">

   <   param name="Prefix" value=""/>

   </layout>

</appender>

The Windows Events provider

The Windows Event Log provider reads log rows form the windows event log. This provider is not restricted to deal with log rows generated from Log4Net but can show all log events form the Windows event log.

<datasource name="LocalEventLog" Description="Windows event log">

   <provider type="L4NDashEventLogProvider.EventLogProvider" 

      assembly="L4NDashEventLogProvider, Version=2.2, Culture=neutral"/>

   <providersettings>

      <machinename value="."/>

      <logname value="system;application;security"/>

      <cachetime value="60">

   </providersettings>

The machinename points to the machine to fetch the event log from use . (period) to fetch the log from the local machine.
The log name is a ; (semicolon) separated list of the logs you want to make available in L4NDash, the default names on the logs are system, application and security. Reading the security logs usually requires a user with more rights.
The cachetime decides how often the provider will refetch the data from the log.

Using predefined search filters

For all data sources it is possible to define a file containing predefine search filters. The file can be updated from the filter panel in the application.

Storage for predefined filters is done through using the parameter <predefinedsearchfilter value="Filename">

The path is relative to the application directory.

It is possible to store predefined search filters from several datasources on the same file.

Adding custom columns

It is common to log custom columns in addition to the standard columns (Date, Level, Logger, Thread, Message and Exception). This paragraph explains how you setup L4NDash to display these columns.

Custom columns are defined in the web.config file, and they can be defined different for each data source. The definition of custom columns is therefore added to the data source definition in the web.config file. The generalized web.config syntax for this is shown below:

<datasource ........>

	



   <customcolumns>

      <customcolumn name="MyDatabaseColumnName">

         <label value="MyLabelr" />

         <rowstabledisplay value= "yes|no" />

         <rowsdetaildisplay value= "yes|no" />

         <filter value="yes|no" />

      </customcolumn>




   </customcolumns>

</datasource>

The section <customcolumn> needs to be repeated for each column. For one column you can define the parameters:

name	The name of the column in the database.
label	The label you want to be displayed in L4NDash
rowstabledisplay	yes or no
rowsdetaildisplay	yes or no
filter	yes or no, defining if the user should be able to define a filter for the column.

In version 2.1 it was possible to define a "substing display" using the parameter format substing(99), this functionality is replaced by the Visualizer, and the paremteres defining the Visualizers.

If you, for example have three custom columns (hostname, username, useraccountdata), and you would like hostname and username to be displayed in the log table view (and in the detail pane). In addition you want the useraccountdata to be displayed in the detail pane. The hostname and username you also want to make available for filtering.

<customcolumns>

   <customcolumn name="hostname">

      <label value="Host Name" />

      <rowstabledisplay value= "yes" />

      <rowsdetaildisplay value= "yes" />

      <filter value="yes" />

   </customcolumn>

   <customcolumn name="username">

      <label value="User" />

      <rowstabledisplay value= "yes" />

      <rowsdetaildisplay value= "yes" />

      <filter value="yes" />

   </customcolumn>

      <customcolumn name="useraccountdata">

      <label value="Account information" />

      <rowstabledisplay value="no" />

      <rowsdetaildisplay value="yes" />

      <filter value="no" />

   </customcolumn>

</customcolumns>

When you restrict the display of an custom column the full column will be available if the user click the "Show message on separate page" link on the bottom of the detail pane.

If you add several columns, you may want to expand the width of the web page. To expand the width of the web page you simply need to modify the style sheet defined in the MainStyle.css file (The MainStyle.css file is located on the L4NDash web root).

The width of an L4NDash page is defined in the .Container width parameter. If you increase this you also need to reposition the help panel (which is displayed on the right hand side of a page), this is done by increasing the .HelpPanel left parameter according to the increase you did on the .Container width parameter.

Adding a visualizer

L4NDash comes with one standard visualizer assembly, this assembly contains to visualizers (a string visualizer and a datetime visualizer).

A visualizer can render a column value in 3 different ways.

Short display, this format is used in the log table panel
Medium display, this format is used in the detail panel.
Long display, this format is used when a log event is displayed on a separate page.

The Default DateTime visualizer

To define a DateTime visualizer you use the config statment:


<Visualizer ColumnName="The name of the column">

   <provider type="L4NDashDefaultVisualizer.DefaultDateTimeVisualizer" 
      assembly="L4NDashDefaultVisualizer, Version=2.2,Culture=neutral"/>

   <providersettings>

      <ShortDisplayFormat value="MM/dd/yy HH:mm:ss"/>

      <MediumDisplayFormat value="MM/dd/yyyy HH:mm:ss"/>

      <LongDisplayFormat value="MM/dd/yyyy HH:mm:ss"/>

   </providersettings>



</visualizer>

You can use the formats in the provider settings section to change how datetime vaues is formated by the Visualizer.

The Default String visualizer

To define a String visualizer you use the config statment:

<Visualizer ColumnName="The name of the column">

   <provider type="L4NDashDefaultVisualizer.DefaultStringVisualizer" 
      assembly="L4NDashDefaultVisualizer, Version=2.2, Culture=neutral"/>

   <providersettings>

      <ShortDisplayTruncate value="right"/>

      <MediumDisplayMaxLength value="500"/>

      <MediumDisplayTruncate value="right"/>

   </providersettings>



</visualizer>

For short and medium display you can truncate the length of the string that are displayed. You can also define if the truncation should be done from left or right of the string.

Other parameters in the <appSettings> section

The web.config file contains additional parameters you can change:

DateTimeFormat	How date time values are displayed
DateFormat	How date values are displayed
UserInputDateFormat	Date format for user input
HelpModus	1 or 0 i.e. will help text be displayed integrated in the pages as default.
SummaryTableCacheTime	Timeout when executing SQL statements, number of seconds.
RowTableShowMessage	1 or 0 i. - Show the message column in the logrow table
RowTableWhowLogger	1 or 0 i. - Show the message column in the logrow table