Cisco Unified Serviceability Alarms and CiscoLog Messages
Cisco Unified Serviceability alarms provide information on runtime status and the state of the system, so you can troubleshoot problems that are associated with your system. The alarm or error message information includes the application name, machine name, and recommended action and other critical information to help you troubleshoot.
You configure the alarm interface to send alarm information to multiple locations, and each location can have its own alarm event level (from debug to emergency). You can direct alarms to the Syslog Viewer (local syslog), SNMP traps, Syslog file (remote syslog), SDI trace log file, SDL trace log file (for Cisco Unified CM and CTIManager services only), or to all destinations.
You use the Trace and Log Central option in the Cisco Unified Real-Time Monitoring Tool (RTMT) to collect alarms that get sent to an SDI or SDL trace log file. To view the alarm information sent to the local syslog, use the SysLog Viewer in RTMT.
 Note |
All the alarms are logged based on their severity and settings of alarm event level. For information on viewing the alarm configuration settings, refer to the Cisco Unified Serviceability Administration Guide. |
CiscoLog Format
CiscoLog, a specification for unified logging in Cisco software applications, gets used in the Cisco Unified RTMT. It defines the message format when messages are logged into file or by using the syslog protocol. The output that is provided by Cisco software applications gets used for auditing, fault-management, and troubleshooting of the services that are provided by these applications.
Be aware that CiscoLog message format is compatible with one of the message formats that is produced by Cisco IOS Release 12.3 by using the syslog protocol when Cisco IOS Software is configured with the following commands:
-
service sequence-numbers—A default sequence number that is produced by Cisco IOS. An additional sequence number can also be enabled with this command. This command forces sequence numbers to be shown in terminal output, but results in two sequence numbers in the syslog output. CiscoLog standardizes on a format with just one sequence number. Thus, the compliant Cisco IOS Software configuration occurs when the second number is disabled by using the no service sequence-numbers command.
-
logging origin-id hostname—The CiscoLog HOST field remains consistent with that produced by the Cisco IOS Release 12.3 when configured with this command. This command does not get documented in the Cisco IOS Software documentation but is available in Cisco IOS Release 12.3. CiscoLog stays compatible with the results that Cisco IOS Software produces in this field.
-
service timestamps log datetime localtime msec show-timezone year—The CiscoLog TIMESTAMP field remains consistent with the timestamp format produced by Cisco IOS Release 12.3 when configured with this command.
Note |
CiscoLog uses the same field delimiters as Cisco IOS Software Release 12.3. |
Log File and Syslog Outputs
When CiscoLog messages are written directly into a log file by an application, each message is on a separate line. The line separator should be a standard line separator used on a given platform. On Windows, the line separator must be the sequence of carriage return and line feed characters (ASCII decimal values 13 and 10; often designated as "\r\n" in programming languages). On Solaris and Linux, the line separator is a single line feed character (ASCII decimal value 10 and in programming languages typically "\n"). Two line separators must never appear one after another, for example, you cannot have "\r\n\r\n" on Windows, but "\r\n" is fine because these two characters are a single line separator.
In practical terms, this means that applications should be careful when appending data to an existing log. In some cases an initial line break is required and in others not. For example, if application crashes when writing CiscoLog message, but before it wrote a line break to file, then when the application starts up, it should print an initial line break before printing the next message. An application can determine if an initial line break is necessary during startup by checking the last character sequence in the log file that will be used for appending.
CiscoLog message format is identical for messages written directly to a log file or those generated by using the syslog protocol with two minor exceptions. When CiscoLog messages are written directly into to a file they must be appended with line separators. When CiscoLog messages are sent by using the syslog protocol then the syslog RFC 3164 protocol PRI header must be prepended to each CiscoLog message.
The syslog PRI field encodes syslog message severity and syslog facility. The severity encoded in the PRI field must match the value of the CiscoLog SEVERITY field. Any syslog facility can be used regardless of the content of the message. Typically, a given application is configured to send all its messages to a single syslog facility (usually RFC 3164 facilities local 0 through local 7). Refer to RFC 3164 for details about how to encode the PRI field. Below is an example of a CiscoLog message with the syslog protocol PRI field <165> which encodes the severity level of notice (5) and facility value local4.
<165>11: host.cisco.com: Jun 13 2003 12:11:52.454 UTC: %BACC-5-CONFIG: Configured from
console by vty0 [10.0.0.0]Messages as shown in the example above can be sent to UDP port 514 if using RFC 3164 logging mechanism.
Syslog RFC 3164 provides additional guidelines for message content formatting beyond the PRI field. However, RFC 3164 is purely information (not on IETF standards track) and actually allows messages in any format to be generated to the syslog UDP port 514 (see section 4.2 of RFC 3164). The RFC provides observation about content structure often encountered in implementations, but does not dictate or recommend its use. CiscoLog format does not follow these observations due to practical limitations of the format defined in the RFC. For example, the time stamp is specified without a year, time zone or milliseconds while the hostname can only be provided without the domain name.
CiscoLog messages must remain unaltered when relayed. The PRI field is not part of a CiscoLog message, but rather a protocol header. It can be stripped or replaced if necessary. Additional headers or footers can be added to and stripped from the CiscoLog message for transport purposes.
Standard Syslog Server Implementations
Standard syslog server implementations can be configured to forward received log messages or to store the messages locally. Most syslog server implementations strip the PRI field from the received messages and prefix additional information to the message before storage. This additional information typically includes two extra fields: the local time stamp and the host identifier (IP or DNS name) of the server, which generated or relayed the message.
The following example of a CiscoLog message shown the output after being logged by the Solaris 8 syslog server:
Jun 13 12:12:09 host.cisco.com 11: host.cisco.com: Jun 13 2003 12:11:52.454 UTC: %BACC-5-CONFIG: Configured from console by vty0 [10.0.0.0]There is no standard that defines how syslog servers must store messages. Implementations vary greatly. CiscoLog only addresses the format in which messages are sent to the syslog server, not how they are stored by the server that receives them. Specifically, the format and presence of any additional header fields in syslog log files is outside of the scope of this specification.
Note |
The CiscoLog specification recommends that the syslog server implementation store CiscoLog messages in exactly the same format as it receives them only stripping the PRI field and without any extra headers. This would provide an identical storage format for CiscoLog messages written directly to the log file by an application or logged through syslog protocol. |
Clock Synchronization
It is important that the clocks of all hosts of a distributed application be synchronized with one authoritative clock. This can be accomplished by using protocols such as NTP. Clock synchronization is recommended because the time stamps in log messages are required in order to be able to reconstruct the correct sequence of events based on messages originating from multiple processes or multiple hosts. Clock drifts can still occur, but ongoing synchronization should reduce this issue to a minimum.
Multipart Messages
ASCII control characters are not permitted in any of the fields of CiscoLog message format. Control characters include characters such as line feed, form feed and carriage returns. This means that multi-line messages are not allowed unless to allow:
-
Better presentation (for example, a stack trace)
-
Fragmenting messages which exceed 800 octet limit
Multi-part CiscoLog message consists of a set of multiple valid CiscoLog messages. Messages are grouped together using a special tag key "part", which identifies the part number and the sequence number of the original message.
All messages which are part of a multi-part message must have a "part" tag as well as identical values for the HOST, TIMESTAMP, APPNAME, SEVERITY fields and other TAG values. However, the sequence number of each message has to be incremented as usual.
Example of a multi-part message:
16: host.cisco.com: Jun 13 2003 23:11:52.468 UTC:
%BACC-3-UNEXPECTED_EXCEPTION: %[pname.orig=rdu][part=16.1/3]: Null pointer
exception
17: host.cisco.com: Jun 13 2003 23:11:52.468 UTC:
%BACC-3-UNEXPECTED_EXCEPTION: %[pname.orig=rdu][part=16.2/3]:
com.cisco.Source:123
18: host.cisco.com: Jun 13 2003 23:11:52.468 UTC:
%BACC-3-UNEXPECTED_EXCEPTION: %[pname.orig=rdu][part=16.3/3]:
com.cisco.Main:1112In this example, the first message has part number 1 and its sequence number, 16, embedded in the part tag. Subsequent messages embed the sequence number of the first message part and provide their own part number. The trailing "/3" in each part tag value means that the message consists of three parts.
CiscoLog Message Format
The CiscoLog message format follows:
<SEQNUM>: <HOST>: <TIMESTAMP>: %<HEADER>: [TAGS: ]<MESSAGE>
All fields gets separated by a single colon character (ASCII decimal value 58) and a single space character (ASCII decimal value 32). The HEADER field is also preceded by a percent character (ASCII decimal value 37).
The TIMESTAMP, HEADER and TAGS fields have internal formatting. Below is a complete format with details for TIMESTAMP and HEADER fields:
<SEQNUM>: <HOST>: [ACCURACY]<MONTH> <DAY> <YEAR> <HOUR>:<MINUTES>:<SECONDS>.<MILLISECONDS> <TIMEZONE>: %<APPNAME>-<SEVERITY>-<MSGNAME>: [TAGS: ]<MESSAGE>
All fields except for ACCURACY and TAGS are required.
The following example shows a CiscoLog message:
11: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-5-CONFIG: Configured from
console by vty0 [10.10.10.0]The following example shows the optional TAGS and ACCURACY fields in a CiscoLog message:
12: host.cisco.com: *Jun 13 2003 23:11:52.454 UTC: %BACC-4-BAD_REQUEST:
%[pname.orig=rdu][comp=parser][mac=1,6,aa:bb:cc:11:22:33][txn=mytxn123]: Bad request
received from device [1,6,aa:bb:cc:11:22:33]. Header missing.The values of the specific fields in the above example are as follows:
-
SEQNUM – "12"
-
HOST – "host.cisco.com"
-
ACCURACY – "*"
-
MONTH - "Jun"
-
DAY – "13"
-
YEAR – "2003"
-
HOUR – "23"
-
MINUTES – "11"
-
SECONDS – "52"
-
MILLISECONDS – "454"
-
TIMEZONE – "UTC"
-
APPNAME – "BACC"
-
SEVERITY – "4"
-
MSGNAME – "BAD_REQUEST"
-
TAGS – "%[pname.orig=rdu][comp=parser][mac=1,6,aa:bb:cc:11:22:33][txn=mytxn123]"
-
MESSAGE – "Bad request received from device [1,6,aa:bb:cc:11:22:33]. Header missing."
Message Length Limit
The maximum length of a complete CiscoLog message must not exceed 800 octets.The term octet is used for 8-bit data type instead of byte because byte is not 8 bits on some platforms. The words "character" and "octet" are not synonyms in parts of this specification because in places were internationalization is supported a single character may need to be represented with multiple octets. This limit is dictated by RFC 3164. The limit of 1024 octets reserves some extra space for syslog forwarding headers and/or fields that may be formalized in later specifications.
When CiscoLog message includes the syslog PRI field, then the combined CiscoLog messages and PRI field length must not exceed 805 octets.
SEQNUM Field
The SEQNUM field contains a sequence number, which can be used to order messages in the time sequence order when multiple messages are produced with the same time stamp by the same process. The sequence number begins at 0 for the first message fired by a process since the last startup and is incremented by 1 for every subsequent logging message originated by the same process. Every time the application process is restarted, its sequence number is reset back to 0. The sequence number of each message must be in the exact order in which messages are fired/logged by the application.
This may mean that in a multi-threaded application there must be some kind of synchronization to ensure this and another consideration may have to be made for Java applications that have some native (C) code in JNI. If log messages originate in both native and Java parts of the same process, the implementation needs to be synchronized to use the same sequence number counter across the two process parts and to fire messages in the order of sequence numbers.
The maximum numeric value of the SEQNUM field is 4,294,967,295 at which point the counter must be reset back to 0. The maximum positive value of a 32-bit unsigned integer as used in Cisco IOS. Cisco IOS uses ulong for the sequence number counter and ulong is a 32-bit unsigned integer on all current Cisco IOS platforms including mips, ppc, and 68k.
Sequence numbers are process specific. If application architecture has multiple application processes on a single host, which share a single logging daemon, the sequence number still has to be process-specific. Thus, each process has it is own sequence number which it increments.
Sequence numbers also help detect lost messages. Therefore, sequence numbers cannot be skipped. In other words, a message must be produced for every number in the sequence order.
HOST Field
The HOST field identifies the system originating the message with a Fully Qualified DNS Name (FQDN), hostname or an IPv4/IPv6 address. If the FQDN or hostname is known, one of the two has to appear in the HOST field. It is expected that in most deployments the hostname is sufficient. However, if a deployment spans multiple domains, then using FQDNs is recommend. If an application is expected to be deployed in both scenarios, then it is recommended that the application default to the FQDNs, but make it a configurable option.
If neither FQDN nor hostname can be identified, then the IP address of the host must be used. If the IP address cannot be identified, then a constant "0.0.0.0" (without quotes) must appear in place of the HOST field.
Note |
With regards to the compliance with Cisco IOS format. Cisco IOS Release 12.3 supports producing hostname, IP address, or any user-defined string in the HOST field. If it is configured to provide a hostname and it is not set on the device, it will use a string such as "Router." |
The length of the HOST field must not exceed 255 octets.
FQDN and Hostname
If multiple FQDNs or hostnames are known for a given system, applications must use the primary FQDN/hostname or an arbitrary one if no primary is designated. However, applications must use the same HOST field value until some relevant configuration change takes place. In other words, the FQDN/hostname value should not arbitrarily change from message to message if system is configured with multiple FQDNs/hostnames.
Only printable US ASCII characters (those with decimal values 32-126) and foreign language characters are allowed in the HOST field when encoding an FQDN or hostname. The appropriate character set and encoding for HOST should be compliant with RFC 1123 / STD-3.
The acceptable character set per these standards includes US ASCII letters, numbers, dash and dot separator characters (although not starting or ending with a dash). The reason that these are only recommendations of adhering to these standards is that, in practice, many hosts do not follow the convention and use characters such as underscore in the hostname. However, the HOST field cannot contain a character sequence of ": " (colon and space) as this sequence is used as a field delimiter in the CiscoLog format.
Foreign language characters outside of the printable US ASCII characters have to be encoded according to internationalization rules.
Use of non-printable (control) ASCII characters is not allowed in the HOST field. Control characters include characters with ASCII decimal values 0-31 and 127. If an application provides a CiscoLog-compliant library with a host string, which includes one or more control characters, the logging library must do the following. If the horizontal tab character (ASCII decimal value 9) is encountered, it must be replaced with one or more space characters (ASCII decimal value 32). Eight spaces per tab are recommended because this is a convention on most Unix and Windows platforms. Other control characters must each be replaced with a question mark character (ASCII decimal value 63).
While DNS is letter-case agnostic, CiscoLog places an additional recommendation of using only lower-case characters in the HOST field for ease of readability. The use of the trailing dot at the end of the FQDN is optional. The following examples are valid HOST fields:
-
host123
-
host-123
-
host123.cisco.com
-
host123.cisco.com.
IP Addresses
The IP address value used in the HOST field can be either an IPv4 or IPv6 address. If a device has multiple IP addresses, the primary IP address of the device must be used regardless of the interface through which the CiscoLog message is sent to syslog server. If no primary IP address is designated, a fixed/static IP address is preferred to a dynamically assigned one. If multiple static IP addresses exist, any one can be used, but it must be used consistently in all messages until a relevant configuration event occurs on the system.
-
IPv4 Address—IPv4 address should be represented in dot notation "x.x.x.x", where x is a decimal value from 0 to 255 encoded as ASCII text. If an IP address is unknown, "0.0.0.0" (without quotes) must be used as a place holder. Examples of valid IPv4 addresses are 0.0.0.0 and 212.1.122.11.
Below is an example of a message with an IPv4 address in the HOST field:
11: 212.1.122.11: Jun 13 2003 23:11:52.454 UTC: %BACC-3-BAD_REQUEST: Bad request received from device [1.2.3.4]. Missing header.Below is an example of a CiscoLog message when FQDN, hostname or IP are all unknown:
11: 0.0.0.0: Jun 13 2003 23:11:52.454 UTC: %BACC-3-BAD_REQUEST: Bad request received from device [1.2.3.4]. Missing header. -
IPv6 Address—IPv6 address representation must follow conventions outlined in RFC 3513, sections 2.2.1, 2.2.2 and 2.2.3. Specifically, all three conventions are supported. Both lower-case and upper-case letters can be used in the IPv6 address, but the lower-case letters are recommended. If an IP address is unknown, "0.0.0.0" (without quotes) should be used as the IP address. Examples of valid IPv6 addresses:
-
1080:0:0:800:ba98:3210:11aa:12dd (full notation)
-
1080::800:ba98:3210:11aa:12dd (use of "::" convention)
-
0:0:0:0:0:0:13.1.68.3 (last 4 octets expanded as in IPv4)
-
0.0.0.0 (unknown FQDN, hostname and IP address )
-
Below is an example of a message with an IPv6 address in the HOST field:
11: 1080:0:0:800:ba98:3210:11aa:12dd: Jun 13 2003 23:11:52.454 UTC:
%BACC-3-BAD_REQUEST: Bad request received from device [1.2.3.4]. Missing header.TIMESTAMP Field
The TIMESTAMP field provides date with year, time with milliseconds and a time zone identifier in the following format:
[ACCURACY]<MONTH> <DAY> <YEAR> <HOUR>:<MINUTES>:<SECONDS>.<MILLISECONDS> <TIMEZONE>
Below are several examples of valid time stamps:
Jun 13 2003 23:11:52.454 UTCJun 3 2003 23:11:52.454 UTC
Jun 22 2003 05:11:52.525 -0300
*Feb 14 2003 01:02:03.005 ESTIn some cases, it is possible that a device may not have the knowledge of the date and/or time due to hardware or software limitations. In such circumstances, the following string must be produced TIMESTAMP field: "--- 00 0000 00:00:00.000 ---". Below is an example of a CiscoLog message from a device which has no knowledge of date and/or time:
11: host.domain.com: --- 00 0000 00:00:00.000 ---: %BACC-3-BAD_REQUEST: Bad request received from device [1.2.3.4]. Missing header.Devices which are not aware of their clock, may choose to provide an uptime as a relative measure of time. If device is capable of providing uptime, it is recommended that does so as a substitute for unavailable time stamp. If uptime is provided it must be provided with a standard uptime tag as outlined in the CiscoLog Standard Tags specification.
The following table details each field specification.
|
Field |
Specification |
|---|---|
|
ACCURACY |
This is an optional field. If present, it must be either a single asterisk character (ASCII decimal value 42), or a single dot character (ASCII decimal value 46). No separator character is used after this field. This field indicates the status of clock synchronization. Cisco IOS uses a special convention for time prefixes to indicate the accuracy of the time stamp. If dot character appears before the date, it means that the local time was synchronized at some point via NTP, but currently no NTP servers are available. The asterisk character in front of the date means that the local time is not authoritative, i.e. NTP servers are not setup. |
|
CiscoLog supports the use of this convention, but does not require it. If an application is integrated with NTP client software, and knows that its time is out of sync, then it can optionally prefix the message with asterisk character. However, because applications may choose not to use this scheme, the lack of "." or "*" in CiscoLog messages should not be interpreted to mean that the local time is synchronized. |
|
|
MONTH |
Must be one of the following three-character month designations followed by a single space (ASCII decimal value 32) as a delimiter character: Jan, Feb, Mar, Apr, May, Jun, Jul, Sep, Oct, Nov or Dec. |
|
DAY |
Must consist of two characters. If day is a single digit, it must be prefixed with a single space character. The acceptable range of values is from 1 to 31. The day value must be followed by a single space as a delimiter character. |
|
YEAR |
Must consist of exactly 4 digit characters followed by a space as a delimiter character. |
|
HOUR |
Must consist of exactly two number characters. The hour value is based on a 24-hour clock. Values range from 00 to 23. If hour value is a single digit, it must be prefixed with a single zero character. The hour value must be followed by a single colon as a delimiter character. |
|
MINUTES |
Must consist of exactly two number characters. Values range from 00 to 59. If minute value is a single digit, it must be prefixed with a single zero character. The minutes value must be followed by a single colon as a delimiter character |
|
SECONDS |
Must consist of exactly two number characters. Values range from 00 to 59. If seconds value is a single digit, it must be prefixed with a single zero character. The seconds value must be followed by a period as a delimiter character. |
|
MILLISECONDS |
Must consist of exactly 3 digit characters. Values range from 000 to 999. If milliseconds value is less then 3 digits in length it must be prefixed with extra zeros to make it a 3-character field. The milliseconds value is followed by a space as a delimiter character. |
|
TIMEZONE |
Must consist of at least one, but no more than 7 characters in the following ASCII decimal value range: 32-126. The value must not include a combination of colon-space-percent of characters – ": %" (ASCII decimal values 58, 32, 37) – as this character combination is reserved as a field delimiter that follows the time stamp. There is no standard set of acronyms for time zones1. A list of common time zone acronyms and corresponding time offsets from UTC is provided in the UTC specification. Uppercase letters are recommended for time zone acronym values. CiscoLog recommends the use of time offset instead of time zone identifier in this field. The offset, if provided, must follow the following format "-hhmm" or "+hhmm" to indicate hour and minute offset from UTC. In this format time zone field must always contain 5 characters, with the last 4 characters being constrained to numbers only. Unlike a textual time zone identifier, this format provides a specific time offset from universal standard time. Cisco IOS Release 12.3 supports any 7-character string as a time zone identifier, so it can be configured in a way which is compatible with this recommendation. Multiple messages may and sometimes must be produced with exactly the same time stamp. This can happen naturally on a non-preemptive operating system or may need to be deliberately induced as in the case of multi-part messages. Sequence numbers then become helpful for establishing message order. Time stamp should always be accurate to the millisecond unless it can significantly hinder performance of the application. In either case, applications must always provide the administrator with an option to output messages with exact time stamp in milliseconds. If an application uses time stamp with accuracy to the second (instead of a millisecond), it must put the last known milliseconds value or 000 in place of the milliseconds. Whatever convention is chosen by the application, it should be followed consistently. |
HEADER Field
The HEADER field has the following format:
<APPNAME>-<SEVERITY>-<MSGNAME>
A single dash character (ASCII decimal value 45) serves a separator for the three fields.
APPNAME Field
The APPNAME field in the HEADER defines the name of the application producing the message. Cisco IOS uses FACILITY in place of APPNAME that names the logical component producing the message. Cisco IOS 12.3 defines approximately 287 facilities for 3950 messages. Example of some easily recognizable facilities: AAAA, SYS, ATM, BGP, CRYPTO, ETHERNET, FTPSERVER, CONFIG_I, IP, ISDN, RADIUS, SNMP, SYS, TCP, UBR7200, X25. A complete list of defined facilities is available in Cisco IOS documentation at http://.
Outside of the Cisco IOS, there can be multiple applications on the same host originating log messages. Therefore, it is necessary that APPNAME field identify the specific application. Additional source identifiers are available in the HOST field as well as various standard TAGS field values (pname, pid, comp, etc).
The APPNAME field must consist of at least two uppercase letters or digits and may include underscore characters. More precisely, the acceptable character set is limited to characters with the following ASCII decimal values: 48-57 (numbers), 65-90 (upper-case letters) and 95 (underscore).
The length of the APPNAME field must not exceed 24 characters.
Application names cannot conflict with other Cisco software applications and with Cisco IOS facilities.
On the Solaris platform, it is recommended (not required) that the application name values used in the APPNAME field be consistent with those used for the application installation package name, only in upper case and without the CSCO prefix. For example, an application registering as "CSCObacc" on Solaris should use "BACC" as the value of the APPNAME field.
Some applications may choose to specify a version as part of the APPNAME field. This is acceptable and may be useful in cases where the meaning of certain messages is redefined from one release to another. For example, an APPNAME value could be "BACC_2_5" for BACC version 2.5. The use the version within an application name is optional and may be introduced by applications in any release.
SEVERITY Field
The SEVERITY field is a numeric value from 0 to 7, providing eight different severities. The severities defined below match Cisco IOS severity levels. They are also standard syslog severities.
It is important that messages use the correct severity. An error in a certain component may be severe as far as the component is concerned, but if the overall application handles it gracefully, then the severity may be lower for the application as a whole. The following table lists guidelines that should be followed in determining the severity of a message.
|
Name/Severity Level |
Description |
|---|---|
|
Emergency (0) |
System or service is unusable. Examples:
|
|
Alert (1) |
Action must be taken immediately. Examples:
|
|
Critical (2) |
Critical condition. Similar to alert, but not necessarily requiring an immediate action. Examples:
|
|
Error (3) |
An error condition, which does not necessarily impact the ability of the service to continue to function. Examples:
|
|
Warning (4) |
A warning about some bad condition, which is not necessarily an error. Examples:
|
|
Notice (5) |
Notifications about system-level conditions, which are not error conditions. Examples:
|
|
Informational (6) |
Informational messages are distinguished from notification in that they provide information for internal flows of the application or per-request information instead of system-wide notifications. Informational messages are used for troubleshooting by users who are familiar with the basic flows of the application. Examples:
|
|
Debug (7) |
Debugging messages are similar to informational messages, but provide more detail and require the user to have better knowledge of system internal processing. These messages are typically reserved for very advanced users or Cisco technical support. Examples:
|
If an application uses a default severity level to determine which messages should be logged, then it is recommended that this level be set at 5 (notice). This ensures that all messages of severity 5 or higher are logged by default.
MSGNAME Field
The MSGNAME field of the HEADER uniquely identifies the message within the context of a given APPNAME. A fixed severity and logical meaning is associated with a specific MSGNAME within a specific APPNAME. In other words, the same message name cannot appear with different severity or a completely different logical meaning for the same APPNAME value even if the message is originated by a different process.
Message names are only unique within a given application (a given APPNAME value) unless the message is one of the standard messages. Thus, applications interpreting CiscoLog messages should be careful not to assume that a message with a given name has the same meaning for all applications that may use this message name. Indeed, if the message is not one of the standard messages, it may have a different severity and meaning in a different application.
The MSGNAME field must consist of at least two characters. Acceptable characters are limited to the following ASCII decimal values: 48-57 (numbers), 65-90 (upper-case letters) and 95 (underscore). While IOS allows lower-case letters as well, the vast majority of IOS messages use only the upper-case letters. In order to be consistent with established conventions we opted to restrict the character set to upper-case letters, numbers and underscore characters.
Both numeric-only or alphanumeric message names are acceptable. However, per IOS convention, it is recommended that a user-friendly alphanumeric label be preferred to a numeric-only label. For example, "NO_MEMORY" message name is preferred to a "341234" identifier.
A special tag mid is defined in the CiscoLog Standard Tags specification for identifying a numeric id corresponding to a message name. This tag can be used to provide a numeric message is in addition to the MSGNAME. When this tag is used, a given MSGNAME must always correspond to a single message id value. CiscoLog defines mid tag values for each standard message.
The length of the MSGNAME field must not exceed 30 characters, but most message names should be more concise. MSGNAME value may not conflict with the names defined in this standard.
A separate message name must be defined for each logically different message. In other words, while the message text for a given message name can vary by virtue of some substitutable parameters, logically different messages must have different message names.
The following is an example of correct use of message name:
11: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-4-CONNECTION_LOST: %[pname.orig=rdu]: Server lost connection to host [1.1.1.1]12: host.cisco.com: Jun 13 2003 23:11:52.458 UTC: %BACC-4-CONNECTION_LOST: %[pname.orig=rdu]: Server lost connection to host [2.2.2.2Notice that while the IP address of the host changes, it is still logically the same type of message. The following is an example of an INCORRECT use of the message name:
15: host.cisco.com: Jun 13 2003 23:11:52.458 UTC: %BACC-4-CONNECTION: %[pname.orig=rdu]: Server lost connection to host [2.2.2.2]16: host.cisco.com: Jun 13 2003 23:11:52.468 UTC: %BACC-4-CONNECTION: %[pname.orig=rdu]: Server re-established connection to host [2.2.2.2]
The use of a single message name for two different events in the above example is wrong and unacceptable. This is referred to as a "catch-all" message name and they must be avoided. Another extreme example is defining a message named "ERROR" and providing all error log messages under the same message name. This defeats the purpose of having the message name field, which is to enable external filtering of messages or easily trigger actions.
The only exception to the "no-catch-all" rule is when message cannot be identified ahead of time with anything better than a generic description or the users will not benefit from distinguishing the various subtypes of the message.
Although some applications may choose to do so, there is generally no need to define a separate message name for all debugging messages because debugging messages are not intended for automated filtering and action triggering based on message name. The sheer number of debugging messages and the highly dynamic nature of what is produced in them makes it very hard to define separate messages.
This specification proposes establishing a mailing list that could be used by groups for consulting purposes when in doubt about how to define certain messages. Currently, the mailing list alias used for this purpose is "cmn-logging".
TAGS Field
The TAGS field is optional in the message format. It provides a standard mechanism for applications to provide structured content in the form of key-value pairs which can be used to categorize or filter a set of messages externally.
Tags can be used to identify virtual logging channels. A set of messages flagged with the same tag can later be grouped together. For example, an application may flag messages belonging to a particular thread by supplying the corresponding tag. This would then allow filtering and viewing messages based on threads.
Virtual logging channels can also be established across multiple applications. For example, if all applications could tag requests from a device with device id (mac, ip, etc), then it would be easy to filter all messages related to that device even thought it communicates with multiple components.
Each application may define its own set of supported tags. A single tag consists of key and value pair separated by the equals sign and surrounded by square bracket characters as in the following format: [KEY=VALUE]. This is an example of a valid tag key-value pair [ip=123.23.22.22].
The TAGS field is prefixed with a percent character (ASCII decimal value 37) and ends with a sequence of colon and space characters (ASCII decimal values 58 and 32). When multiple tags are assembled together, no characters should appear between the tags as separators. The following example has a complete CiscoLog message with four tags:
12: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-4-BAD_REQUEST: %[pname.orig=rdu][comp=parser][mac=1,6,aa:bb:cc:11:22:33][txn=mytxn123]: Bad request received from device [1,6,aa:bb:cc:11:22:33]. Missing header.If TAGS field is missing, the percent character prefix and the trailing colon and space must be omitted. Thus, when the TAGS field is missing, the HEADER and MESSAGE fields must be separated by just a single colon and a space which follows the HEADER field. For example:
12: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-4-BAD_REQUEST: Bad request received from device [1,6,aa:bb:cc:11:22:33]. Missing header.Multiple tags with the same tag key can be provided in the same message. This essentially provides the capability for handling multi-valued keys. Below is an example of a message produced from a device which has two IP addresses where the application chose to provide both IP addresses in the TAGS field as well as the process name:
12: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-4-BAD_REQUEST: %[pname.orig=rdu][ip.orig=1.1.1.1][ip.orig=1.1.1.2]: Bad request received from device [1,6,aa:bb:cc:11:22:33]. Missing header.Any number of tags can be provided in a given message. The only limit is the overall length limit of the CiscoLog message of 800 octets.
If multiple tags are present, it is recommended that they appear in the alphanumeric order of the keys. This insures that tags are always produced in the same order. However, a different order may be chosen by an application if the order of tags is used to communicate some semantic value.
Tag Keys
Tag key must contain at least one character. The characters are limited to ASCII characters with decimal values 48-57 (numbers), 65-90 (upper-case letters), 95 (underscore), 97-122 (lower case letters). Use of lower-case letters is recommended. There is no strict limit on tag key length, although a general message limit of 800 octets applies and dictates that one should attempt to define short tag key names.
Tag Semantic Extensions
In some cases, a tag can have a standard value syntax, but different meaning depending on the content in which it is used. Tag semantic extensions are used to differentiate the contextual meaning of tags.
The semantic extension tags are created by appending the tag key with a single dot character (ASCII decimal value 46) and a text string consisting of characters from a proper character set.
For example, an "ip" tag defines syntax for an IP address representation, but no semantic value. An "ip" tag found in a CiscoLog message generally means only that this IP address is somehow related to the message. In some cases, such vague association is sufficient. However, sometimes, communicating semantic value could be useful.
A message may have two IP address tags associated with it, for example, from and to IP addresses. In this case, using tags "ip.from" and "ip.to" would communicate both the syntax of the tags and some semantic value. Another example, is a standard tag "ip.orig", which specifies the IP address of the host which originated the message. The following is an example of all three tags appearing together:
[ip.from=1.1.1.1][ip.to=2.2.2.2][ip.orig=123.12.111.1]Multiple levels of semantic extension tags are allowed with each extension providing meaning that is more specific. For example, tag key "ip.to.primary" is valid and could mean the primary IP address of the destination host.
The semantic value is much harder to standardize than the syntax because there can an infinite number of meanings for a given value depending on the context. Thus, it is anticipated that defining tag semantics extensions will be largely application specific.
Tag Values
Tag values may contain zero or more characters. The empty (zero characters) value is interpreted as unknown or undetermined value. The value must only include printable US ASCII characters (those in the ASCII decimal value range 32-126) and foreign language characters
There is a restriction on the use of three characters: "["," ]" and "\". The bracket characters (ASCII decimal values 91 & 93) must be escaped with a back slash character (ASCII decimal value 92) . This helps to avoid confusion with the brackets that signify the start/end of the tag. Thus, when the tag value needs to represent characters "[" or "]", a sequence of "\[" or "\]" is used instead respectively. When the escape character itself needs to be represented in the tag value, then instead of the "\" character a sequence of "\\" is used.
Use of non-printable (control) ASCII characters is not allowed in the TAG value field. Control characters include characters with ASCII decimal values 0-31 and 127. If application provides to a CiscoLog-compliant library a tag value string, which includes one or more control characters, the logging library must do the following. If the horizontal tab character (ASCII decimal value 9) is encountered, it must be replaced with one or more space characters (ASCII decimal value 32). Eight spaces per tab are recommended because this is a convention on most Unix and Windows platforms. Other control characters must each be replaced with a question mark character (ASCII decimal value 63). Technically, we only need to require escaping a closing bracket. However, requiring escaping both open and closing brackets simplifies parser code and provides for a more consistent display in raw form.
There is no strict limit on tag value length; although a general message length limit of 800 octets applies and dictates that one must be conservative.
Tag Guidelines
The TAGS field is optional in the CiscoLog message format. Tags do not replace substitutable parameters in the message body. Tags merely provide an additional way to identify and categorize messages.
Since tags are optional, they can be enabled or disabled by the application/user as required. There is no requirement for the same message to always be produced with the same set of tags. If the application supports a given tag, it does not necessarily mean that it must always produce it. This can be configurable. Indeed, it is recommended that applications provide the administrator with at least limited control over which tags get produces.
Application developers have a choice as to what information to make available in the tags and what in the message body. In some cases, the information may be duplicated between the two. This is acceptable.
The general guideline is to put all required information in the message body and make appropriate information available via tags. In other words, the message should provide sufficient meaning even when all tags are disabled. Tags merely provide additional useful information and a way to present it in a standard, easily filtered, form.
The following are two valid examples of a message where both the message and the message tags contain a MAC address. Example with tags disabled:
11: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-3-BAD_REQUEST: Bad request received from device [1,6,aa:bb:11:22:33:aa]. Missing header.In the above example, the MAC address appears as part of the message field – it is not a tag. In the following example, the tags are enabled. Even though MAC address is duplicated between the tag and the message, it is acceptable.
11: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-3-BAD_REQUEST: %[mac=1,6,aa:bb:11:22:33:aa][tid=thread1][txn=mytxn123]: Bad request received from device [1,6,aa:bb:11:22:33:aa]. Missing header.Process Identification Tag
One of the standard tags, pname.orig, is used to identify the logical process name which originates the message. Any application that seeks to provide originating process information must do so using the "pname.orig" tag.
This tag is extremely valuable in addition to information in the APPNAME field because some applications consist of multiple processes, each of which may originate logging messages. It is recommended that any application which consists of multiple processes always provide the "pname.orig" tag.
MESSAGE Field
The MESSAGE field provides a descriptive message about the logging event. This field may consist of one or more characters. The character set is limited to printable US ASCII characters (ASCII decimal values 32-126) and foreign language characters.
Use of non-printable (control) ASCII characters is not permitted in the MESSAGE field. Control characters include characters with ASCII decimal values 0-31 and 127. If application provides a CiscoLog-compliant library with message string, which includes one or more control characters, the logging library must do the following. If the horizontal tab character (ASCII decimal value 9) is encountered, it must be replaced with one or more space characters (ASCII decimal value 32). Eight spaces per tab are recommended because this is a convention on most Unix and Windows platforms. Other control characters must each be replaced with a question mark character (ASCII decimal value 63).
The maximum length of the MESSAGE field is constrained only by the maximum length of the entire message. The maximum length of the CiscoLog message must not exceed 800 octets. Another practical limitation is a potentially highly variable length of the TAGS field.
Message text may contain substitutable parameters, which provide necessary details about the message. For example, the IP address in the following example is a substitutable parameter.
11: host.cisco.com: Jun 13 2003 23:11:52.454 UTC: %BACC-3-INVALID_REQUEST: Invalid request received from device [1.22.111.222]. Missing header.It is recommended (but not required) that substitutable parameters be surrounded by bracket characters "[" and "]" as in the above example. It is further recommended that the message text and values of substitutable parameters do not include bracket characters. When it is not possible to avoid brackets characters in the values of substitutable parameters, it is recommended that the value at least does not include unbalances brackets (like an opening bracket without a closing one). When these recommendations are followed, it would be possible to programmatically extract substitutable parameter values out of a CiscoLog message. However, this recommendation is not a strict requirement.
Message text should be spell-checked. Editorial review is recommended. This includes all messages that can be seen by the customers, even debugging messages.
If the first word of the message is an English word, the first letter should be capitalized. Single sentence messages do not require a period at the end.
Internationalization
Foreign language characters are defined as characters with ASCII decimal values 0-126. Foreign language characters are supported in the HOST field, the value part of the TAGS field and the MESSAGE field.
Foreign language characters must be encoded using the Unicode standard UTF-8. UTF-8 provides encoding for any language without requiring the application to know local encoding/decoding rules for a particular language. In fact, the application encoding the message does not even need to know the language of the message. UTF-8 can encode any Unicode character.
UTF-8 encodes US ASCII characters exactly as they would normally be encoded in a 7-bit ASCII convention. This means that applications interpreting CiscoLog messages can assume that entire messages are encoded in UTF-8. On the other hand, applications producing CiscoLog messages can encode the entire message using US-ASCII 7-bit convention if they are known not to support foreign languages in their products.
Since UTF-8 can encode characters in any language, it is possible to mix and match languages. For example, it is anticipated that a one use-case would be the inclusion of just some parameters in foreign language in an otherwise English message. For example, an English message about user authentication could have a username in Japanese. Similarly, any number of languages can be combined in a CiscoLog message.
In order to take advantage of messages, which include a foreign language, a log viewer capable of interpreting UTF-8 would be necessary. Most likely, the log viewer would also require that the appropriate language fonts be installed on a given system. In a US-ASCII only editor, the user will see garbage for non-US-ASCII characters encoded in UTF-8, but should be able to see all US-ASCII text.
Internationalization support can be readily used with CiscoLog messages written to a local file. Syslog RFC 3164, however, does not currently define foreign language support. Thus, in order to take advantage of internationalization with a syslog server, one would need to use a server implementation, which was tested to correctly relay or store all 8-bits of each octet unchanged. This would ensure that UTF-8 encoded parts of the message retain all their information when foreign languages are used.
In UTF-8, a single character is encoded with one or more octets. The CiscoLog message length limit is specified as 800 octets. Developers must be aware that with foreign languages, the 800-octet length limit may mean fewer than 800 characters. When a message is split into a multi-part message, octets belonging to a single character must never be split into separate lines.
Versioning
CiscoLog does not provide any versioning information in the message format. Extensions to the format must be made within the restrictions of the format. CiscoLog message formats provides for extensions by way of defining additional tags.
If applications require changes to existing messages, the value of APPNAME can redefine message within the new space. For example, the application version can be appended to the application name as BACC_2_5 for BACC 2.5.
Feedback