From 1605a27a0eab631905974d1c3b0d7499efb432d2 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Sun, 4 Jan 2026 09:19:04 -0500 Subject: [PATCH] docs: add logging best practices for plugin authors adds section on using client.app.log() instead of console.log for structured logging in plugins --- packages/web/src/content/docs/plugins.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx index 59a7010833d4..11ecfcfedc61 100644 --- a/packages/web/src/content/docs/plugins.mdx +++ b/packages/web/src/content/docs/plugins.mdx @@ -288,6 +288,25 @@ Your custom tools will be available to opencode alongside built-in tools. --- +### Logging + +Use `client.app.log()` instead of `console.log` for structured logging: + +```ts title=".opencode/plugin/my-plugin.ts" +export const MyPlugin = async ({ client }) => { + await client.app.log({ + service: "my-plugin", + level: "info", + message: "Plugin initialized", + extra: { foo: "bar" } + }) +} +``` + +Levels: `debug`, `info`, `warn`, `error`. See [SDK documentation](https://opencode.ai/docs/sdk) for details. + +--- + ### Compaction hooks Customize the context included when a session is compacted: