> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

> Write plugin diagnostics through the Kernel's unified logger.

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:

| Level   | Use for                                                         |
| ------- | --------------------------------------------------------------- |
| `debug` | Diagnostic details useful while investigating behavior.         |
| `info`  | Normal lifecycle and meaningful state changes.                  |
| `warn`  | Recoverable problems or conditions that need attention.         |
| `error` | Failed operations or conditions that prevent the intended work. |

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](../kernel/config-log) 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:

```text theme={null}
component=plugin from=<plugin-name>
```

`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:

```json theme={null}
{
  "level": "INFO",
  "msg": "plugin initialized",
  "component": "plugin",
  "from": "my-plugin"
}
```

## 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:

```text theme={null}
cache refresh completed: items=24 source=remote
```

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.