Log origin context

Prysm can attach origin metadata to each emitted log message. When enabled, this metadata tells you which view, frame, task family, or task produced a warning, error, or informational message. This is especially useful when you are debugging multiple views, background tasks, CSS parsing, resource loading, or script output and need to identify the exact source of a log.

The origin metadata is delivered through the LogOriginInfo Origin; member of the cohtml::Logging::LogInfo struct and is available to every custom implementation of cohtml::Logging::ILogHandler. This includes the default log handler provided by Prysm, where everything is handled out of the box.

This feature builds directly on top of the structured logging changes introduced in release 3.0.0, where ILogHandler::WriteLog() started receiving a LogInfo object instead of just a severity value.

Enabling log origin context

Log origin metadata is opt-in and is configured through LibraryParams::LoggingFilters.EnabledContextFields. This keeps the default behavior unchanged for integrations that do not need the extra diagnostic information.

You can choose which fields to enable when initializing the library - for example, the snippet below will enable all available fields:

cohtml::LibraryParams params;
params.LoggingFilters = cohtml::Logging::LoggingSettings(
    cohtml::Logging::TargetUser::All,
    cohtml::Logging::MessageType::All,
    cohtml::Logging::Severity::Info,
    cohtml::Logging::LogContextFields::All);

If you only need part of the metadata, you can enable a narrower subset:

params.LoggingFilters.EnabledContextFields =
    cohtml::Logging::LogContextFields::ViewId |
    cohtml::Logging::LogContextFields::TaskName;

Reading the origin in a custom log handler

If you are using a custom log handler, you don’t have to change the signature of the WriteLog method, you simply access the Origin from the LogInfo parameter.

void WriteLog(cohtml::Logging::LogInfo info, const char* message, size_t length) override
{
    if (info.Origin.HasViewId())
    {
        // Route or annotate the message with the originating view.
    }

    WriteToEngineLog(info.Severity, message, length);
}

Reading the origin in the default log handler

If you use Prysm‘s default log handler, enabling the context fields is enough. The built-in formatter automatically prepends the available origin fields to the emitted message.

Example output:

[View:3 Frame:0 Family:24 Task:ParseCSS] Unable to parse declaration: width - var()

Available origin fields

When origin tracking is enabled, LogInfo::Origin may contain the following fields:

Field	Meaning
ViewId	The id of the cohtml::View that originated the log.
FrameId	The frame associated with the log, when applicable.
FamilyId	The task family that was executing when the log was emitted.
TaskName	The name of the active task, such as an internal parsing or networking task.

Not every log has every field populated. Only the fields you enabled are collected, and some messages naturally do not belong to a specific frame or task. Use the helper methods on LogOriginInfo (HasViewId(), HasFrameId(), HasFamilyId(), HasTaskName()) before consuming a value.

Recommended usage

• Enable ViewId when you need to distinguish logs coming from multiple active views.
• Add TaskName when you are debugging asynchronous systems such as CSS parsing, XHR, or resource loading.
• Enable FrameId only if your tooling or diagnostics need to track frame-specific work.
• Keep the enabled set minimal in shipping configurations if you want the smallest possible logging overhead.

Related information

• If you are already using categorized logging, this feature builds directly on top of LibraryParams::LoggingFilters.
• See Logging categories and filtering for the 3.0.0 logging API upgrade this feature extends.