0
# Utilities
1

2
Event logging, debugging, and other utility data structures for TensorFlow operations monitoring and analysis. These types support model debugging, performance profiling, and execution monitoring.
3

4
## Capabilities
5

6
### Event
7

8
Protocol buffer for logging events during model execution, including scalar summaries, histograms, and debugging information.
9

10
```java { .api }
11
/**
12
 * Protocol buffer for logging events during model execution
13
 */
14
class Event {
15
  /** Get wall clock time as Unix timestamp */
16
  double getWallTime();
17
  
18
  /** Get training step number */
19
  long getStep();
20
  
21
  /** Get file version string */
22
  String getFileVersion();
23
  
24
  /** Get serialized graph definition */
25
  ByteString getGraphDef();
26
  
27
  /** Get summary data */
28
  Summary getSummary();
29
  
30
  /** Get log message */
31
  LogMessage getLogMessage();
32
  
33
  /** Get session log */
34
  SessionLog getSessionLog();
35
  
36
  /** Get tagged run metadata */
37
  TaggedRunMetadata getTaggedRunMetadata();
38
  
39
  /** Get metadata for debugging */
40
  ByteString getMetaGraphDef();
41
  
42
  /** Get which event type is set */
43
  WhatCase getWhatCase();
44
  
45
  /** Create a new builder for constructing Event */
46
  static Builder newBuilder();
47
  
48
  /** Builder for constructing Event instances */
49
  static class Builder {
50
    Builder setWallTime(double wallTime);
51
    Builder setStep(long step);
52
    Builder setFileVersion(String version);
53
    Builder setGraphDef(ByteString graphDef);
54
    Builder setSummary(Summary summary);
55
    Builder setLogMessage(LogMessage logMessage);
56
    Builder setSessionLog(SessionLog sessionLog);
57
    Builder setTaggedRunMetadata(TaggedRunMetadata metadata);
58
    Builder setMetaGraphDef(ByteString metaGraphDef);
59
    Event build();
60
  }
61
  
62
  /** Enum indicating which event type is set */
63
  enum WhatCase {
64
    FILE_VERSION,
65
    GRAPH_DEF,
66
    SUMMARY,
67
    LOG_MESSAGE,
68
    SESSION_LOG,
69
    TAGGED_RUN_METADATA,
70
    META_GRAPH_DEF,
71
    WHAT_NOT_SET
72
  }
73
}
74
```
75

76
**Usage Examples:**
77

78
```java
79
import org.tensorflow.util.*;
80
import org.tensorflow.framework.*;
81

82
// Create a scalar summary event
83
Event scalarEvent = Event.newBuilder()
84
    .setWallTime(System.currentTimeMillis() / 1000.0)
85
    .setStep(1000)
86
    .setSummary(Summary.newBuilder()
87
        .addValue(Summary.Value.newBuilder()
88
            .setTag("loss")
89
            .setSimpleValue(0.25f)
90
            .build())
91
        .addValue(Summary.Value.newBuilder()
92
            .setTag("accuracy")  
93
            .setSimpleValue(0.95f)
94
            .build())
95
        .build())
96
    .build();
97

98
// Create a histogram summary event
99
Event histogramEvent = Event.newBuilder()
100
    .setWallTime(System.currentTimeMillis() / 1000.0)
101
    .setStep(1000)
102
    .setSummary(Summary.newBuilder()
103
        .addValue(Summary.Value.newBuilder()
104
            .setTag("weights/layer1")
105
            .setHisto(HistogramProto.newBuilder()
106
                .setMin(-1.5)
107
                .setMax(1.5)
108
                .setNum(1000)
109
                .setSum(0.0)
110
                .setSumSquares(250.0)
111
                .addBucketLimit(-1.0)
112
                .addBucketLimit(0.0)
113
                .addBucketLimit(1.0)
114
                .addBucket(100)
115
                .addBucket(800)
116
                .addBucket(100)
117
                .build())
118
            .build())
119
        .build())
120
    .build();
121

122
// Create a graph definition event
123
Event graphEvent = Event.newBuilder()
124
    .setWallTime(System.currentTimeMillis() / 1000.0)
125
    .setStep(0)
126
    .setGraphDef(myGraphDef.toByteString())
127
    .build();
128
```
129

130
### Summary
131

132
Contains summary data for visualization and monitoring.
133

