Interface ResourceDiagnostics
- All Known Implementing Classes:
DefaultResourceDiagnostics
Returned from two places, because two parties know different things. A resource type speaks
for the category through ResourceAiDelegate.getDiagnostics(): what these resources are
and what healthy looks like across all of them. An extension point speaks for one type within that category: what that implementation does and how
its failures read. The module implementing a type is the only one that knows the second kind of
thing, and the only one whose code changes when that implementation changes.
The resource type decides whether a digest exists at all. Declaring diagnostics on it is what puts an AI panel on the page; an extension point's declaration is inert until that happens, and cannot open the gate on its own. Extension point contributions are then gathered only from types that have a configured instance on this gateway, so the prompt stays proportional to what the gateway is actually running rather than to every type its installed modules could provide.
A digest also only reaches an operator where the page renders it. The shared resource-page templates mount the panel already; a page assembled by hand mounts it itself.
Capabilities are deliberately absent. Whether a resource type is visible to AI at all is the
resource type's decision, made through ResourceAiDelegate; an extension point plugging
into it cannot widen that.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic final recordA digest section heading and the function that renders its body, evaluated once per digest request. -
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionLogger names queried in addition to the MDC-identified events, for loggers that carry no per-instance MDC context — startup and manager-level loggers, typically.default @NonNull List<ResourceDiagnostics.DigestSection> Digest sections appended to the analysis flow only, for detail that would bloat the summary's context without changing the at-a-glance judgment.Guidance appended to the analysis flow only, for detail too long to justify on the cheap summary that runs on page load.default @NonNull List<ToolBundle> Tools the analysis agent may call while diagnosing these resources.default @NonNull List<ResourceDiagnostics.DigestSection> Digest sections appended to both flows, for live state the resource system does not hold — in-flight work, pool occupancy, anything read from the subsystem's own manager rather than from stored configuration.Guidance appended to both digest flows: what goes wrong here and how the errors read.The MDC key whose value is a resource instance's name, used to pull that instance's log events.
-
Field Details
-
NONE
Contributes nothing. A resource type whose AI delegate returns this gets no digest; returning anything else is the opt-in.
-
-
Method Details
-
getFraming
Guidance appended to both digest flows: what goes wrong here and how the errors read. WhereResourceAiDelegate.getDescription()says what a resource type is, this says how it fails.Name concrete symptoms and their usual causes, and keep it to what is specific. The platform already instructs the model on voice, output shape, and severity. Written for a model rather than an operator, and not localized for that reason.
- Returns:
- the framing text, or empty to contribute none.
-
getAnalysisFraming
Guidance appended to the analysis flow only, for detail too long to justify on the cheap summary that runs on page load. Config-check and log-interpretation guidance usually belongs here.- Returns:
- the analysis-only framing text, or empty to contribute none.
-
getDigestSections
Digest sections appended to both flows, for live state the resource system does not hold — in-flight work, pool occupancy, anything read from the subsystem's own manager rather than from stored configuration.Keep these cheap. The summary digest runs on page load.
- Returns:
- sections for both flows, or an empty list.
-
getAnalysisDigestSections
Digest sections appended to the analysis flow only, for detail that would bloat the summary's context without changing the at-a-glance judgment.- Returns:
- sections for the analysis flow, or an empty list.
-
getAnalysisTools
Tools the analysis agent may call while diagnosing these resources.These run in the gateway with whatever access the contributing module has. The
ResourceAiDelegate.AiCapabilitylevel governs reads of stored configuration, not what a tool does once invoked — a tool here is trusted code, and whoever contributes one is responsible for keeping it read-only and bounded.- Returns:
- tool bundles for the analysis flow, or an empty list.
-
getAdditionalLoggerNames
Logger names queried in addition to the MDC-identified events, for loggers that carry no per-instance MDC context — startup and manager-level loggers, typically.Prefer MDC identity, and derive any name here from the class that writes it rather than typing it. A literal that stops matching after a class rename fails silently: the query returns nothing and the digest reads as healthy.
Names may contain
*as a wildcard, and a builder is free to expand one declared logger into several entries —DefaultResourceDiagnosticsemits both a name and its subtree. Treat this list as query patterns rather than as exact logger names.These are queried on their own and unioned with the identity-matched events, so everything a pattern matches comes back whether or not it concerns one of this type's resources. Name a subtree the subsystem owns, not a shared parent: the digest labels what it can attribute and says the rest is subsystem-wide, but a pattern reaching another subsystem's loggers spends the section's budget on events nobody asked about.
- Returns:
- logger name patterns to query, or an empty list.
-
getLogIdentityMdcKey
The MDC key whose value is a resource instance's name, used to pull that instance's log events. A subsystem whose loggers are built withLoggerEx.newBuilder().mdcContext(key, name)should return that key here.Declaring the key is optional but preferred. Without it a digest infers the key by matching instance names against MDC values seen in the log store, which only works once the subsystem has logged something recent enough to survive pruning.
An extension point rarely needs this. Types sharing a resource type usually share its logging identity, declared once on the resource type, and differ only where an implementation tags its events with a key of its own.
- Returns:
- the MDC key, or empty to fall back to the resource type's, then to inference.
-