Output runtime diagnostics data as JSON, XML or PlantUML diagrams

Output runtime diagnostics data as JSON, XML or PlantUML diagrams

Siegfried Steiner
Siegfried Steiner
16 min read

Categories

Tags

Understanding a system’s runtime state can be challenging. Monitoring endpoints and logs often provide data that is difficult to interpret. When analyzing the internal behavior of a system, dedicated diagnostic information can be invaluable, especially when visualized. Generating on-demand snapshots of a system’s state can reveal what is happening under the hood. Once canonical schemas that represent system state are in place, generating diagnostics and reports in XML, JSON or PlantUML becomes straightforward.

Diagnostic interfaces, beyond the well-known monitoring endpoints, should be treated as first-class citizens of critical deployment artifacts. In production environments, you cannot simply place breakpoints or inspect variables with your IDE to understand a system’s internal state. Without dedicated diagnostic interfaces that expose runtime information, reproducing issues requires a debug-enabled environment with an attached debugger, which is rarely feasible in production. Moreover, some issues only become apparent and reproducible only when you have knowledge of the system’s internal state. A common but impractical workaround is to deploy versions filled with additional logging statements tracing variable values which clutters both the logs and the codebase. A more effective approach is to provide a diagnostic interface that can generate reports and snapshots of the system’s internal state on demand.

The diagnostic interface may be a web endpoint that accepts query parameters to isolate the data of interest and its representation or an MBean accessible via JMX through tools such as JConsole. Given the broad support of web endpoints by the various motoring frameworks, web endpoints are considered a natural choice for a diagnostic interface.

JSON alike document for a serial data communication buffer at runtime […] 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

{
  label: "CrcSegmentDecorator",
  alias: "CrcSegmentDecorator",
  description: "A segment decorator enriching the encapsulated segment with a CRC checksum.",
  identifier: "CrcSegmentDecorator@5025a98f",
  type: "org.refcodes.serial.CrcSegmentDecorator",
  hash: 1344645519,
  value: [ 2, 88, 1, 41, 20, 0, 0, 12, 0, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ],
  properties: {
    "CRC_ALGORITHM": "CRC-16/CCITT-FALSE",
    "CRC_BYTE_WIDTH": 2,
    "CRC_CHECKSUM": 22530,
    "CRC_CHECKSUM_CONCATENATION_MODE": "PREPEND",
    "CRC_CHECKSUM_HEX": [ 2, 88 ],
    "CRC_CHECKSUM_LITTLE_ENDIAN_BYTES": [ 2, 88 ],
    "CRC_ENDIANESS": "LITTLE",
    "LENGTH": 21
  },
  children: [
    {
      label: "SegmentComposite",
      alias: "SegmentComposite",
      description: "A body containing a composite segment as payload.",
      identifier: "SegmentComposite@544fe44c",
      type: "org.refcodes.serial.SegmentComposite",
      hash: 1414521932,
      value: [ 1, 41, 20, 0, 0, 12, 0, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ],
      properties: {
        "LENGTH": 19
      },
      children: [
        {
          label: "BooleanSegment",
          alias: "booleanSegment",
          description: "A segment containing an boolean payload.",
          identifier: "BooleanSegment@60c6f5b",
          type: "org.refcodes.serial.BooleanSegment",
          hash: 101478235,
          value: [ 1 ],
          properties: {
            "LENGTH": 1,
            "VERBOSE": "true"
          }
        },
        {
          label: "IntSegment",
          alias: "intSegment",
          description: "A body containing an integer payload.",
          identifier: "IntSegment@2038ae61",
          type: "org.refcodes.serial.IntSegment",
          hash: 540585569,
          value: [ 41, 20, 0, 0 ],
          properties: {
            "ENDIANESS": "LITTLE",
            "LENGTH": 4,
            "VERBOSE": "5161"
          }
        },
        {
          label: "AllocSectionDecoratorSegment",
          alias: "AllocSectionDecoratorSegment",
          description: "An allocation decorator referencing a decoratee and prefixing the length of the decoratee in bytes.",
          identifier: "AllocSectionDecoratorSegment@3c0f93f1",
          type: "org.refcodes.serial.AllocSectionDecoratorSegment",
          hash: 1007653873,
          value: [ 12, 0, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ],
          properties: {
            "ALLOC_LENGTH": 12,
            "ALLOC_LENGTH_WIDTH": 2,
            "ENDIANESS": "LITTLE",
            "LENGTH": 14
          },
          children: [
            {
              label: "StringSection",
              alias: "stringSection",
              description: "A section containing a string payload.",
              identifier: "StringSection@31dc339b",
              type: "org.refcodes.serial.StringSection",
              hash: 836514715,
              value: [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ],
              properties: {
                "LENGTH": 12,
                "VERBOSE": "Hello world!"
              }
            }
          ]
        }
      ]
    }
  ]
}

