Location: PHPKode > scripts > sLog > sLog-0.8/README.txt
sLog v0.8
copyright (c) 2008 Kjell-Inge Gustafsson, kigkonsult
www.kigkonsult.se/slog
hide@address.com

DESCRIPTION
===========
A mysql (5.x) log database logging events in a single/multi system/application
environment. Written completely as mysql stored procedures with a secure simple
log interface using direct access to database or via a web/soap service.

sLog logs application and system events, keeping track of user, client, applica-
tion, application module, operation, date and time and event/log specifics.

Logging is done with a simple direct mysql call (stored procedure), no coding
required apart from coding database connection and call. Logging can also be
done by doing http or SOAP requests, PHP examples attached.

Database structure is completely hidden from user/calling application, using a
mysql user only allowed to insert log events by executing a stored procedure.

Only sLog mysql administrator can access stored events and gather statistics of
user activities (who did what, when?) and application use and payload.


sLog Payload Monitor
====================
sLog Payload Monitor, not included, explores and displays sLog information. sLog
Payload Monitor package is to download separate.


LOG ITEMS
=========
ORGANISATION
organisation/unit alt. internet country name/code
Type and size: string <= 255 characters
mandatory=yes

ORGANISATION_SPEC
organisation/unit detail text
Only if ORGANISATION is used
Type and size: string <= 255 characters
mandatory=no


USER
Some user id, member id alt. IP-number
Type and size: string <= 255 characters
mandatory=yes

USER_SPEC
ex. user name alt. Internet domain
Only if USER id used
Type and size: string <= 255 characters
mandatory=no


CLIENT
client name, alt. Web browser.
Type and size: string <= 255 characters
mandatory=yes

CLIENT_SPEC
client specification:version.. ., alt. Web browser spec.
Only if CLIENT is used
Type and size: string <= 255 characters
mandatory=no


APPLICATION
application/system name
Type and size: string <= 255 characters, stored in lower case
mandatory=yes

SERVICE
application/system module/(web-)service name ex. 'createCustomer'
Type and size: string <= 255 characters, stored in lower case
mandatory=no, default application/system name

OPERATION
Basic operation, ex. CRUD; one of 'create'/'read'/'update'/'delete'
Type and size: string <= 6 characters, stored in lower case
mandatory=no

OBJECT NUMBER
Used if running more than one instance of the object (=application/service),
ex. together with a load balancer
Type and size: integer
mandatory=no, default 1


DATE
event date
Type and size: string, format 'Y-m-d'
mandatory=no, log date used if missing

TIME
event time
Type and size: string, format 'H:m:s'
mandatory=no, log time used if missing


SUBJECT
Detailed header event information like query, read/update/delete id.. .
Type and size: string <= 255 characters
mandatory=no

BODY
Respons, query answer, update specific..
Type and size: string <= 2^16 characters
mandatory=no


INSTALL
=======
Unpack to any folder. Open createDB.sql in an editor and CHANGE and notice pass-
words (and opt. hosts, if running in a multi server environment) for slogadmin,
slogreader and slogcaller!!!

User slogadmin is used when managing sLog database.
User slogcaller is used when insert log events into database, no access right
except executing stored procedures.
User slogreader can only read database, used with sLog Payload Monitor (separate
download).

Observe character set for database and change it if not appropriate.

Open up a terminal window, go to the installation scripts folder and log into mysql as mysql root user:
-->mysql -u root

Set delimiter:
mysql>delimiter //

Run the createDB.sql script:
mysql>source createDB.sql

Select the new database slog:
mysql>use slog

Create the tables:
mysql>source createTables.sql

Create the mysql stored procedures:
mysql>source createProcedure.sql

Exit mysql:
mysql>exit

All operations can also be done with an mysql admin interface like phpMyAdmin.
If using phpMyAdmin and import script function, use delimiter '//' (no quotes)
when running createProcedures.sql.

Apply a sLog call into every application(/module/service).

Thats'all!


FILE LIST
=========
db/                             test folder, testing direct db access
db/slogtest.php                 sLog direct database access test form
http/                           test folder, testing http access
http/insertLog.php              http test server, using PHP PEAR HTTP_Request
http/slogtest.php               http test client
include/form.php                common functions, used in test
pear_soap/                      test folder, testing SOAP access, PHP PEAR SOAP
pear_soap/slogclient.php        SOAP test client
pear_soap/slogserver.php        SOAP test server
pear_soap/slogserver.class.php  SOAP test server class, user by server
pear_soap/slogserver.wsdl       SOAP WSDL (Web Service Definition Language) file
scripts/                        sql scripts
scripts/createDB.sql            create database+user script
scripts/createTables.sql        create table script
scripts/createProcedures.sql    create stored procedures and functions
scripts/dropTables.sql          drop/truncate tables
GPL.txt                         licence
howto.txt                       PHP samples howto assemble web related log items
README.txt                      this file


