Skip to main content

Publishing public pipeline diagnostics

Plugins can emit structured public diagnostics when they run in a pipeline. These diagnostics appear alongside public content and are intended to help uploaders understand failures and ask the community for help.

Public diagnostics are not debug logs. Private implementation details belong in the internal plugin log, which is restricted to administrators with plugin-management permission.

Diagnostic shape​

type PublicDiagnostic = {
  level: "INFO" | "WARNING" | "ERROR";
  code: string;
  message: string;
  details?: unknown;
  helpUrl?: string;
};

Use the pipeline runtime's public diagnostic callback to publish this data. Continue to use the internal logging API for provider responses, request IDs, stack traces, and debugging context.

Author requirements​

  • Use a stable uppercase code containing letters, numbers, and underscores.
  • Write a concise, non-technical message.
  • Keep details bounded, JSON-serializable, and safe for anonymous visitors.
  • Use an HTTPS helpUrl.
  • Describe the actionable cause rather than transient implementation details.
  • Document plugin-specific codes and preserve their meaning after publication.

Never publish:

  • credentials, tokens, cookies, or authorization headers;
  • signed URLs or private storage paths;
  • email addresses, IP addresses, or private identifiers;
  • raw request or response bodies;
  • stack traces or internal prompt-debug data;
  • moderation data that contains private information;
  • provider internals that would materially help someone evade a check;
  • unbounded arbitrary payloads.

The host validates, bounds, and redacts public diagnostics before storage. Invalid entries are discarded. Existing arbitrary log output remains internal unless a plugin deliberately adopts this contract.

Designing useful codes​

Prefer a small set of stable codes that identify categories people can act on. For example:

ctx.diagnostics.public({
  level: "ERROR",
  code: "ARCHIVE_CONTAINS_EXECUTABLE",
  message: "The archive contains an executable file.",
  details: {path: "setup.exe"},
  helpUrl: "https://example.com/help/archive-check",
});

The diagnostic should remain useful when copied into a support discussion. Do not require consumers to parse the human-readable message; use the stable code for programmatic behavior.

Compatibility​

Pipeline attempts snapshot the plugin version and resolved configuration used for that execution. Adding optional fields to details is compatible, but renaming a code or changing its meaning is not.

For current first-party codes and operational guidance, see Plugin pipelines.