The diagnostics data may be served in an arbitrary notation which then is to be interpreted as required. For example, the data may be provided as XML or JSON and then further processed or as PlantUML for visualization and analysis.

Diagnostic interface considerations

Providing a diagnostic interface involves three key parts: First, gather the runtime state in a canonical schema. Second, generate reports from that schema in formats such as XML, JSON or PlantUML. Third, expose these generated reports through a diagnostic interface for easy access and analysis.

1. Gather the runtime state in a canonical schema

The canonical model captures the system’s runtime state. This diagnostic data is organized as nested instances of a Schema class. To remain flexible, the data is stored in a map of arbitrary key/value pairs. For convenience, common diagnostic properties such as identifier, alias, value or description can be exposed through dedicated methods with the meaning of these properties depending on the specific diagnostic purpose. When rendered, these common properties use fixed lower camel case names, while custom properties remain data and child schemas are represented as ordered children.

Canonical schema class diagram Serial schema implementation class diagram

Any data structure intended to provide diagnostic data implements the Schemable interface, which requires the implementation of a toSchema() method. This method returns a Schema instance that describes the diagnostic data of the structure. If any member fields within the object graph also implement Schemable, their toSchema() methods are invoked in turn and their resulting Schema instances are added as children to the current one. This recursive process builds a nested Schema hierarchy that represents the complete diagnostic view of the data structure.

2. Generate XML, JSON or PlantUML reports from the schema

The SchemaVisitor interface defines methods for traversing a Schema hierarchy according to the Visitor pattern. By invoking a Schema’s visit() method with a specific SchemaVisitor implementation, reports can be generated in various formats. The visitor traverses the entire Schema hierarchy and, depending on its implementation, produces output in JSON, XML, PlantUML or other notations. The predefined SchemaNotation.JSON uses the compact JSON-like notation shown above, while SchemaNotation.JSON_STRICT produces standards-compliant JSON.

PlantUML source code of a serial data communication buffer at runtime […] 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271

@startuml

object "ComplexTypeSegment@37574691" {
  label = "ComplexTypeSegment"
  alias = "ComplexTypeSegment"
  description = "A body containing a composite segment as payload."
  identifier = "ComplexTypeSegment@37574691"
  type = org.refcodes.serial.ComplexTypeSegment
  hash = 928466577
  value = [0x33, 0x00, 0xaf, 0x93, 0x01, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x41, 0xaf, 0x93, 0x01, 0x00, 0x5d, 0x56, 0x00, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x42, 0x5d, 0x56, 0x00, 0x00, 0xad, 0xc9, 0x04, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x43, 0xad, 0xc9, 0x04, 0x00]
  ___
  LENGTH = 53
}

object "AllocSectionDecoratorSegment@70beb599" {
  label = "AllocSectionDecoratorSegment"
  alias = "AllocSectionDecoratorSegment"
  description = "An allocation decorator referencing a decoratee and prefixing the length of the decoratee in bytes."
  identifier = "AllocSectionDecoratorSegment@70beb599"
  type = org.refcodes.serial.AllocSectionDecoratorSegment
  hash = 1891546521
  value = [0x33, 0x00, 0xaf, 0x93, 0x01, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x41, 0xaf, 0x93, 0x01, 0x00, 0x5d, 0x56, 0x00, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x42, 0x5d, 0x56, 0x00, 0x00, 0xad, 0xc9, 0x04, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x43, 0xad, 0xc9, 0x04, 0x00]
  ___
  ALLOC_LENGTH = 51
  ALLOC_LENGTH_WIDTH = 2
  ENDIANESS = "LITTLE"
  LENGTH = 53
}

object "SegmentArraySection@6a79c292" {
  label = "SegmentArraySection"
  alias = "/"
  description = "An array segment containing a fixed length elements array as payload."
  identifier = "SegmentArraySection@6a79c292"
  type = org.refcodes.serial.SegmentArraySection
  hash = 1786364562
  value = [0xaf, 0x93, 0x01, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x41, 0xaf, 0x93, 0x01, 0x00, 0x5d, 0x56, 0x00, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x42, 0x5d, 0x56, 0x00, 0x00, 0xad, 0xc9, 0x04, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x43, 0xad, 0xc9, 0x04, 0x00]
  ___
  LENGTH = 51
}

