package tensorflow

Get desktop application:
View/edit binary Protocol Buffers messages

////////////////////////////////////////////////////////////////////////////// ProfileAnalysis service provide entry point for profiling TPU and for serving profiled data to TensorBoard through GRPC //////////////////////////////////////////////////////////////////////////////

• rpc EnumSessions (EnumProfileSessionsAndToolsRequest, EnumProfileSessionsAndToolsResponse)

  profiler_analysis.proto:76

  Enumerate existing sessions and return available profile tools.

  message EnumProfileSessionsAndToolsRequest

  profiler_analysis.proto:24

  • string repository_root = 1

  message EnumProfileSessionsAndToolsResponse

  profiler_analysis.proto:34

  • string error_message = 1

    Auxiliary error_message.

  • repeated ProfileSessionInfo sessions = 2

    If success, the returned sessions information are stored here.

• rpc GetSessionToolData (ProfileSessionDataRequest, ProfileSessionDataResponse)

  profiler_analysis.proto:79

  Retrieve specific tool's data for specific session.

  message ProfileSessionDataRequest

  profiler_analysis.proto:41

  • string repository_root = 1

    The place where we will read profile data. We will normally use MODEL_DIR/plugins/profile as the repository root.

  • string session_id = 2

  • string host_name = 5

    Which host the data is associated. if empty, data from all hosts are aggregated.

  • string tool_name = 3

    Which tool

  • map<string, string> parameters = 4

    Tool's specific parameters. e.g. TraceViewer's viewport etc

  message ProfileSessionDataResponse

  profiler_analysis.proto:55

  • string error_message = 1

    Auxiliary error_message.

  • string output_format = 2

    Output format. e.g. "json" or "proto" or "blob"

  • bytes output = 3

    TODO(jiesun): figure out whether to put bytes or oneof tool specific proto.

• rpc NewSession (NewProfileSessionRequest, NewProfileSessionResponse)

  profiler_analysis.proto:73

  Starts a profiling session, blocks until it completes. TPUProfileAnalysis service delegate this to TPUProfiler service. Populate the profiled data in repository, then return status to caller.

  message NewProfileSessionRequest

  profiler_analysis.proto:7

  • optional ProfileRequest request = 1

  • string repository_root = 2

    The place where we will dump profile data. We will normally use MODEL_DIR/plugins/profile as the repository root.

  • repeated string hosts = 3

    host or host:port, port will be ignored.

  • string session_id = 4

  message NewProfileSessionResponse

  profiler_analysis.proto:16

  • string error_message = 1

    Auxiliary error_message.

  • bool empty_trace = 2

    Whether all hosts had returned a empty trace.

The ProfilerService service retrieves performance information about the programs running on connected devices over a period of time.

• rpc GetSnapshot (GetSnapshotRequest, ProfileResponse)

  profiler_service.proto:27

  Gets a snapshot of an ongoing profiling session.

  message GetSnapshotRequest

  profiler_service.proto:110

  • string snapshot_session_id = 1

    Optional. Suffix for the snapshot directory sandboxed inside repository_root. E.g. "window_001". If empty, defaults to emit_xpace=true behavior. using the timestamp folder.

• rpc Monitor (MonitorRequest, MonitorResponse)

  profiler_service.proto:19

  Collects profiling data and returns user-friendly metrics.

  message MonitorRequest

  profiler_service.proto:124

  Next-ID: 4

  • uint64 duration_ms = 1

    Duration for which to profile between each update.

  • int32 monitoring_level = 2

    Indicates the level at which we want to monitor. Currently, two levels are supported: Level 1: An ultra lightweight mode that captures only some utilization metrics. Level 2: More verbose than level 1. Collects utilization metrics, device information, step time information, etc. Do not use this option if the TPU host is being very heavily used.

  • bool timestamp = 3

    True to display timestamp in monitoring result.

  message MonitorResponse

  profiler_service.proto:141

  Next-ID: 11

  • string data = 1

    Properly formatted string data that can be directly returned back to user.

  • optional ProfilerServiceMonitorResult monitor_result = 10

    A collection of monitoring results for each field show in data.

• rpc Profile (ProfileRequest, ProfileResponse)

  profiler_service.proto:13

  Starts a profiling session, blocks until it completes, and returns data.

