Skip to main content
Plugins should write diagnostics through the logging capability provided by the Kernel. This sends plugin log records into the same structured log stream as Kernel messages, regardless of whether the plugin runs as WASM or gRPC. The plugin logging boundary accepts a level and a message. The plugin does not choose the output format, configure the global log level, or write the component and from fields itself.

​
Log levels

Use the level that describes the operational meaning of the message: The Kernel filters plugin records using the global [Log].Level setting. For example, a plugin’s debug record is not emitted while the Kernel is running at info. See Logging configuration for the global format, level, and output behavior. Use info sparingly for events that operators need during normal operation. Do not emit one informational record for every internal step or request when the Kernel already provides an access or transport log for that activity.

​
Plugin identity in logs

The Kernel adds these fields to every plugin log record:
from is the registered plugin identity. For gRPC plugins, the Kernel derives it from the authenticated host callback. For WASM plugins, it comes from the plugin context established by the Kernel. A plugin cannot replace this value with an arbitrary source name. The same identity is used in JSON and text output. For example, a JSON record may look like:

​
Messages and structured context

The current plugin logging contract carries the log level and one message string. It does not provide an arbitrary key-value attribute map for plugin records. Keep messages concise and include stable context when it is needed to understand the event:
Do not include passwords, tokens, request bodies, Socket.IO payloads, secret values, or other sensitive data in a message. Logs are centralized at the Kernel and may be collected outside the plugin’s process.

​
Debug source locations

When the Kernel uses Level = "debug", its logger adds the source field to records. This is the logger call site in the Kernel’s host layer. It can help diagnose the host boundary, but it is not a reliable file and line location in the plugin’s own source code. Use message context to identify the plugin operation you are diagnosing. Do not rely on the debug source field as a plugin stack trace.

​
Logging failures

Logging should not replace error handling. Return or propagate an error when an operation fails, and add a log record when the failure needs operator visibility. Include enough context to identify the operation without exposing its input data. Use warn when the plugin can continue with a fallback. Use error when the operation failed and the plugin cannot provide the intended result. Use debug for successful diagnostic paths that would be too noisy at info. The Kernel supplies the same logging behavior to both supported plugin backends. Your plugin’s logging code should use the generated host binding for its selected backend rather than writing directly to a backend-specific output stream.