object "SegmentComposite@11e21d0e" {
  label = "SegmentComposite"
  alias = "SegmentComposite"
  description = "A body containing a composite segment as payload."
  identifier = "SegmentComposite@11e21d0e"
  type = org.refcodes.serial.SegmentComposite
  hash = 300031246
  value = [0xaf, 0x93, 0x01, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x41, 0xaf, 0x93, 0x01, 0x00]
  ___
  LENGTH = 17
}

object "IntSegment@5e25a92e" {
  label = "IntSegment"
  alias = "/payload"
  description = "A body containing an integer payload."
  identifier = "IntSegment@5e25a92e"
  type = org.refcodes.serial.IntSegment
  hash = 1579526446
  value = [0xaf, 0x93, 0x01, 0x00]
  ___
  ENDIANESS = "LITTLE"
  LENGTH = 4
  VERBOSE = "103343"
}

object "AllocSectionDecoratorSegment@4df828d7" {
  label = "AllocSectionDecoratorSegment"
  alias = "AllocSectionDecoratorSegment"
  description = "An allocation decorator referencing a decoratee and prefixing the length of the decoratee in bytes."
  identifier = "AllocSectionDecoratorSegment@4df828d7"
  type = org.refcodes.serial.AllocSectionDecoratorSegment
  hash = 1308109015
  value = [0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x41]
  ___
  ALLOC_LENGTH = 7
  ALLOC_LENGTH_WIDTH = 2
  ENDIANESS = "LITTLE"
  LENGTH = 9
}

object "StringSection@b59d31" {
  label = "StringSection"
  alias = "/name"
  description = "A section containing a string payload."
  identifier = "StringSection@b59d31"
  type = org.refcodes.serial.StringSection
  hash = 11902257
  value = [0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x41]
  ___
  LENGTH = 7
  VERBOSE = "SensorA"
}

"AllocSectionDecoratorSegment@4df828d7" --> "StringSection@b59d31" : <has>

object "IntSegment@62fdb4a6" {
  label = "IntSegment"
  alias = "/value"
  description = "A body containing an integer payload."
  identifier = "IntSegment@62fdb4a6"
  type = org.refcodes.serial.IntSegment
  hash = 1660794022
  value = [0xaf, 0x93, 0x01, 0x00]
  ___
  ENDIANESS = "LITTLE"
  LENGTH = 4
  VERBOSE = "103343"
}

"SegmentComposite@11e21d0e" --> "IntSegment@5e25a92e" : <has>
"SegmentComposite@11e21d0e" --> "AllocSectionDecoratorSegment@4df828d7" : <has>
"SegmentComposite@11e21d0e" --> "IntSegment@62fdb4a6" : <has>

object "SegmentComposite@23bb8443" {
  label = "SegmentComposite"
  alias = "SegmentComposite"
  description = "A body containing a composite segment as payload."
  identifier = "SegmentComposite@23bb8443"
  type = org.refcodes.serial.SegmentComposite
  hash = 599491651
  value = [0x5d, 0x56, 0x00, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x42, 0x5d, 0x56, 0x00, 0x00]
  ___
  LENGTH = 17
}

object "IntSegment@1dd02175" {
  label = "IntSegment"
  alias = "/payload"
  description = "A body containing an integer payload."
  identifier = "IntSegment@1dd02175"
  type = org.refcodes.serial.IntSegment
  hash = 500179317
  value = [0x5d, 0x56, 0x00, 0x00]
  ___
  ENDIANESS = "LITTLE"
  LENGTH = 4
  VERBOSE = "22109"
}

object "AllocSectionDecoratorSegment@31206beb" {
  label = "AllocSectionDecoratorSegment"
  alias = "AllocSectionDecoratorSegment"
  description = "An allocation decorator referencing a decoratee and prefixing the length of the decoratee in bytes."
  identifier = "AllocSectionDecoratorSegment@31206beb"
  type = org.refcodes.serial.AllocSectionDecoratorSegment
  hash = 824208363
  value = [0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x42]
  ___
  ALLOC_LENGTH = 7
  ALLOC_LENGTH_WIDTH = 2
  ENDIANESS = "LITTLE"
  LENGTH = 9
}

object "StringSection@3e77a1ed" {
  label = "StringSection"
  alias = "/name"
  description = "A section containing a string payload."
  identifier = "StringSection@3e77a1ed"
  type = org.refcodes.serial.StringSection
  hash = 1048027629
  value = [0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x42]
  ___
  LENGTH = 7
  VERBOSE = "SensorB"
}

"AllocSectionDecoratorSegment@31206beb" --> "StringSection@3e77a1ed" : <has>