134
```java { .api }
135
/**
136
 * Summary data for TensorBoard visualization
137
 */
138
class Summary {
139
  /** Get list of summary values */
140
  List<Value> getValueList();
141
  
142
  /** Create a new builder for constructing Summary */
143
  static Builder newBuilder();
144
  
145
  /** Builder for constructing Summary instances */
146
  static class Builder {
147
    Builder addValue(Value value);
148
    Builder addAllValue(Iterable<Value> values);
149
    Summary build();
150
  }
151
  
152
  /** Individual summary value */
153
  static class Value {
154
    /** Get value tag/name */
155
    String getTag();
156
    
157
    /** Get simple scalar value */
158
    float getSimpleValue();
159
    
160
    /** Get obsolete old-style scalar value */
161
    @Deprecated
162
    ByteString getObsoleteOldStyleHistogram();
163
    
164
    /** Get image summary */
165
    Image getImage();
166
    
167
    /** Get histogram summary */
168
    HistogramProto getHisto();
169
    
170
    /** Get audio summary */
171
    Audio getAudio();
172
    
173
    /** Get tensor summary */
174
    TensorProto getTensor();
175
    
176
    /** Get which value type is set */
177
    ValueCase getValueCase();
178
    
179
    /** Create a new builder */
180
    static Builder newBuilder();
181
    
182
    /** Builder for Value instances */
183
    static class Builder {
184
      Builder setTag(String tag);
185
      Builder setSimpleValue(float value);
186
      Builder setImage(Image image);
187
      Builder setHisto(HistogramProto histo);
188
      Builder setAudio(Audio audio);
189
      Builder setTensor(TensorProto tensor);
190
      Value build();
191
    }
192
    
193
    enum ValueCase {
194
      SIMPLE_VALUE,
195
      OBSOLETE_OLD_STYLE_HISTOGRAM,
196
      IMAGE,
197
      HISTO,
198
      AUDIO,
199
      TENSOR,
200
      VALUE_NOT_SET
201
    }
202
  }
203
}
204
```
205

206
### HistogramProto
207

208
Histogram data for distribution visualization.
209

210
```java { .api }
211
/**
212
 * Histogram data for distribution visualization
213
 */
214
class HistogramProto {
215
  /** Get minimum value */
216
  double getMin();
217
  
218
  /** Get maximum value */
219
  double getMax();
220
  
221
  /** Get number of values */
222
  long getNum();
223
  
224
  /** Get sum of all values */
225
  double getSum();
226
  
227
  /** Get sum of squares of all values */
228
  double getSumSquares();
229
  
230
  /** Get bucket limits (edges) */
231
  List<Double> getBucketLimitList();
232
  
233
  /** Get bucket counts */
234
  List<Long> getBucketList();
235
  
236
  /** Create a new builder */
237
  static Builder newBuilder();
238
  
239
  /** Builder for constructing HistogramProto instances */
240
  static class Builder {
241
    Builder setMin(double min);
242
    Builder setMax(double max);
243
    Builder setNum(long num);
244
    Builder setSum(double sum);
245
    Builder setSumSquares(double sumSquares);
246
    Builder addBucketLimit(double limit);
247
    Builder addBucket(long count);
248
    HistogramProto build();
249
  }
250
}
251
```
252

253
### Summary Image and Audio
254

255
Media summaries for visualization.
256

257
```java { .api }
258
/**
259
 * Image summary for visualization
260
 */
261
static class Image {
262
  /** Get image height */
263
  int getHeight();
264
  
265
  /** Get image width */
266
  int getWidth();
267
  
268
  /** Get color space (1=grayscale, 2=grayscale+alpha, 3=RGB, 4=RGBA) */
269
  int getColorspace();
270
  
271
  /** Get encoded image data (PNG/JPEG) */
272
  ByteString getEncodedImageString();
273
  
274
  /** Create a new builder */
275
  static Builder newBuilder();
276
  
277
  static class Builder {
278
    Builder setHeight(int height);
279
    Builder setWidth(int width);
280
    Builder setColorspace(int colorspace);
281
    Builder setEncodedImageString(ByteString data);
282
    Image build();
283
  }
284
}
285

286
/**
287
 * Audio summary for visualization
288
 */
289
static class Audio {
290
  /** Get sample rate in Hz */
291
  float getSampleRate();
292
  
293
  /** Get number of channels */
294
  long getNumChannels();
295
  
296
  /** Get length in frames */
297
  long getLengthFrames();
298
  
299
  /** Get encoded audio data (WAV) */
300
  ByteString getEncodedAudioString();
301
  
302
  /** Get content type */
303
  String getContentType();
304
  
305
  /** Create a new builder */
306
  static Builder newBuilder();
307
  
308
  static class Builder {
309
    Builder setSampleRate(float rate);
310
    Builder setNumChannels(long channels);
311
    Builder setLengthFrames(long frames);
312
    Builder setEncodedAudioString(ByteString data);
313
    Builder setContentType(String type);
314
    Audio build();
315
  }
316
}
317
```
318

319
### LogMessage
320

321
Log messages for debugging and monitoring.
322

323
```java { .api }
324
/**
325
 * Log message for debugging and monitoring
326
 */
327
class LogMessage {
328
  /** Get log level */
329
  Level getLevel();
330
  
331
  /** Get log message text */
332
  String getMessage();
333
  
334
  /** Create a new builder */
335
  static Builder newBuilder();
336
  
337
  static class Builder {
338
    Builder setLevel(Level level);
339
    Builder setMessage(String message);
340
    LogMessage build();
341
  }
342
  
343
  /** Log levels */
344
  enum Level {
345
    UNKNOWN,
346
    DEBUG,
347
    INFO, 
348
    WARN,
349
    ERROR,
350
    FATAL
351
  }
352
}
353
```
354

