OnTime offers several options when it comes to generating reports about player activity.
Total, Daily, Weekly, and Monthly Playtime Reports
The most basic set of OnTime reports are the playtime reports that can be generated for total (all time), daily, weekly, and monthly basis.
There are multiple options for the format of the reports. Reports can be generated in a plain text (TXT) format, in an HTML format suitable for use on web pages (HTML), or the reports can be generated as MySQL tables which can then be used by external utilities that support MySQL. (OnTime itself does not provide any utilities that use these tables, that is up to the server owner and administrators.)
Setting the Report Format
# If autoReportEnable is true, set the format of the reports: (Valid Settings: TXT, HTML, MYSQL) reportFormat: TXT
Configuration of Start of Week & Start of Month
To accommodate different practices in the world, OnTime enables the administrator to define what should be considered the start of a new week (day), and the start of a new month (day).
# Identify the starting day of each week for weekly reports and weekly rewards. Valid Values: 1-7 where: # 1=Sunday; 2=Monday; etc. firstDayofWeek: 2 # Identify the starting day of each month for monthly reports, and monthly rewards. # Just in case you want to start in the middle for some strange reason..... and to help debug problems # Valid Values: 1-31 where: 1=1st; 2=2nd; etc. firstDayofMonth: 1
Reports can be generated manually via the command "/ontime reports". To use this command a player must have the permission "ontime.report".
Only through using the "ontime reports" command will an "total OnTime" report be generated.
More commonly, OnTime reports are generated automatically each day, week, and month. These automated reports are setup through configuration settings in the OnTime/config.yml.
Enabling Automated Reports
# Enable if DAILY/WEEKLY/MONTLY reports should be auto-generated autoReportEnable: true # If 'autoReportEnable is true' then, enable various DAILY/WEEKLY/MONTHLY reports dailyPlayReportEnable: true weeklyPlayReportEnable: true monthlyPlayReportEnable: true
Configuration of Automated Reports File Storage and Names
The administrator is able to define the folder location of where the reports are stored. They can also specify that the 'date' of the report be included in the name of the report, and if so configured the administrator has the ability to define the format of the date used in those names. This way each new day a report is created, older reports are not lost. Conversely if the 'date' is not included in the name of the report, when a new report is created it will use the same report name, and write over the previous version of the report. (These settings apply to TXT and HTML formatted reports only.)
# Report Storage sub-folder under /plugins/OnTime/ # '/' implies no sub-folder. '/reports' is otherwise recommended reportFolder: / # Date format used in reports and in filename (if enabled below) dateFilenameFormat: yyyy.MM.dd # Enable date to be used in Report filenames (using format above) dateInFilenameEnable: true
Purging of Automatically Generated Reports
Administrators will find that when automated reports are used and old reports are retained by the system, that their folders or databases will fill up over time, using up valuable storage resources. OnTime helps with this by automatically deleting old reports or MySQL tables, retaining the old data only for time periods specified by the admin. The settings for this part of the configuration is specified in the number of days that each file should be retained before it is deleted. If the duration is specified as negative one (-1) then files will not be automatically deleted.
# If autoReportEnable is true, set the duration (in days) that reports are retained before they are auto deleted # Set any of the following to -1 to disable the auto deletion for that report type # Recommendations: Daily:8; Weekly:36; Monthly:380; afk:15 # dailyReportRetention: -1 weeklyReportRetention: -1 monthlyReportRetention: -1 afkReportRetention: -1
There is one additional "report" that OnTime creates which is only available when using MySQL, and is more of a system status than a report, because it is continually updated by the plugin.
With the "Online Tracking" table, an administrator can define a set of data to be collected about all online players and saved to a MySQL table on a regular interval. This data will also be updated any time players join, leave, or change AFK status on the server. The purpose of this table is provide a means for server owners to pull data from OnTime and use it to populate web sites that show the status of players currently on the server.
Enabling and Setting Update Interval
The administrator is able to specify the interval, in minutes, at which OnTime updates this information, in addition to specifying the information stored.
# Enable if Online player status should be tracked in MYSQL Table onlineTrackingEnable: false # If online tracking is enabled, set the refresh rate (in minutes) onlineTrackingRefresh: 5
Defining OnLine Report Content
The data included in the OnLine Report is specified in the /plugins/OnTime/output.yml file under the keyword "onlineReport". The administrator can include in this report any of the following pieces of information, of which only "player" is absolutely required. (These are also identified in the ouput.yml file at the top, as it is the same output used in game for various commands.)
- player - player name
- afk - afk status
- lastLogin - date and timestamp of last login
- current - play time for current session
- daily - play time for the current day
- weekly - play time for the current week
- monthly - play time for the current month
- total - total play time on the server
- afkTime - afk time for current afk state
- afkToday - afk time for the current day
- afkWeek - afk time for the current week
- afkMonth - afk time for the current month
- votes - total number of votes cast
- voteToday - votes cast during the current day
- voteWeek - votes cast during the current week
- voteMonth - votes cast during the current month
- lastVote - the date and time stamp of a player's last vote
- referrals - total number of referrals a player has made
- daysAgo - the number of days ago that a player joined the server
- daysOn - the number of different days that a player has been on the server
- rank - a players current highest priority group (rank)
# # MYSQL Online Report # onlineReport: - player - afk - lastLogin - current - daily - total - afkToday #
Configuring On Line Report Data
Because the information populated into this report is the same as is used in the output to the user in game for various commands such as "/ontime" and "/ontime <playerName>", the information placed in this report is also configurable. Such as:
# Formats used to output dates and time. Please reference http://www.java2s.com/Tutorial/Java/0040__Data-Type/SimpleDateFormat.htm # for more information and examples # dateTimeFormat: '[MM/dd/yyyy HH:mm:ss]'
# TimeDetail is used for output for 'ontime', 'ontime <playerName>', 'ontime top' commands # DD = days ; HH = hours ; MM = minutes (default = DDHHMM) # EXAMPLE: if set to HHMM then a player with more than 1 day of playtime will see a number larger than 24 in their hour count # EXAMPLE: if set to DDHH then the playtime display will only include the number of days and hours. Minutes will be ignored. timeDetail: DDHHMM # Labels used for time output for 'ontime', 'ontime <playerName>', 'ontime top' commands time: seconds: ' Seconds' minutes: ' Min ' hours: ' Hr ' days: ' Day ' na: ' Time N/A '
About MYSQL Reports:
Using the "ontime-players" database to track reports
When configured with “reportFormat: MYSQL” OnTime will keep track of reports created using the “ontime-players” table. (This is the same table where all of the player data is stored.) There will be one row in this table for each report that can be identified by the “referredBy” column which is set to “ontime-report”. This information is used to track when reports should be deleted by purge function, and the row for a report will be removed when that report is purged.
About Weekly and Monthly Reports
When weekly and/or monthly reports are enabled, and “reportFormat:” is set to HTML or TXT, the reports will be generated at the end of each week or month. When “reportFormat:” is set to MYSQL, these tables will be updated continually until the end of each week or month. So when using MYSQL it’s possible to see player’s progress-to-date for the current week and current month.