# tf.compat.v1.profiler.ProfileOptionBuilder

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L22-L461) |

Option Builder for Profiling API.

    tf.compat.v1.profiler.ProfileOptionBuilder(
        options=None
    )

For tutorial on the options, see
<https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core/profiler/g3doc/options.md>

    # Users can use pre-built options:
    opts = (
        tf.profiler.ProfileOptionBuilder.trainable_variables_parameter())

    # Or, build your own options:
    opts = (tf.compat.v1.profiler.ProfileOptionBuilder()
        .with_max_depth(10)
        .with_min_micros(1000)
        .select(['accelerator_micros'])
        .with_stdout_output()
        .build()

    # Or customize the pre-built options:
    opts = (tf.compat.v1.profiler.ProfileOptionBuilder(
        tf.profiler.ProfileOptionBuilder.time_and_memory())
        .with_displaying_options(show_name_regexes=['.*rnn.*'])
        .build())

    # Finally, profiling with the options:
    _ = tf.compat.v1.profiler.profile(tf.compat.v1.get_default_graph(),
                            run_meta=run_meta,
                            cmd='scope',
                            options=opts)

<br />

<br />

<br />

| ## Args ||
|---|---|
| `options` | Optional initial option dict to start with. |

<br />

## Methods

### `account_displayed_op_only`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L368-L381)

    account_displayed_op_only(
        is_true
    )

Whether only account the statistics of displayed profiler nodes.

<br />

<br />

<br />

| Args ||
|---|---|
| `is_true` | If true, only account statistics of nodes eventually displayed by the outputs. Otherwise, a node's statistics are accounted by its parents as long as it's types match 'account_type_regexes', even if it is hidden from the output, say, by hide_name_regexes. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `build`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L189-L195)

    build()

Build a profiling option.

<br />

<br />

<br />

| Returns ||
|---|---|
| A dict of profiling options. ||

<br />

### `float_operation`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L110-L137)

    @staticmethod
    float_operation()

Options used to profile float operations.

Please see <https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core/profiler/g3doc/profile_model_architecture.md>
on the caveats of calculating float operations.

<br />

<br />

<br />

| Returns ||
|---|---|
| A dict of profiling options. ||

<br />

### `order_by`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L417-L431)

    order_by(
        attribute
    )

Order the displayed profiler nodes based on a attribute.

Supported attribute includes micros, bytes, occurrence, params, etc.
<https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core/profiler/g3doc/options.md>

<br />

<br />

<br />

| Args ||
|---|---|
| `attribute` | An attribute the profiler node has. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `select`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L433-L447)

    select(
        attributes
    )

Select the attributes to display.

See <https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core/profiler/g3doc/options.md>
for supported attributes.

<br />

<br />

<br />

| Args ||
|---|---|
| `attributes` | A list of attribute the profiler node has. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `time_and_memory`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L139-L187)

    @staticmethod
    time_and_memory(
        min_micros=1,
        min_bytes=1,
        min_accelerator_micros=0,
        min_cpu_micros=0,
        min_peak_bytes=0,
        min_residual_bytes=0,
        min_output_bytes=0
    )

Show operation time and memory consumptions.

<br />

<br />

<br />

| Args ||
|---|---|
| `min_micros` | Only show profiler nodes with execution time no less than this. It sums accelerator and cpu times. |
| `min_bytes` | Only show profiler nodes requested to allocate no less bytes than this. |
| `min_accelerator_micros` | Only show profiler nodes spend no less than this time on accelerator (e.g. GPU). |
| `min_cpu_micros` | Only show profiler nodes spend no less than this time on cpu. |
| `min_peak_bytes` | Only show profiler nodes using no less than this bytes at peak (high watermark). For profiler nodes consist of multiple graph nodes, it sums the graph nodes' peak_bytes. |
| `min_residual_bytes` | Only show profiler nodes have no less than this bytes not being de-allocated after Compute() ends. For profiler nodes consist of multiple graph nodes, it sums the graph nodes' residual_bytes. |
| `min_output_bytes` | Only show profiler nodes have no less than this bytes output. The output are not necessarily allocated by this profiler nodes. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A dict of profiling options. ||

<br />

### `trainable_variables_parameter`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L84-L108)

    @staticmethod
    trainable_variables_parameter()

Options used to profile trainable variable parameters.

Normally used together with 'scope' view.

<br />

<br />

<br />

| Returns ||
|---|---|
| A dict of profiling options. ||

<br />

### `with_accounted_types`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L312-L332)

    with_accounted_types(
        account_type_regexes
    )

Selectively counting statistics based on node types.

Here, 'types' means the profiler nodes' properties. Profiler by default
consider device name (e.g. /job:xx/.../device:GPU:0) and operation type
(e.g. MatMul) as profiler nodes' properties. User can also associate
customized 'types' to profiler nodes through OpLogProto proto.

For example, user can select profiler nodes placed on gpu:0 with:
`account_type_regexes=['.*gpu:0.*']`

If none of a node's properties match the specified regexes, the node is
not displayed nor accounted.

<br />

<br />

<br />

| Args ||
|---|---|
| `account_type_regexes` | A list of regexes specifying the types. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self. ||

<br />

### `with_empty_output`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L383-L386)

    with_empty_output()

Do not generate side-effect outputs.

