ChatGPTClaudeGrok / X / CursorGemini

DSH plugin diagnostics: logs, events, and read-only state

Plugin DevelopmentPublished 2026-11-17Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessplugin developmentloggingobservability
Production failures leave one undefined in the log and vanish on restart. Covers log granularity, events as diagnostics, read-only state, redaction.

Shipping a plugin is only half the job; the other half is making failures explain themselves. Too many plugins fail with a single undefined in the log, lose the crime scene on restart, and leave you guessing. A DSH plugin does not hand you observability. You decide, while writing the code, which evidence survives.

What you want to see when a DSH plugin breaks

Imagine one outage first, then work backwards to the fields you need. (source)

Ask yourself three questions:

  1. What is it doing? Initializing, ready, or stopped, and when did it last succeed.
  2. Why did it stop? An error code, a failing stage, a cancellation -- not just "it failed".
  3. What state is it in now? Entry counts, queue depth, the last cursor position.

Those answers decide which state fields you expose and where you log. If you cannot answer any of them, the plugin's internals are invisible from the outside.

The goal is not more logging. It is one log line that points to one code path, and one query that answers one question.

Logs: one DSH plugin fact per line

Packing several facts into a line trades searchability for readability. (source)

A useful line has a stable prefix, an action, and an outcome. The prefix makes grep work, the action says what happened, the outcome says how it ended.

Three habits:

  1. Fixed prefix -- include the plugin name so your output does not blur into other plugins' lines.
  2. One fact per record -- split "read finished" and "parse failed" into two lines instead of "read finished but parse failed, 3 entries".
  3. Name the stage on errors -- init failure, registration failure, and call failure are three different problems and must be distinguishable.

Restraint matters on hot paths. Stringifying a full object per request drives both log volume and CPU. Leave the detail to state queries; let logs record that something happened and how it ended.

Events as a DSH plugin diagnostic channel

Events are good at broadcasting what happened, bad at guaranteeing what must happen. (source)

In-process events have no persistence and no replay, and a listener that throws must not affect the publisher. Those three properties fix their role: notification and observation.

Good uses:

  1. Stage transitions -- index build started, finished, failed.
  2. Observable side effects -- which file was written, which cache was refreshed.
  3. Extension points for other plugins -- letting others hook into your flow.

Bad uses: notifications that must arrive, tasks that need retries, branches that change the main result. Reach for method calls or background jobs there; otherwise behavior silently differs depending on who is listening.

Read-only state beats logs in DSH plugin triage

State can be queried any time; a log waits for the next reproduction. (source)

The implementation is unglamorous: keep fields such as a readiness flag, entry count, last error, and last success time, and return a snapshot from one query entry point. That query does no heavy work and never triggers initialization.

Its value shows up in three situations:

  1. "Is there any data right now?" -- read the entry count instead of scrolling logs.
  2. "Is it stuck initializing?" -- the readiness flag and last error answer faster than guessing.
  3. "Is it leaking?" -- sample the counters over time and the trend is obvious.

Tie the fields to the Fiber. After unload they should be gone, not parked on a module-level object where the next load inherits the previous round's numbers.

Never log DSH plugin secret values

"Printing it makes debugging easier" is the most common cause of leaked credentials. (source)

Credentials live in config as references, with the value held by the provider. The moment you log the result of a resolve, you have bypassed the whole redaction chain. The session-telemetry/record waterfall transforms records on the telemetry path, but it does not cover your own console.log.

Safe to log: source layer (env, file, user-env), whether a value is configured, its length, resolution duration. Not safe: the value, full request headers, snippets of file contents.

A five-point DSH plugin diagnostics checklist

Run this before release and you delete half of your "cannot reproduce" tickets. (source)

  1. Every failure branch logs, and includes an error code and a stage.
  2. Key flows emit stage events, so outsiders can see start, finish, and failure.
  3. Read-only state is exposed and answers "what is happening now".
  4. No credentials, file contents, or full headers appear in logs.
  5. State fields expire with the plugin instead of leaking across instances.

Verification: make failures reproducible

The acceptance test is simple: someone can locate the fault without reading your code. (source)

  1. Force an initialization failure and assert the log names the stage and error code, not just "failed".
  2. Make one call throw and assert the last-error field updates in read-only state.
  3. Hot reload twice and assert no counter from the previous round survives.
  4. Point a credential reference at a configured value and assert only the source layer and length appear.
  5. Subscribe to stage events and assert exactly one start and one finish arrive, with no duplicates.

Counters doubling in step 3 mean the state lives at module scope. Plaintext in step 4 means your logging skipped the redaction rule.

For the redaction pipeline and channel split, read session telemetry and redaction; for load-time investigation, see local plugin debugging.

One line to close: one log line carries one fact, events only notify and observe, state fields answer questions on demand and die with the instance, and credentials never reach a log -- together, those four make failures diagnosable instead of mysterious.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

How much logging should a DSH plugin write on the hot path?

A DSH plugin log line should carry one fact on the critical path, and no more. DSH does not stop you from logging freely, but synchronous logging consumes load and request time, so never stringify large objects on a hot path. Add read-only state for detail instead of printing every variable.

Can DSH plugin events carry work, or only diagnostics?

Treat DSH plugin events as notifications, not as a business channel. DSH events are in-process broadcasts with no persistence or replay, and a throwing listener must not break the publisher. A business channel built on events collapses the moment nobody subscribes; use method calls or services for work that must happen.

Why expose DSH plugin read-only state instead of more logs?

DSH plugin read-only state answers questions on demand; logs only capture one instant. DSH read-only state can report entry counts, readiness flags, and the last error whenever you ask, without waiting for a reproduction. Turning key counters into state fields is the cheapest diagnostic investment.

May I log DSH plugin config values and request headers?

No: DSH plugin logs must not carry credential values or full request headers. DSH stores credentials as references and the provider holds the secret, so printing a resolved value bypasses redaction entirely; only the telemetry path goes through the session-telemetry/record waterfall. Log the source layer, whether it is set, and the length.

Related Terms

ctx.emit
ctx.emit is the entry point for publishing an in-process event; events have no persistence or replay, which makes them suitable for notification and diagnosis, not for work that must be delivered.— DeepSeek Harness Docs - Plugins and Lifecycle
session-telemetry/record
session-telemetry/record is the waterfall every exported telemetry record passes through; a listener can transform it, and skipping next replaces everything below.— DeepSeek Harness Reference - Session Telemetry
read-only state
Read-only state is a snapshot a plugin exposes for inspection; queries compute or read a cached value, trigger no side effects, and can replace extra logging during triage.— DeepSeek Harness Docs - Plugins and Lifecycle
Fiber
A Fiber is the lifecycle scope of one plugin instance; its registrations disappear on unload, so diagnostic fields must not outlive the instance.— DeepSeek Harness Docs - Plugins and Lifecycle

Sources