Class DefaultResourceDiagnostics

java.lang.Object
com.inductiveautomation.ignition.gateway.config.DefaultResourceDiagnostics
All Implemented Interfaces:
ResourceDiagnostics

public class DefaultResourceDiagnostics extends Object implements ResourceDiagnostics
The standard 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)))
    [...]
  • 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

      public Optional<String> getFraming()
      Description copied from interface: ResourceDiagnostics
      Guidance appended to both digest flows: what goes wrong here and how the errors read. Where ResourceAiDelegate.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:
      getFraming in interface ResourceDiagnostics
      Returns:
      the framing text, or empty to contribute none.
    • getAnalysisFraming

      public Optional<String> getAnalysisFraming()
      Description copied from interface: ResourceDiagnostics
      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.
      Specified by:
      getAnalysisFraming in interface ResourceDiagnostics
      Returns:
      the analysis-only framing text, or empty to contribute none.
    • getDigestSections

      public @NonNull List<ResourceDiagnostics.DigestSection> getDigestSections()
      Description copied from interface: ResourceDiagnostics
      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.

      Specified by:
      getDigestSections in interface ResourceDiagnostics
      Returns:
      sections for both flows, or an empty list.
    • getAnalysisDigestSections

      public @NonNull List<ResourceDiagnostics.DigestSection> getAnalysisDigestSections()
      Description copied from interface: ResourceDiagnostics
      Digest 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:
      getAnalysisDigestSections in interface ResourceDiagnostics
      Returns:
      sections for the analysis flow, or an empty list.
    • getAnalysisTools

      public @NonNull List<ToolBundle> getAnalysisTools()
      Description copied from interface: ResourceDiagnostics
      Tools the analysis agent may call while diagnosing these resources.

      These run in the gateway with whatever access the contributing module has. The ResourceAiDelegate.AiCapability level 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:
      getAnalysisTools in interface ResourceDiagnostics
      Returns:
      tool bundles for the analysis flow, or an empty list.
    • getAdditionalLoggerNames

      public @NonNull List<String> getAdditionalLoggerNames()
      Description copied from interface: ResourceDiagnostics
      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 — DefaultResourceDiagnostics emits 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:
      getAdditionalLoggerNames in interface ResourceDiagnostics
      Returns:
      logger name patterns to query, or an empty list.
    • getLogIdentityMdcKey

      public Optional<String> getLogIdentityMdcKey()
      Description copied from interface: ResourceDiagnostics
      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 with LoggerEx.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:
      getLogIdentityMdcKey in interface ResourceDiagnostics
      Returns:
      the MDC key, or empty to fall back to the resource type's, then to inference.
    • newBuilder

      public static DefaultResourceDiagnostics.Builder newBuilder()
    • build

      Builds diagnostics through DefaultResourceDiagnostics.Builder, for callers that configure them inline.
      Parameters:
      consumer - receives a fresh builder.