Introduction

RunOptions and RunMetadata are TensorFlow 1.x session-era tools for controlling a specific session.run call and collecting information about how that run executed. They are most useful when you are profiling an old graph, investigating device placement, or exporting timeline data for performance analysis.

These classes are not central to normal TensorFlow 2 development. They belong to the older graph-and-session execution model, so the main audience today is anyone maintaining legacy TensorFlow code.

What RunOptions Controls

RunOptions lets you change the behavior of a specific execution step. Common uses include enabling tracing and applying run-level timeouts.

1import tensorflow as tf
2
3x = tf.constant(3.0)
4y = tf.constant(4.0)
5z = x + y
6
7run_options = tf.RunOptions(
8    trace_level=tf.RunOptions.FULL_TRACE,
9    timeout_in_ms=5000,
10)
11
12run_metadata = tf.RunMetadata()
13
14with tf.Session() as sess:
15    result = sess.run(
16        z,
17        options=run_options,
18        run_metadata=run_metadata,
19    )
20    print(result)

In that call, options tells TensorFlow to collect full execution trace information and to fail the run if it exceeds the configured timeout. Without RunOptions, session.run simply executes normally and returns the fetch results.

What RunMetadata Captures

RunMetadata is the container TensorFlow fills with runtime details produced by that execution. One of the most useful parts is step_stats, which records information about operation timing and device activity during the run.

That metadata is what lets you answer questions such as:

• which operations took the most time
• whether work ran on CPU or GPU
• how execution was sequenced across devices

In other words, RunOptions asks for extra instrumentation and RunMetadata receives the result of that instrumentation.

Export a Trace for Timeline Analysis

A common TensorFlow 1.x profiling workflow was to run one step with full tracing and then export the metadata into a Chrome trace file.

1import tensorflow as tf
2from tensorflow.python.client import timeline
3
4x = tf.random_normal([1000, 1000])
5y = tf.random_normal([1000, 1000])
6z = tf.matmul(x, y)
7
8run_options = tf.RunOptions(trace_level=tf.RunOptions.FULL_TRACE)
9run_metadata = tf.RunMetadata()
10
11with tf.Session() as sess:
12    sess.run(z, options=run_options, run_metadata=run_metadata)
13
14    trace = timeline.Timeline(run_metadata.step_stats)
15    chrome_trace = trace.generate_chrome_trace_format()
16
17    with open("timeline.json", "w") as handle:
18        handle.write(chrome_trace)

That file can be inspected with Chrome trace tooling to understand how time was spent. This was one of the most practical uses of RunMetadata because raw profiling objects are much less useful than a timeline you can actually inspect.

Use These Tools Deliberately

Tracing adds overhead. You generally do not want full trace collection on every training step. Instead, enable it for a small number of carefully chosen runs when diagnosing slow graph execution, unexpected device placement, or performance regressions.

That is why RunOptions and RunMetadata are better thought of as profiling instruments than as everyday model-building utilities. They are most valuable when you already know something is wrong and need deeper visibility into execution.

Common Pitfalls

The biggest mistake is treating these classes like normal TensorFlow 2 APIs. They are part of the TensorFlow 1.x session model and should be understood in that historical context.

Another common issue is enabling full tracing too broadly. Profiling changes performance characteristics, so it should be turned on sparingly and for a reason.

It is also easy to collect metadata without actually inspecting it. The value comes from exporting and analyzing step_stats, not just constructing the objects.

Finally, if a codebase is already migrating to modern TensorFlow, deep investment in session-era profiling APIs may not be the best long-term use of effort. Sometimes the better move is to profile with current TensorFlow tools instead.

Summary

• 'RunOptions customizes how a specific session.run call executes.'
• 'RunMetadata stores profiling and trace information from that run.'
• The pair is mainly useful for TensorFlow 1.x performance diagnosis.
• Full tracing is powerful but should be used selectively.
• In TensorFlow 2, newer profiling workflows are usually the better default.