• rpc StartContinuousProfiling (ProfileRequest, ContinuousProfilingResponse)

  profiler_service.proto:21

  Starts a continuous profiling session.

  message ContinuousProfilingResponse

  profiler_service.proto:117

  (message has no fields)

• rpc StopContinuousProfiling (StopContinuousProfilingRequest, StopContinuousProfilingResponse)

  profiler_service.proto:24

  Stops an ongoing continuous profiling session.

  message StopContinuousProfilingRequest

  profiler_service.proto:119

  (message has no fields)

  message StopContinuousProfilingResponse

  profiler_service.proto:121

  (message has no fields)

• rpc Terminate (TerminateRequest, TerminateResponse)

  profiler_service.proto:17

  Signal to terminate the Profile rpc for a on-going profiling session, The Profile rpc will return successfully and prematurely without timeout. This is used by programmatic mode to end the session in workers.

  message TerminateRequest

  profiler_service.proto:103

  • string session_id = 1

    Which session id to terminate.

  message TerminateResponse

  profiler_service.proto:108

  (message has no fields)

Next ID: 16

Used in: ProfileRequest, RemoteProfilerSessionManagerOptions

• uint32 version = 5

  Some default value of option are not proto3 default value. Use this version to determine if we should use default option value instead of proto3 default value.

• ProfileOptions.DeviceType device_type = 6

  Device type to profile/trace: (version >= 1) DeviceType::UNSPECIFIED: All registered device profiler will be enabled. DeviceType::CPU: only CPU will be profiled. DeviceType::GPU: only CPU/GPU will be profiled. DeviceType::TPU: only CPU/TPU will be profiled. DeviceType::PLUGGABLE_DEVICE: only CPU/pluggable devices with profilers will be profiled.

• bool include_dataset_ops = 1

  We don't collect the dataset ops by default for better trace-viewer scalability. The caller can manually set this field to include the ops.

• uint32 host_tracer_level = 2

  Levels of host tracing: (version >= 1) - Level 0 is used to disable host traces. - Level 1 enables tracing of only user instrumented (or default) TraceMe, this is the default. - Level 2 enables tracing of all level 1 TraceMe(s) and instrumented high level program execution details (expensive TF ops, XLA ops, etc). - Level 3 enables tracing of all level 2 TraceMe(s) and more verbose (low-level) program execution details (cheap TF ops, etc).

• uint32 device_tracer_level = 3

  Levels of device tracing: (version >= 1) - Level 0 is used to disable device traces. - Level 1 is used to enable device traces. - More levels might be defined for specific device for controlling the verbosity of the trace.

• uint32 python_tracer_level = 4

  Whether enable python function calls tracing. Runtime overhead ensues if enabled. Default off. (version >= 1)

• bool enable_hlo_proto = 7

  Whether serialize hlo_proto when XLA is used. (version >= 1)

• uint64 start_timestamp_ns = 8

  The local profiler starts profiling at this Unix timestamp in nanoseconds.

• uint64 duration_ms = 9

  The local profiler collects `duration_ms` milliseconds of data. If the value is 0, profiling continues until interrupted.

• string repository_path = 10

  Directory to save profile data to. No-op when empty.

• optional ProfileOptions.TraceOptions trace_options = 11

• map<string, ProfileOptions.AdvancedConfigValue> advanced_configuration = 12

  Advanced configuration for the profiler contains a map of config name to config value. It gives the flexibility to pass any configuration to the profiler. eg: advanced_configuration { key: "tpu_trace_mode" value: { int64_value: 2 } }

• bool raise_error_on_start_failure = 13

• string session_id = 14

  Identifier of the profiling session. This will be used as the subdirectory under the repository path. If not set, the current timestamp will be used.

• string override_hostname = 15

  If set, this hostname will be used to name the profile file.

AdvancedConfigValue represents the configuration value, it can be one of the following types: string, bool, int64, depending upon the config type.

Used in: ProfileOptions

• oneof value

  • string string_value = 1

  • bool bool_value = 2

  • int64 int64_value = 3

Used in: ProfileOptions

• UNSPECIFIED = 0

• CPU = 1

• GPU = 2

• TPU = 3

• PLUGGABLE_DEVICE = 4

Used in: ProfileOptions

