Symbolizer Markup Format#
Overview#
This document defines a text format for log messages that can be processed by a symbolizing filter. The basic idea is that logging code emits text that contains raw address values and so forth, without the logging code doing any real work to convert those values to human-readable form. Instead, logging text uses the markup format defined here to identify pieces of information that should be converted to human-readable form after the fact. As with other markup formats, the expectation is that most of the text will be displayed as is, while the markup elements will be replaced with expanded text, or converted into active UI elements, that present more details in symbolic form.
This means there is no need for symbol tables, DWARF debugging sections, or similar information to be directly accessible at runtime. There is also no need at runtime for any logic intended to compute human-readable presentation of information, such as C++ symbol demangling. Instead, logging must include markup elements that give the contextual information necessary to make sense of the raw data, such as memory layout details.
This format identifies markup elements with a syntax that is both simple and
distinctive. It’s simple enough to be matched and parsed with straightforward
code. It’s distinctive enough that character sequences that look like the start
or end of a markup element should rarely if ever appear incidentally in logging
text. It’s specifically intended not to require sanitizing plain text, such as
the HTML/XML requirement to replace < with < and the like.
llvm-symbolizer includes a symbolizing
filter via its --filter-markup option. Also, LLVM utilites emit stack
traces as markup when the LLVM_ENABLE_SYMBOLIZER_MARKUP environment
variable is set.