Tagmap paths and file precedence

The following parameters specify the paths of tagmap files: DiagTagMapsBaseline and DiagTagMapsUser.

Each path can contain a list of files delimited by semicolons. Do not use spaces between file paths (this is required to enable Windows paths, which allow spaces as part of the path).

Whenever TRC reads the files, it parses all the files in all paths in order. Ordered parsing is an important concept because it establishes the precedence of tags when they appear in more than one tagmap file. TRC uses the last occurrence of a definition.

TRC parses tagmap paths in this order:

1. DiagTagMapsBaseline—Tagmap files provided during Nuance Recognizer installation; this is the baseline TRC configuration.
2. DiagTagMapsUser—Tagmap files provided by the application developer; these paths override the voice platform and baseline TRC configurations.

Within each path, the order of the files determines the order of the parse. In the example below, the parse order is a, b, c, e, and f:

DiagTagMapsBaseline  = a.txt;b.txt;c.txt

DiagTagMapsUser      = e.txt;f.txt

User-defined tagmap files

User tagmap files are usually smaller than the baseline or platform files. This simplifies your activities by allowing you to specify only the tags you care about in a small file.

Using tags to control data written to logs

TRC defines tags to be integers which represent some family, class, or subsystem within an application. Logging related operations are internally driven by whether a given tag has been enabled. The use of tags allows fine grained control over what information is logged at any given time, by only logging information whose tag has been enabled.

For example, there may be a tag defined for all recognition hypothesis construction, and another tag for prompt construction. A debugging session by a speech scientist may enable just the recognition hypothesis tag. An application developer may enable only the prompt construction. A voice platform integrator may enable both, neither, or go back and forth at different times.

The ability to arbitrarily turn on and off tags enables logging to be done only for the subsystem of interest, without seeing unnecessary data. This significantly increases the efficiency of the trouble shooting effort by enabling focussed data analysis and minimizing the logging of irrelevant data.

Format and contents of tagmap files

You can configure TRC diagnostic messages in text files known as tagmap files. Below, the tagmap fragment shows the format accepted by the TRC engine. For more information, see Configuring Recognizer diagnostic logging.

Each non-comment line in the file consists of 3 fields, with an optional comment. Comments begin with #.

#

# default SWItrc tagmap file this file defines a 

# dictionary of SWItrc tags and their corresponding names,

# parsed by an as yet undefined configuration manager for

# TRC.

# format:

#

# name : tag : enabled 

#

# where:

#

# name—a string representing the tag name for printing

#

# tag—the tag number

#

# enabled -indicates if the tag is enabled by default

#   values are: 

#     yes (explicitly enabled),

#     no (explicitly disabled),

#     <blank> (implicitly disabled)

#

# name             : tag value  : enabled by default?

# ----               ---------    ------------------

ERROR_CRITICAL_OOS      : 0     :  yes  # can't be disabled

ERROR_SEVERE_SA         : 1     :  yes  # can't be disabled

WARNING_NSA             : 2     :  yes  # can't be disabled

LOG_CLNT_SRVR           : 5     : 

LOG_DLBG_PARSER         : 10    : 

LOG_FILE_PARSER         : 11    : 

LOG_MEMORY_PARSER       : 12    : 

LOG_SENT_PARSER         : 13    : 

LOG_SING_NAME_PARSER    : 14    : 

LOG_SPELL_PARSER        : 15    : 

LOG_STREET_ADDR_PARSER  : 16    : 

Name field

The first field is the name of the tag. The name is the string which appears in the logging output as a human readable string.

The above sample uses all capital letters, but this isn't a requirement. Any alpha numeric character, except a colon (:) may be used in the tag name field.

Tag Value field

The second field is the actual integer value. This value must be consistent with all instrumented code. It’s up to the instrumenter to ensure this value is correct.

Nuance has defined ranges for use by different aspects of a system. These ranges are defined by convention, there is no enforcement mechanism in place. The following table shows the basic ranges conventionally defined for tag values.

	Low value	High value	Notes
Nuance Recognizer core	0	24000	Core product Nuance product developers define tags in this range
Platform	24001	40000	Voice platform and runtime environment related, including platform services (for example, AudioSource, AudioPlayer). Voice platform integrators define tags in this range.
Application	100000	232	Available to application developers

Enabled field

The third field indicates whether to enable or disable the tag. If "yes," the tag is enabled when the file is parsed. If "no" or blank, the tag is disabled.

Because the tagmap files are periodically loaded by TRC at runtime, you can enable and disable USER tags (but not the baseline tag maps in defaultTagMap.txt) without restarting an application by editing the appropriate file. The DiagConfigPollSecs configuration parameter specifies the number of seconds between loads.