Class DefaultResourceDiagnostics
- All Implemented Interfaces:
ResourceDiagnostics
ResourceDiagnostics. Build one inline from an extension point:
@Override
public ResourceDiagnostics getDiagnostics() {
return DefaultResourceDiagnostics.build(d -> d
.framing("""
What goes wrong with this particular type and how its errors read, in terms an
operator would recognise. Keep it to what is specific to this implementation.
""")
.additionalLogger(MyImplementation.class.getName()));
}
or from a resource type, through its AI delegate:
ResourceTypeMeta.newBuilder(MyConnectionConfig.class)
.buildAiDelegate(ai -> ai
.diagnostics(d -> d
.framing(MY_SUBSYSTEM_FRAMING)
.logIdentityMdcKey(MY_INSTANCE_NAME_MDC_KEY)))
[...]
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classCollects what a resource type or one extension point contributes to a digest.Nested classes/interfaces inherited from interface ResourceDiagnostics
ResourceDiagnostics.DigestSection -
Field Summary
Fields inherited from interface ResourceDiagnostics
NONE -
Constructor Summary
ConstructorsConstructorDescriptionDefaultResourceDiagnostics(@Nullable String framing, @Nullable String analysisFraming, List<ResourceDiagnostics.DigestSection> digestSections, List<ResourceDiagnostics.DigestSection> analysisDigestSections, List<ToolBundle> analysisTools, List<String> additionalLoggerNames, @Nullable String logIdentityMdcKey) -
Method Summary
Modifier and TypeMethodDescriptionstatic DefaultResourceDiagnosticsbuild(Consumer<DefaultResourceDiagnostics.Builder> consumer) Builds diagnostics throughDefaultResourceDiagnostics.Builder, for callers that configure them inline.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.@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.@NonNull List<ToolBundle> Tools the analysis agent may call while diagnosing these resources.@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.
-
Constructor Details
-
DefaultResourceDiagnostics
public DefaultResourceDiagnostics(@Nullable String framing, @Nullable String analysisFraming, List<ResourceDiagnostics.DigestSection> digestSections, List<ResourceDiagnostics.DigestSection> analysisDigestSections, List<ToolBundle> analysisTools, List<String> additionalLoggerNames, @Nullable String logIdentityMdcKey) - Parameters:
framing- guidance for both digest flows, or null.analysisFraming- guidance for the analysis flow only, or null.digestSections- sections for both flows; copied.analysisDigestSections- sections for the analysis flow; copied.analysisTools- tools for the analysis flow; copied.additionalLoggerNames- loggers queried alongside MDC-identified events; copied.logIdentityMdcKey- MDC key naming an instance, or null.
-
-
Method Details
-
getFraming
Description copied from interface:ResourceDiagnosticsGuidance 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.
- Specified by:
getFramingin interfaceResourceDiagnostics- Returns:
- the framing text, or empty to contribute none.
-
getAnalysisFraming
Description copied from interface:ResourceDiagnosticsGuidance 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.- Specified by:
getAnalysisFramingin interfaceResourceDiagnostics- Returns:
- the analysis-only framing text, or empty to contribute none.
-
getDigestSections
Description copied from interface:ResourceDiagnosticsDigest 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.
- Specified by:
getDigestSectionsin interfaceResourceDiagnostics- Returns:
- sections for both flows, or an empty list.
-
getAnalysisDigestSections
Description copied from interface:ResourceDiagnosticsDigest sections appended to the analysis flow only, for detail that would bloat the summary's context without changing the at-a-glance judgment.- Specified by:
getAnalysisDigestSectionsin interfaceResourceDiagnostics- Returns:
- sections for the analysis flow, or an empty list.
-
getAnalysisTools
Description copied from interface:ResourceDiagnosticsTools 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.- Specified by:
getAnalysisToolsin interfaceResourceDiagnostics- Returns:
- tool bundles for the analysis flow, or an empty list.
-
getAdditionalLoggerNames
Description copied from interface:ResourceDiagnosticsLogger 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.
- Specified by:
getAdditionalLoggerNamesin interfaceResourceDiagnostics- Returns:
- logger name patterns to query, or an empty list.
-
getLogIdentityMdcKey
Description copied from interface:ResourceDiagnosticsThe 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.
- Specified by:
getLogIdentityMdcKeyin interfaceResourceDiagnostics- Returns:
- the MDC key, or empty to fall back to the resource type's, then to inference.
-
newBuilder
-
build
public static DefaultResourceDiagnostics build(Consumer<DefaultResourceDiagnostics.Builder> consumer) Builds diagnostics throughDefaultResourceDiagnostics.Builder, for callers that configure them inline.- Parameters:
consumer- receives a fresh builder.
-