This wiki is archived and useful information is being migrated to the main bzflag.org website
Difference between revisions of "Logging"
(import Logging wiki page from previous moinmoin wiki) |
m (development category) |
||
Line 175: | Line 175: | ||
=== --log server_messages syslog,local3.info === | === --log server_messages syslog,local3.info === | ||
=== --log debug_messages stdout === | === --log debug_messages stdout === | ||
+ | |||
+ | [[Category:Development]] |
Revision as of 19:35, 18 February 2007
Contents
INTRO
learner is in the process of adding a logging framework that will unify logging across all of the bzflag binaries. This raises the need for some discussion and agreement on default logging message types, logging categories, default formats for those messages and categories, and how logging is to be specified in general. This file intends to serve as a RFC as well as a draft specification for what will get implemented. You are welcome to make contributions but please denote your changes with your irc name, if you would. Write in plain english (even if broken) and try to be clear.. :)
Quick Overview:
We are logging MESSAGES. Those MESSAGES are comprised of %atoms. %atoms may be comprised of other %atoms.
MESSAGES may be grouped into categories_of_messages. categories_of_messages may be comprised of other_categories_of_messages.
Example:
CHAT => "%timestamp %player: %message" example: "2004-11-05T08:15:30-05:00 chestal: guten tag"
TEAM_CHAT => "%timestamp [TEAM] %player (%team): %message" example: "2004-11-05T00:15:39+05:00 [TEAM] bzg (green): hello"
public_messages => CHAT TEAM_CHAT
chat_messages => public_messages ADMIN_CHAT PRIVATE_CHAT
Slightly Longer Overview:
Logging is comprised of messages of various types such as notification that a player fired a shot, that someone picked up a flag, that someone joined the server, that a network packet was lost, and much more. Each log message type is denoted below in uppercase (e.g. ADMIN_CHAT) and contains various identifiable components like player names, time stamps, shot IDs, and more. These identifiable components are called message 'atoms' and are designated with a % prefix optionally wrapped in curly braces (e.g. %timestamp, %{flag}, %player). Atoms themselves may be comprised of other atoms (e.g. %timestamp might be a combination of "%year %month %day %hour:%minute:%second") -- and yes, someone has already mentioned they should probably be called molecules but stick with the metaphor -- they are still succint message units from a formatting perspective. ;-) Finally and additionally, the various messages may be grouped together according to various categories like chatting, player actions, networking, and more. Message groups are designated by a underscore-separated lowercase word (e.g. chat_messages and debug_messages) and like atoms, you may have groups that are comprised of other groups (and messages that belong to multiple groups).
This specification intends to describe the types of messages, a default grouping of the various categories, and a list of all the message atoms possible. It should also suggest the user-interface for how the logging format is to be specified (user menus, command line options, etc).
NEEDS
The basic needs that are considered useful (even if already implemented in some fashion) are as follows:
1. server logging 2. client chat logging 3. debug logging for developers 4. ability to have separate logs for separate categories of messages 5. multi-server logs 6. time-stamping 7. multiple message types with specified formats 8.
MESSAGE TYPES
There are a variety of default logging categories that can be grouped a variety of ways. Some of the major groups of messages are separated out below. At a fundamental level, though, they are simply all just individual message types:
Chat (chat_messages)
public chat (CHAT)
This is a message sent to all players from some player
private chat (PRIVATE_CHAT)
This is a message sent to a specific player from some player
team chat (TEAM_CHAT)
This is a message sent to a specific team from some player
admin chat (ADMIN_CHAT)
This is a message sent from a specific player to all players in the ADMIN group or that have the adminMessages permission.
Player Actions (action_messages)
Firing a weapon action (firing_messages)
firing a bullet (SHOOT)
firing a guided missile (SHOT_GM)
firing a laser (SHOT_L)
firing a shock wave (SHOT_SW)
... lot more ...
- Why the difference in tense (shoot/shot) between normal bullets and flags? --DTRemenak
Picking up or dropping Flags (flag_message)
laser (L)
guided missle (GM)
shock wave (SW)
... lot more ...
Developer/Debug (debug_messages)
informational (INFO)
Something informative that is not a trace
trace (TRACE)
A message that tells you about run-time values or where the current execution is in the code.
warning (WARN)
Caution about some event or status that has occured.
error (ERROR)
A fatal or catastrophic exception (that will generally abort the application).
- I'd like to see the ability to have "debug channels" like wine does...e.g. so I could enable just network debug logging when working on net stuff (and leave it turned off when working on other stuff), or just whatever else is relevant. --DTRemenak
DEFAULT MESSAGE GROUPS
chat_messages => CHAT, PRIVATE_CHAT, TEAM_CHAT, ADMIN_CHAT
debug_messages => INFO, TRACE, WARN, ERROR
firing_messages => SHOOT, SHOT_GM, SHOT_L, SHOT_SW
flag_messages => L, GM, SW
action_messages => firing_messages, flag_messages
MESSAGE ATOMS
Message atoms are the individual components of a log that you might want to specify individually somehow. See the list for ideas of what that means. The list includes some atoms that are basically combinations of other atoms too (like ISO date/time format).
logging goo
1. message type (%level) 2. ip address (%ip) 3. resolved domain name (%dn)
1. 4 digit year (%year) 2. numeric month (%month) 3. month name (%Month) 4. numeric day (%day) 5. day of week name (%Day) 6. calendar date (%ymd => %year %month %day) 7. time (%hour %minute %second %subsecond %timezone %utc_offset) 8. ISO date/time (%timestamp => %year-%month-%{day}T%hour:%minute:%second.%subsecond%utc_offset) 9. UNIX timestamp (%date => %Day %Month %day %hour:%minute:%second %timezone %year)
1. sending player 2. recipient player 3. recipient group (team/all) 4. chat message 5. logging of the private/team/admin recipients with the message
1. flag type 2. flag actions (grabbed/dropped/captured/reset/removed)
1. callsign 2. email address 3. player type (human/robot/observer) 4. team 5. player actions (connected/quit/kicked/banned/died/spawned)
1. position 2. obstacle type 3. size/dimension
SPECIFYING LOGS
How server operators and players specify logging should be as simple yet potentially flexible as possible, of course. Players and server ops definately have rather different logging needs, and I (learner) suggest that both client and server have the same mechanism on the command line, yet the client should also have an in-game menu for configuring logging on a basic level.
In-Game Menu
Since there will still be the command-line interface for rather complicated logging configurations, the in-game menu for logging should be as simple as possible. I (learner) would propose that there basically be a field to specify a directory (perhaps default to ~/.bzf), and then a variety of checkboxes for what to enable-disable. The menu could include the following components:
=== input field for a logging directory === === option for logging in one file, separate by server/join, or separate by type === === checkbox for logging to the console === === checkbox for logging everything (toggling it on would enable all below) === ==== checkbox for join/quit notifications ==== ==== checkbox for flag events (captures, pickups, and drops) ==== ==== checkbox for kills ==== ==== checkbox for pause/nr ==== ==== checkbox for logging all chat (toggling on enables all chat types) ==== ===== checkbox for public chat ===== ===== checkbox for private chat ===== ===== checkbox for team/group (would include admin) chat ===== ===== checkbox for server chat =====
Command-line Interface
Maybe something like: