Database logging
When you configure Spotfire Server to log user actions to a database, you create a dependent and integrated system that you can tune to your logging needs. You can monitor its health with a JMX-compatible application such as JConsole.
If you enable database logging, then the server depends on being able to connect successfully to the database. During startup, the database logger attempts to connect to the database. If the database logger fails to connect, it attempts to reconnect at increasing intervals. If the database logger is not successful after the startup attempts, the server does not run.
Times are logged as GMT by default. To change the logging times value to local time, in the Spotfire Server configuration tool, go to the User Action Log page and set Log in local time to Yes.
- Spotfire Server registers an event and checks if action logging is enabled.
- If yes, then Spotfire Server checks if the category where the event occurred is enabled for logging.
- If yes, then the event information is sent to one or two of the loggers.
- If file logging is enabled, the event is written to the file.
- Spotfire Server checks if database logging is enabled.
- If yes, the database logger adds the event to a fixed-size queue. (The queue size is fixed at runtime.)
Note: You can configure the Spotfire Server logging queue to handle the following conditions. See config-action-log-database-logger for more information.
- Control the maximum number of log events in the queue.
- If the queue is more than half full, prioritize events so that only certain events are added to the queue.
- If the queue is full, wait until there is room in the queue.
- If the queue is full, wait for a given period of time.
- The chunk worker waits until the configured number of events are available, or until the configured amount of time has passed.
- The chunk worker starts an insert worker.
- You can configure the number of simultaneous insert workers. If the limit of simultaneous workers is reached, the chunk worker waits for an insert worker to finish. See config-action-log-database-logger for more information.
- The insert worker runs a batch insert into the database.
To manage the size and performance of the database, consider the following additional configurations to the action log database logger.
| Action | Configuration option in
config-action-log-database-logger
|
|---|---|
| If everything must be logged, set the database logger to block for a place in the queue. | --block-on-full-queue=true
|
| Prioritize desired categories. If the queue is more than half full, the database logger adds to the queue only events in the prioritized categories. Other events are discarded. | --prioritized-categories=<value>
|
| To ensure that important elements are not discarded, set the queue to wait if it is full. | --wait-on-full-queue-time=<value>
|
| If the load is high, set multiple simultaneous insert workers. Otherwise, if you want to sample the system, and you do not want to load a database instance, set the number of insert workers to a low number. | --workers=<value>
|
| By default, the database pruner checks every hour for events older than the set number of hours (by default 48 hours). The events that are older are deleted. If you set the number of hours to 0, no pruning takes place, and your database administrator must manage the growth through some other means (for example, by manually pruning, or by partitioning the table). | --pruning-period=<value>
|
| Set a grace period, in seconds, to move events that are in the queue to the database when Spotfire Server is shutting down. Spotfire Server attempts to write these remaining events during this grace period. | --grace-period=<value>
|
The database administrator should monitor the usage regularly to determine if index tables should be rebuilt or dropped.
- Events for enabled categories are logged to the table ACTIONLOG, and index tables are created. If you run database searches, you can omit these index tables. (See Update action logs and system monitoring for more information.) If you include the index tables, and you also set the option for pruning, then your database administrator should consider rebuilding the index tables periodically. See your database administrator for more information.
- Views are created for categories and actions. These views help to interpret the generic columns. If you do not use the views, then you can omit them from the database creation script.
By specifying these options from the command-line command
config config-action-log-database-logger, you can tune the system for your particular environment and load. Additionally, you can use JMX to tune the system. See
Monitoring for more information about using JMX with
Spotfire Server.
In JConsole, under
com.spotfire.server, you can examine the attributes for
action-log-db-worker, of type
ActionDBLogger, to answer the following questions.
| Question | JMX Attribute |
|---|---|
| How many more insert workers can be started? | CurrentNumberOfSpareWorkers
|
| How many events are in the queue? | CurrentQueueSize
|
| What is the minimum number of spare insert workers since the server was started?
(0 indicates that all possible workers were started at some point.) |
MinimumFreeWorkers
|
| How many events have not been put in the database? | NumberOfFailedLogs
|
| How many events have tried to be logged? | NumberOfLogged
|
| How many items have been pruned from the database? | NumberOfPrunedEntries
|
| How many SQL Exceptions have been encountered? | NumberOfSQLExceptions
|
| How many more events can be queued? | RemainingQueueCapacity
|
For some database types, the installation kit also includes a library import file, which you can use to gain insight into the usage of the system. See Importing a library for analyzing action logs in Spotfire Analyst for instructions on how to get access to the Information Services model and analysis file.