355
### SessionLog
356

357
Session lifecycle logging.
358

359
```java { .api }
360
/**
361
 * Session lifecycle event logging
362
 */
363
class SessionLog {
364
  /** Get session status */
365
  SessionStatus getStatus();
366
  
367
  /** Get checkpoint path if applicable */
368
  String getCheckpointPath();
369
  
370
  /** Get error message if failed */
371
  String getMsg();
372
  
373
  /** Create a new builder */
374
  static Builder newBuilder();
375
  
376
  static class Builder {
377
    Builder setStatus(SessionStatus status);
378
    Builder setCheckpointPath(String path);
379
    Builder setMsg(String message);
380
    SessionLog build();
381
  }
382
  
383
  /** Session status values */
384
  enum SessionStatus {
385
    STATUS_UNSPECIFIED,
386
    START,
387
    STOP,
388
    CHECKPOINT
389
  }
390
}
391
```
392

393
### TaggedRunMetadata
394

395
Metadata from step execution with profiling information.
396

397
```java { .api }
398
/**
399
 * Tagged run metadata with profiling information  
400
 */
401
class TaggedRunMetadata {
402
  /** Get metadata tag */
403
  String getTag();
404
  
405
  /** Get run metadata */
406
  ByteString getRunMetadata();
407
  
408
  /** Create a new builder */
409
  static Builder newBuilder();
410
  
411
  static class Builder {
412
    Builder setTag(String tag);
413
    Builder setRunMetadata(ByteString metadata);
414
    TaggedRunMetadata build();
415
  }
416
}
417
```
418

419
### Saved Tensor Slice
420

421
Utilities for saved model tensor slicing.
422

423
```java { .api }
424
/**
425
 * Metadata for saved tensor slices
426
 */
427
class SavedTensorSliceMeta {
428
  /** Get tensor information */
429
  List<SavedTensorSliceMeta.TensorSliceMetaData> getTensorList();
430
  
431
  /** Get versions information */
432
  VersionDef getVersions();
433
  
434
  /** Metadata for individual tensor slices */
435
  static class TensorSliceMetaData {
436
    /** Get tensor name */
437
    String getName();
438
    
439
    /** Get tensor shape */
440
    TensorShapeProto getShape();
441
    
442
    /** Get tensor type */
443
    DataType getType();
444
    
445
    /** Get slice specifications */
446
    List<TensorSliceProto> getSliceList();
447
  }
448
}
449

450
/**
451
 * Specification for tensor slice
452
 */
453
class TensorSliceProto {
454
  /** Get extent specifications */
455
  List<Extent> getExtentList();
456
  
457
  /** Extent along one dimension */
458
  static class Extent {
459
    /** Check if extent has start position */
460
    boolean hasStart();
461
    
462
    /** Get start position */
463
    long getStart();
464
    
465
    /** Check if extent has length */
466
    boolean hasLength();
467
    
468
    /** Get length (or -1 for rest of dimension) */
469
    long getLength();
470
  }
471
}
472
```
473

474
**Usage Examples:**
475

476
```java
477
import org.tensorflow.util.*;
478

479
// Create training metrics summary
480
Summary trainingMetrics = Summary.newBuilder()
481
    .addValue(Summary.Value.newBuilder()
482
        .setTag("train/loss")
483
        .setSimpleValue(0.123f)
484
        .build())
485
    .addValue(Summary.Value.newBuilder()
486
        .setTag("train/accuracy")
487
        .setSimpleValue(0.945f)
488
        .build())
489
    .addValue(Summary.Value.newBuilder()
490
        .setTag("train/learning_rate")
491
        .setSimpleValue(0.001f)
492
        .build())
493
    .build();
494

495
// Create image summary (e.g., for sample predictions)
496
Summary.Image imageSummary = Summary.Image.newBuilder()
497
    .setHeight(224)
498
    .setWidth(224)
499
    .setColorspace(3)  // RGB
500
    .setEncodedImageString(ByteString.copyFrom(pngImageBytes))
501
    .build();
502

503
Summary imageEvent = Summary.newBuilder()
504
    .addValue(Summary.Value.newBuilder()
505
        .setTag("predictions/sample_image")
506
        .setImage(imageSummary)
507
        .build())
508
    .build();
509

510
// Create session lifecycle log
511
SessionLog startLog = SessionLog.newBuilder()
512
    .setStatus(SessionLog.SessionStatus.START)
513
    .setMsg("Training session started")
514
    .build();
515

516
Event sessionEvent = Event.newBuilder()
517
    .setWallTime(System.currentTimeMillis() / 1000.0)
518
    .setStep(0)
519
    .setSessionLog(startLog)
520
    .build();
521
```