object "IntSegment@3ffcd140" {
  label = "IntSegment"
  alias = "/value"
  description = "A body containing an integer payload."
  identifier = "IntSegment@3ffcd140"
  type = org.refcodes.serial.IntSegment
  hash = 1073533248
  value = [0x5d, 0x56, 0x00, 0x00]
  ___
  ENDIANESS = "LITTLE"
  LENGTH = 4
  VERBOSE = "22109"
}

"SegmentComposite@23bb8443" --> "IntSegment@1dd02175" : <has>
"SegmentComposite@23bb8443" --> "AllocSectionDecoratorSegment@31206beb" : <has>
"SegmentComposite@23bb8443" --> "IntSegment@3ffcd140" : <has>

object "SegmentComposite@1372ed45" {
  label = "SegmentComposite"
  alias = "SegmentComposite"
  description = "A body containing a composite segment as payload."
  identifier = "SegmentComposite@1372ed45"
  type = org.refcodes.serial.SegmentComposite
  hash = 326298949
  value = [0xad, 0xc9, 0x04, 0x00, 0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x43, 0xad, 0xc9, 0x04, 0x00]
  ___
  LENGTH = 17
}

object "IntSegment@1176dcec" {
  label = "IntSegment"
  alias = "/payload"
  description = "A body containing an integer payload."
  identifier = "IntSegment@1176dcec"
  type = org.refcodes.serial.IntSegment
  hash = 293002476
  value = [0xad, 0xc9, 0x04, 0x00]
  ___
  ENDIANESS = "LITTLE"
  LENGTH = 4
  VERBOSE = "313773"
}

object "AllocSectionDecoratorSegment@120d6fe6" {
  label = "AllocSectionDecoratorSegment"
  alias = "AllocSectionDecoratorSegment"
  description = "An allocation decorator referencing a decoratee and prefixing the length of the decoratee in bytes."
  identifier = "AllocSectionDecoratorSegment@120d6fe6"
  type = org.refcodes.serial.AllocSectionDecoratorSegment
  hash = 302870502
  value = [0x07, 0x00, 0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x43]
  ___
  ALLOC_LENGTH = 7
  ALLOC_LENGTH_WIDTH = 2
  ENDIANESS = "LITTLE"
  LENGTH = 9
}

object "StringSection@4ba2ca36" {
  label = "StringSection"
  alias = "/name"
  description = "A section containing a string payload."
  identifier = "StringSection@4ba2ca36"
  type = org.refcodes.serial.StringSection
  hash = 1268959798
  value = [0x53, 0x65, 0x6e, 0x73, 0x6f, 0x72, 0x43]
  ___
  LENGTH = 7
  VERBOSE = "SensorC"
}

"AllocSectionDecoratorSegment@120d6fe6" --> "StringSection@4ba2ca36" : <has>

object "IntSegment@3444d69d" {
  label = "IntSegment"
  alias = "/value"
  description = "A body containing an integer payload."
  identifier = "IntSegment@3444d69d"
  type = org.refcodes.serial.IntSegment
  hash = 876926621
  value = [0xad, 0xc9, 0x04, 0x00]
  ___
  ENDIANESS = "LITTLE"
  LENGTH = 4
  VERBOSE = "313773"
}

"SegmentComposite@1372ed45" --> "IntSegment@1176dcec" : <has>
"SegmentComposite@1372ed45" --> "AllocSectionDecoratorSegment@120d6fe6" : <has>
"SegmentComposite@1372ed45" --> "IntSegment@3444d69d" : <has>

"SegmentArraySection@6a79c292" --> "SegmentComposite@11e21d0e" : <has>
"SegmentArraySection@6a79c292" --> "SegmentComposite@23bb8443" : <has>
"SegmentArraySection@6a79c292" --> "SegmentComposite@1372ed45" : <has>

"AllocSectionDecoratorSegment@70beb599" --> "SegmentArraySection@6a79c292" : <has>

"ComplexTypeSegment@37574691" --> "AllocSectionDecoratorSegment@70beb599" : <has>
@enduml

These reports can then be served through a diagnostic interface for easy access and analysis. In case of a PlantUmlVisitor implementation, the result will be a a text in PlantUML notation which then can be rendered as UML diagrams.

Serial data diagnostics

3. Expose the generated reports through a diagnostic interface

Using Spring Boot, the generated reports can be served through a WebEndpoint that implements the ReadOperation method. The example below shows how this can be done.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

@Component
@WebEndpoint(id = "diagnostics")
public class DiagnosticsEndpoint {

	private Schemable data = ... // The data variable holds an instance implementing the Schemable interface

	// ...

