[[statsBloc]]
= stats
:author: Wojciech Kapcia <wojciech.kapcia@tigase.org>
:version: v2.1, August 2017: Reformatted for Kernel/DSL

The stats block contains settings for statistics collection. To begin the stats block, use the following:
[source,dsl]
-----
stats {}
-----

*Default value:* 'By default, stats is not listed in the `config.tdsl` file'

*Description*

Tigase XMPP Server can store server statistics internally for a given period of time. This allows you to connect to a running system and collect all the server metrics along with historic data which are stored on the server.
This is very useful when something happens on your production system you can connect and see when exactly this happened and what other metrics looked around this time.
*Please be aware that Tigase XMPP Server produces about 1,000 different metrics of the system. Therefore caching large number of statistics sets requires lots of memory.*

== stats-history-size
Stats-history defines the size of the history buffer. That is how many complete sets of historic metrics to store in memory.
[source,dsl]
-----
stats {
    'stats-history-size' = '2160'
}
-----

== stats-history-interval
Sets the interval for which statistics will be gathered from the server.
[source,dsl]
-----
stats {
    'stats-history-interval' = '10'
}
-----

== stats-logger
Allow enabling and configuring components responsible for storing statistic information. Note that this controls the logging system for retrieving using JMX, clients, or ad-hoc commands.

[source,dsl]
-----
stats {
    'stats-logger' (class: value) {
        <other settings>
    }
}
-----

Currently following classes are available:

- `tigase.stats.CounterDataArchivizer` - every execution put current basic server metrics (CPU usage, memory usage, number of user connections, uptime) into database (overwrites previous entry)
- `tigase.stats.CounterDataLogger` - every execution insert new row with new set of number of server statistics (CPU usage, memory usage, number of user connections per connector, number of processed packets of different types, uptime, etc) into the database
- `tigase.stats.CounterDataFileLogger` - every execution store all server statistics into separate file.

=== frequency
stats-logger may also be controlled using frequency, which is the time interval between executions of the archiver `.execute()` method in seconds.
[source,dsl]
-----
stats {
    'stats-logger' (class: tigase.stats.CounterDataLogger) {
    	repository() {
    		'default'() {
    			'data-source' = 'default';
    		}
    	}
        frequency = '60'
    }
}
-----

== stats-file-logger
This allows configuring of statistics gathering to an external file. This only has one class, and may be controlled independently from the internal statistics.
[source,dsl]
-----
stats {
    'stats-file-logger' (class: tigase.stats.CounterDataFileLogger) {
        <other settings>
    }
}
-----

=== frequency
stats-file-logger may also be controlled using frequency, which is the time interval between executions of the archiver `.execute()` method in seconds.
[source,dsl]
-----
stats {
    'stats-file-logger' (class: tigase.stats.CounterDataFileLogger) {
        frequency = '60'
    }
}
-----

=== file configuration
You can customize the file output for stats-file-logger using the following setting options, these are all optional.
[source,dsl]
-----
stats {
    'stats-history-size' = '2160'
    'stats-update-interval' = '10'
    'stats-file-logger' (class: tigase.stats.CounterDataFileLogger) {
        frequency = '60'
        'stats-datetime' = 'true'
        'stats-datetime-format' = 'HH:mm:ss'
        'stats-directory' = 'logs/server_statistics'
        'stats-filename' = 'stat'
        'stats-level' = 'FINEST'
        'stats-unixtime' = 'false'
-----

- *'stats-datetime'* - Whether to include date & time timestamp.
- *'stats-datetime-format'* - Specifies the formatting of datetime timestamp.
- *'stats-directory'* - The directory to which the statistics file should be saved.
- *'stats-filename'* - The filename prefix to name the output statistics file.
- *'stats-level'* - Sets the level of statistics to be gathered.
- *'stats-unixtime'* - Control the format of the timestamp to use java DateFormat pattern.

which configures accordingly: directory to which files should be saved, filename prefix, whether to include or not unix timestamp in filename, whether to include or not datetime timestamp, control format of timestamp (using java DateFormat pattern) and also set level of the statistics we want to save (using java Logger.Level)


== Database logger
This allows configuring of statistics gathering to a database. Without additional configuration `default` data source will be used but it's possible to store statistics in any database - simply define new data source and configure logger with it's name.

NOTE: After enabling the component it's database schema should be loaded by executing `./scripts/tigase.sh upgrade-schema etc/tigase.conf` from the main Tigase directory

[source,dsl]
-----
stats {
    'stats-logger' (class: tigase.stats.CounterDataLogger) {
    	repository() {
    		'default'() {
    			'data-source' = 'customDataSourceName';
    		}
    	}
        frequency = '60'
    }
}
-----

== Example configuration block
[source,dsl]
-----
stats {
    'stats-history-size' = '2160'
    'stats-update-interval' = '10'
    'stats-file-logger' (class: tigase.stats.CounterDataFileLogger) {
        frequency = '120'
        'stats-datetime' = 'false'
        'stats-datetime-format' = 'HH:mm:ss'
        'stats-directory' = 'logs/statistics'
        'stats-filename' = 'output'
        'stats-level' = 'WARNING'
        'stats-unixtime' = 'true'
    }
    'stats-logger' (class: tigase.stats.CounterDataLogger) {
    	repository() {
    		'default'() {
    			'data-source' = 'default';
    		}
    	}
        frequency = '60'
    }
}
-----

*Available since:* 8.0.0