• uint64 host_traceme_filter_mask = 1

  Filter mask for TraceMe events. If the traceme_filter_mask is set, a TraceMe event will be recorded if it passes the filter. Only lowest 32 bits of the mask are used. The higher 32 bits are reserved and won't be applied if set.

Next-ID: 10

Used as request type in: ProfilerService.Profile, ProfilerService.StartContinuousProfiling

Used as field type in: NewProfileSessionRequest

• uint64 duration_ms = 1

  In future, the caller will be able to customize when profiling starts and stops. For now, it collects `duration_ms` milliseconds worth of data.

• uint64 max_events = 2

  The maximum number of events to return. By default (value 0), return all events.

• repeated string tools = 3

  Required profiling tools name such as "input_pipeline_analyzer" etc

• map<string, ToolRequestOptions> tool_options = 8

  Specifies the requirement for each tools.

• optional ProfileOptions opts = 4

  Optional profiling options that control how a TF session will be profiled.

• string repository_root = 5

  The place where we will dump profile data. We will normally use MODEL_DIR/plugins/profile/ as the repository root.

• string session_id = 6

  The user provided profile session identifier.

• string host_name = 7

  The hostname of system where the profile should happen. We use it as identifier in part of our output filename.

• bool emit_xspace = 9

  If true, the response will contain the XSpace in the response.

  In future, the caller will indicate which TF session is being profiled, and only data relating to that program will be returned. For now, we assume all activity during the profiling period is relevant.

Next-ID: 9

Used as response type in: ProfilerService.GetSnapshot, ProfilerService.Profile

• repeated ProfileToolData tool_data = 6

  Data payload for each required tools.

• bool empty_trace = 7

  When we write profiling data directly to repository directory, we need a way to figure out whether the captured trace is empty.

• optional profiler.XSpace xspace = 8

  The XSpace proto containing the raw profiling data (e.g. pre-analysis). This field is only populated if ProfileRequest.emit_xspace is true.

Used in: EnumProfileSessionsAndToolsResponse

• string session_id = 1

• repeated string available_tools = 2

  Which tool data is available for consumption.

Used in: ProfileResponse

• string name = 1

  The file name which this data is associated (e.g. "input_pipeline.json", "cluster_xxx.memory_viewer.json").

• bytes data = 2

  The data payload (likely json) for the specific tool.

Used in: MonitorResponse

• ProfilerServiceMonitorResult.ResponseType response_type = 1

  Type of profiling responses.

• double device_idle_time_percent = 2

  Percentage of time when device is idle.

• double matrix_unit_utilization_percent = 3

  TPU matrix unit utilization percentage.

• double step_time_ms_avg = 4

  Average step time in millisecond.

• double step_time_ms_min = 5

  Minimum step time in millisecond.

• double step_time_ms_max = 6

  Maximum step time in millisecond.

• double infeed_percent_avg = 7

  Average infeed percentage.

• double infeed_percent_min = 8

  Minimum infeed percentage.

• double infeed_percent_max = 9

  Maximum infeed percentage.

Represents the different types of responses from the profiling service.

Used in: ProfilerServiceMonitorResult

• EMPTY_RESULT = 0

  No result is returned from the profiling service.

• UTIL_ONLY = 1

  Only device utilization is available.

• UTIL_IDLE = 2

  Both device utilization and device idle time are available.

• UTIL_IDLE_STEP = 3

  Device utilization, device idle time, step time, and infeed percentage are all available.

Options for remote profiler session manager. Next ID: 6

• optional ProfileOptions profiler_options = 1

  Options for each local profiler.

• repeated string service_addresses = 2

  List of servers to profile. Supported formats: host:port.

• uint64 session_creation_timestamp_ns = 3

  Unix timestamp of when the session was started.

• uint64 max_session_duration_ms = 4

  Maximum time (in milliseconds) a profiling session manager waits for all profilers to finish after issuing gRPC request. If value is 0, session continues until interrupted. Otherwise, value must be greater than profiler_options.duration_ms.

• uint64 delay_ms = 5

  Start of profiling is delayed by this much (in milliseconds).

Used in: ProfileRequest

• string output_formats = 2

  Required formats for the tool, it should be one of "json", "proto", "raw" etc. If not specified (backward compatible), use default format, i.e. most tools use json format.

• bool save_to_repo = 3

  Whether save the result directly to repository or pass it back to caller. Default to false for backward compatibilities.