	@ReadOperation
	public WebEndpointResponse<String> getDiagnosticsAsPlantUml() {
		Schema schema = data.toSchema();
		String diagnostics = schema.visit(new PlantUmlVisitor());
		return new WebEndpointResponse<>(diagnostics, 200, "text/x-plantuml");
	}
	
	// ...
}

Illustrating the basic functioning

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1
2
3
4
5
6
7
8
9

<dependencies>
	...
	<dependency>
		<artifactId>refcodes-schema</artifactId>
		<groupId>org.refcodes</groupId>
		<version>4.9.9</version>
	</dependency>
	...
</dependencies>

The artifact is available from Maven Central. The source code is hosted at Bitbucket, and the API documentation is available at refcodes-schema.

Your data structure in question should implement the Schemable interface and its toSchema() method. The Schema class of the refcodes-schema artifact already provides a builder() method for easy and fluent construction of the schema in question.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class Data implements Schemable<Properties> {

	private Schemable childData1;
	private Schemable childData2;
	
	// ...
	
	public Schema toSchema() {
		var childSchema1 = childData1.toSchema();
		var childSchema2 = childData2.toSchema();
		Schema schema = Schema.builder().withAlias( "data_structure" ).withInstance( this ).withDescription( "My data structure's description" ).withChildren( childSchema1, childSchema2 ).build();
		return schema.withProperty( "CUSTOM_PROPERTY", "abc" ).withProperty( "ANOTHER_CUSTOM_PROPERTY", "xyz" );
	}
	
	// ...
}

Generating a report from the above Schema instance is as simple as calling the visit() method of the Schema instance with the appropriate visitor (as seen above in the WebEndpoint example):

1
2
3

// ...
String diagnostics = schema.visit(new PlantUmlVisitor());
// ...

See the blog post refcodes-schema: Canonical runtime diagnostics and visitor-based reports of a detailed explanation of the Schema class and the Schemable interface.

Fully provisioned runtime diagnostics

In the previous example, the Schemable interface was implemented with a generic type parameter such as Properties. This type parameter represents a container for custom, potentially implementation-specific configuration values used while generating a Schema.

The Schemable interface provides a default toSchema(OPTS options) method which accepts such an options object. This allows schema generation to be tailored at runtime using additional parameters that are not known at design time.

For ready-to-use runtime diagnostics, the refcodes-runtime artifact provides the Diagnosable interface provisioned with the DiagnosticOptions type as a drop-in replacement for the Schemable interface.

The refcodes-runtime artifact builds upon this concept by introducing the Diagnosable interface. The Diagnosable interface extends Schemable by concretizing the generic type parameter OPTS with the DiagnosticOptions class.

The DiagnosticOptions type represents optional controls supplied when generating a diagnostic schema. This makes it possible to influence the amount or kind of diagnostic information included without coupling the schema model to general runtime configuration.

To make use of this preconfigured runtime diagnostic support, add the following dependency to your pom.xml:

1
2
3
4
5
6
7
8
9

<dependencies>
	... 
	<dependency>
		<groupId>org.refcodes</groupId>
		<artifactId>refcodes-runtime</artifactId>
		<version>4.9.9</version>
	</dependency>
	...
</dependencies>

Once the runtime artifact is available, the Diagnosable interface can be used as a drop-in replacement for Schemable. It exposes a toSchema(DiagnosticOptions options) method with optional diagnostic controls:

1
2
3
4
5
6
7
8
9
10
11
12

public class Data implements Diagnosable {

	// ...

	@Override
	public Schema toSchema( DiagnosticOptions options ) {
		// Use the diagnostic options to influence the generated schema as required.
		// ...
	}

	// ...
}

A recommended approach is to use DiagnosticOptions exclusively for controls that influence diagnostic schema generation. Well-known controls can be exposed through type-safe accessors while the Diagnosable interface keeps the same toSchema(DiagnosticOptions aOptions) contract across implementations.

Conclusion

Diagnostic interfaces bridge the gap between static monitoring and true runtime understanding. By exposing canonical diagnostic schemas through standardized interfaces, systems can provide meaningful insights without invasive debugging or excessive logging. The approach described here enables developers and operators to visualize complex runtime structures as UML diagrams or to process the same data in machine-readable formats such as JSON or XML.

With a consistent schema model and visitor based report generation, runtime introspection becomes both systematic and extensible. Whether integrated into a Spring Boot endpoint or accessed via JMX, such diagnostic interfaces turn opaque runtime behavior into accessible, analyzable knowledge, helping to maintain stability, trace issues faster and understand what really happens under the hood.

See also

LinkedIn Reddit