USAGE EXAMPLES
==============
## Direct database ##
The logging application is making an insert direct into the database.

Files:
- db/slogtest.php, sLog test form

A PHP 5.x sLog insert example:
$link = mysql_connect( <dbserver>, <dbuserid>, <dbpasswd> );
mysql_select_db( <database> ); // = 'slog'
// COMPLETE call:
mysql_query("SELECT <database>.fslog('<date>','<time>','<application>',
'<service>','<operation>','<objno>','<client>','<clientSpec>','<organisation>',
'<org/unit>','<user>','<user_spec>','<subject>','<body>');
// SIMPLE call:
mysql_query("SELECT <database>.fslog('','','<application>','','','1','<client>',
'','<organisation>','','<user1>','','','');

Zero ('0') is allways returned from the mysql_query SELECT (i.e. fslog FUNCTION)
at a successfull log insert operation, anything else (-10 - -80) indicates any
db error.

Run http://<localhost/path/>db/slogtest.php in a (local) web server and open the
page in a web browser. There is a form to edit/adapt/run/view:
+ number of calls, how many logging calls to perform
+ number of organisations, how many (customer/users org.'s) to test with
+ number of users, how many users for every organisation
+ number of applications, every application are assumed to run four services
* execute test
+ execute time (seconds), total and average per call will be displayed
If changed during installation, update server, database namn, user name and
password in script db/slogtest.php at row 31.

Check sLog database ('slog') inserts with an admin interface like phpMyAdmin.

## HTTP ##
A simple http web service using PHP (5.x) and PHP PEAR HTTP_Request extension.
Check if PHP PEAR HTTP_Request is installed, in a terminal window, run 'pear
info HTTP_Request', if not installed, run 'pear install HTTP_Request'. More info
about php pear and SOAP at 'http://pear.php.net/'.

Files:
- http/slogtest.php, sLog test form, a http client using http.php class
- http/insertLog.php, sLog http server, making sLog database inserts

Row 66 in 'http/slogtest.php' might need to be updated, form action.
Run client 'http://<localhost/path/>http/slogtest.php' in a (local) web server
and open the page in a web browser, similar to the db client interface but
adding the URL for the sLog http server interface to the database 
('http://<localhost/path>http/insertLog.php').

The URL 'http/insertLog.php' must be accessible, the (same) web server. If any
changes during sLog installation, update server, database name, user name and
password in the http/insertLog.php script, row 61, before running the test. A 
delay, 0.001 sec, is inserted bewteen calls due to Apache webserver and mysql
limits (max. conections)

Check sLog database ('slog') with an admin interface like phpMyAdmin.

## SOAP ##
A SOAP Web Service client/server using PHP (5.x) and PHP PEAR SOAP extension.
Check if PHP PEAR SOAP is installed, in a terminal window, run 'pear info SOAP',
if not installed, run 'pear install SOAP'. More info about php pear and SOAP at
'http://pear.php.net/'.

Files:
- pear_soap/slogclient.php, like the http client interface, using PHP PEAR SOAP
- pear_soap/slogserver.wsdl, web service description file
- pear_soap/slogserver.class.php, server class description
- pear_soap/slogserver.php, SOAP server using class.php and wsdl + PHP PEAR SOAP
- pear_soap/dbparams.txt, opt., database parameters
Notice
- url in display form for wsdl file,
  used both in pear_soap/slogclient.php and pear_soap/slogserver.php
- in pear_soap/slogserver.wsdl, url to server, tag 'soap:address',
  change it if necessary!
- If any changes during installation, update database server, database name,
  database user name and password in the pear_soap/slogserver.php script (array)
  or external file (dbparams.txt)

Run pear_soap/slogclient.php in a (local) web server, open up a web browser,
displaying a form similar to the http client.

Check sLog database with an admin interface like phpMyAdmin.


COPYRIGHT & LICENCE
===================

COPYRIGHT

sLog
copyright (c) 2008 Kjell-Inge Gustafsson, kigkonsult
www.kigkonsult.se/slog/index.php
hide@address.com

LICENCE

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple 
Place, Suite 330, Boston, MA  02111-1307  USA
Return current item: sLog