Skip to main content

Category Extraction

Overview​

It's often desireable to be able to distinguish log messages originating from different modules, components, or layers within an application. Let's call this a "log category" -- the AutoExtract conventions make it easy to detect and extract a log category automatically. The result is stored into the category field.

How it works​

One or more categories are detected within a log message when a log message starts with one or more "category labels", where each category label is a single word followed by a colon. A single category is formed by combining all detected category labels separated by a period.

For example, the detected category is BackendLayer.Sublayer for the following log message:

BackendLayer: Sublayer: hello world

Category labels must be at the very start of a log message to be recognized as such, with the following exceptions:

  • One or more timestamps can appear before category labels
  • Bracketed or parenthetical terms can appear before category labels

Thus, the category labels would still be detected in the following log message:

2024-11-06 23:32:17.800 [T1537] BackendLayer: Sublayer: message

Whereas it would not detect any in the following (each category label must be a single word, and My is not a category label as it does not end in a colon):

My BackendLayer: Sublayer: message
tip

Many systems already log in this format and will work out of the box (for example, Unreal Engine). By adapting your app logs to follow this convention in general, you can make it easy to explore logs from different components of your application. This is optional, but recommended.

Example​

Try AutoExtract on the following log message from the Unreal Engine to see it compute the log category as LogRHI:

Test Log Message:

Manual override​

If you wish to manually override the category that is detected, set the value of the special category_override field. This will use this override value instead of the detected value. Note that if you attempt to specify the category field directly, it will rename this field to something else (e.g., category2). This logic ensures that the category value is not overridden by accident.

Disabling​

Set the X-No-Detect-Category HTTP header to true to disable automatic category extraction.