### `with_file_output`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L393-L396)

    with_file_output(
        outfile
    )

Print the result to a file.

### `with_max_depth`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L197-L210)

    with_max_depth(
        max_depth
    )

Set the maximum depth of display.

The depth depends on profiling view. For 'scope' view, it's the
depth of name scope hierarchy (tree), for 'op' view, it's the number
of operation types (list), etc.

<br />

<br />

<br />

| Args ||
|---|---|
| `max_depth` | Maximum depth of the data structure to display. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_min_execution_time`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L241-L260)

    with_min_execution_time(
        min_micros=0, min_accelerator_micros=0, min_cpu_micros=0
    )

Only show profiler nodes consuming no less than 'min_micros'.

<br />

<br />

<br />

| Args ||
|---|---|
| `min_micros` | Only show profiler nodes with execution time no less than this. It sums accelerator and cpu times. |
| `min_accelerator_micros` | Only show profiler nodes spend no less than this time on accelerator (e.g. GPU). |
| `min_cpu_micros` | Only show profiler nodes spend no less than this time on cpu. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_min_float_operations`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L295-L310)

    with_min_float_operations(
        min_float_ops
    )

Only show profiler nodes consuming no less than 'min_float_ops'.

Please see <https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core/profiler/g3doc/profile_model_architecture.md>
on the caveats of calculating float operations.

<br />

<br />

<br />

| Args ||
|---|---|
| `min_float_ops` | Only show profiler nodes with float operations no less than this. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_min_memory`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L212-L239)

    with_min_memory(
        min_bytes=0, min_peak_bytes=0, min_residual_bytes=0, min_output_bytes=0
    )

Only show profiler nodes consuming no less than 'min_bytes'.

<br />

<br />

<br />

| Args ||
|---|---|
| `min_bytes` | Only show profiler nodes requested to allocate no less bytes than this. |
| `min_peak_bytes` | Only show profiler nodes using no less than this bytes at peak (high watermark). For profiler nodes consist of multiple graph nodes, it sums the graph nodes' peak_bytes. |
| `min_residual_bytes` | Only show profiler nodes have no less than this bytes not being de-allocated after Compute() ends. For profiler nodes consist of multiple graph nodes, it sums the graph nodes' residual_bytes. |
| `min_output_bytes` | Only show profiler nodes have no less than this bytes output. The output are not necessarily allocated by this profiler nodes. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_min_occurrence`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L277-L293)

    with_min_occurrence(
        min_occurrence
    )

Only show profiler nodes including no less than 'min_occurrence' graph nodes.

A "node" means a profiler output node, which can be a python line
(code view), an operation type (op view), or a graph node
(graph/scope view). A python line includes all graph nodes created by that
line, while an operation type includes all graph nodes of that type.

<br />

<br />

<br />

| Args ||
|---|---|
| `min_occurrence` | Only show nodes including no less than this. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_min_parameters`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L262-L275)

    with_min_parameters(
        min_params
    )

Only show profiler nodes holding no less than 'min_params' parameters.

'Parameters' normally refers the weights of in TensorFlow variables.
It reflects the 'capacity' of models.

<br />

<br />

<br />

| Args ||
|---|---|
| `min_params` | Only show profiler nodes holding number parameters no less than this. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_node_names`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L334-L366)

    with_node_names(
        start_name_regexes=None,
        show_name_regexes=None,
        hide_name_regexes=None,
        trim_name_regexes=None
    )

Regular expressions used to select profiler nodes to display.

After 'with_accounted_types' is evaluated, 'with_node_names' are
evaluated as follows:

For a profile data structure, profiler first finds the profiler
nodes matching 'start_name_regexes', and starts displaying profiler
nodes from there. Then, if a node matches 'show_name_regexes' and
doesn't match 'hide_name_regexes', it's displayed. If a node matches
'trim_name_regexes', profiler stops further searching that branch.

<br />

<br />

<br />

| Args ||
|---|---|
| `start_name_regexes` | list of node name regexes to start displaying. |
| `show_name_regexes` | list of node names regexes to display. |
| `hide_name_regexes` | list of node_names regexes that should be hidden. |
| `trim_name_regexes` | list of node name regexes from where to stop. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_pprof_output`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L403-L415)

    with_pprof_output(
        pprof_file
    )

Generate a pprof profile gzip file.

<br />

<br />

<br />

| To use the pprof file ||
|---|---|
| pprof -png --nodecount=100 --sample_index=1 ||

<br />

<br />

<br />

<br />

| Args ||
|---|---|
| `pprof_file` | filename for output, usually suffixed with .pb.gz. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self. ||

<br />

### `with_stdout_output`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L388-L391)

    with_stdout_output()

Print the result to stdout.

### `with_step`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L449-L461)

    with_step(
        step
    )

Which profile step to use for profiling.

The 'step' here refers to the step defined by `Profiler.add_step()` API.

<br />

<br />

<br />

| Args ||
|---|---|
| `step` | When multiple steps of profiles are available, select which step's profile to use. If -1, use average of all available steps. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| self ||

<br />

### `with_timeline_output`

[View source](https://github.com/tensorflow/tensorflow/blob/v2.14.0/tensorflow/python/profiler/option_builder.py#L398-L401)

    with_timeline_output(
        timeline_file
    )

Generate a timeline json file.