This wiki is archived and useful information is being migrated to the main website


From BZFlagWiki
Jump to: navigation, search
Picture Frame.png This page contains the design document for an enhancement or feature. It is a work of collaborative development, and may not represent the final design. If you are not part of the development or design group, please post comments and suggestions on the talk page and not in the middle of the design.


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.


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).


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


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)[edit]

public chat (CHAT)[edit]

This is a message sent to all players from some player

private chat (PRIVATE_CHAT)[edit]

This is a message sent to a specific player from some player

team chat (TEAM_CHAT)[edit]

This is a message sent to a specific team from some player

admin chat (ADMIN_CHAT)[edit]

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)[edit]

Firing a weapon action (firing_messages)[edit]

firing a bullet (SHOOT)[edit]

firing a guided missile (SHOT_GM)[edit]

firing a laser (SHOT_L)[edit]

firing a shock wave (SHOT_SW)[edit]

... lot more ...

  • Why the difference in tense (shoot/shot) between normal bullets and flags? --DTRemenak

Picking up or dropping Flags (flag_message)[edit]

laser (L)[edit]

guided missle (GM)[edit]

shock wave (SW)[edit]

... lot more ...

Developer/Debug (debug_messages)[edit]

informational (INFO)[edit]

Something informative that is not a trace

trace (TRACE)[edit]

A message that tells you about run-time values or where the current execution is in the code.

warning (WARN)[edit]

Caution about some event or status that has occured.

error (ERROR)[edit]

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


chat_messages => CHAT, PRIVATE_CHAT, TEAM_CHAT, ADMIN_CHAT[edit]

debug_messages => INFO, TRACE, WARN, ERROR[edit]

firing_messages => SHOOT, SHOT_GM, SHOT_L, SHOT_SW[edit]

flag_messages => L, GM, SW[edit]

action_messages => firing_messages, flag_messages[edit]


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[edit]

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


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[edit]

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[edit]

Maybe something like:

--logFormat CHAT "%timestamp %user: %message"[edit]

--logGroup chat_messages CHAT,PRIVATE_CHAT,ADMIN_CHAT,TEAM_CHAT[edit]

--log chat_messages /var/log/chat.log[edit]

--log server_messages syslog,[edit]

--log debug_messages stdout[edit]