1syntax = "proto3";
2
3package tensorflow;
4
5import "tensorflow/core/profiler/profiler_options.proto";
6import "tensorflow/core/profiler/profiler_service_monitor_result.proto";
7
8// The ProfilerService service retrieves performance information about
9// the programs running on connected devices over a period of time.
10service ProfilerService {
11  // Starts a profiling session, blocks until it completes, and returns data.
12  rpc Profile(ProfileRequest) returns (ProfileResponse) {}
13  // Signal to terminate the Profile rpc for a on-going profiling session,
14  // The Profile rpc will return successfully and prematurely without timeout.
15  // This is used by programmatic mode to end the session in workers.
16  rpc Terminate(TerminateRequest) returns (TerminateResponse) {}
17  // Collects profiling data and returns user-friendly metrics.
18  rpc Monitor(MonitorRequest) returns (MonitorResponse) {}
19}
20
21message ToolRequestOptions {
22  // Required formats for the tool, it should be one of "json", "proto", "raw"
23  // etc. If not specified (backward compatible), use default format, i.e. most
24  // tools use json format.
25  string output_formats = 2;
26
27  // Whether save the result directly to repository or pass it back to caller.
28  // Default to false for backward compatibilities.
29  bool save_to_repo = 3;
30}
31
32// Next-ID: 9
33message ProfileRequest {
34  // In future, the caller will be able to customize when profiling starts and
35  // stops. For now, it collects `duration_ms` milliseconds worth of data.
36  uint64 duration_ms = 1;
37
38  // The maximum number of events to return. By default (value 0), return all
39  // events.
40  uint64 max_events = 2;
41
42  // Required profiling tools name such as "input_pipeline_analyzer" etc
43  repeated string tools = 3;
44
45  // Specifies the requirement for each tools.
46  map<string, ToolRequestOptions> tool_options = 8;
47
48  // Optional profiling options that control how a TF session will be profiled.
49  ProfileOptions opts = 4;
50
51  // The place where we will dump profile data. We will normally use
52  // MODEL_DIR/plugins/profile/ as the repository root.
53  string repository_root = 5;
54
55  // The user provided profile session identifier.
56  string session_id = 6;
57
58  // The hostname of system where the profile should happen.
59  // We use it as identifier in part of our output filename.
60  string host_name = 7;
61
62  // In future, the caller will indicate which TF session is being profiled, and
63  // only data relating to that program will be returned. For now, we assume
64  // all activity during the profiling period is relevant.
65}
66
67message ProfileToolData {
68  // The file name which this data is associated (e.g. "input_pipeline.json",
69  // "cluster_xxx.memory_viewer.json").
70  string name = 1;
71
72  // The data payload (likely json) for the specific tool.
73  bytes data = 2;
74}
75
76// Next-ID: 8
77message ProfileResponse {
78  // Data payload for each required tools.
79  repeated ProfileToolData tool_data = 6;
80
81  // When we write profiling data directly to repository directory, we need a
82  // way to figure out whether the captured trace is empty.
83  bool empty_trace = 7;
84
85  reserved 1, 2, 3, 4, 5;
86}
87
88message TerminateRequest {
89  // Which session id to terminate.
90  string session_id = 1;
91}
92
93message TerminateResponse {}
94
95// Next-ID: 4
96message MonitorRequest {
97  // Duration for which to profile between each update.
98  uint64 duration_ms = 1;
99
100  // Indicates the level at which we want to monitor. Currently, two levels are
101  // supported:
102  // Level 1: An ultra lightweight mode that captures only some utilization
103  // metrics.
104  // Level 2: More verbose than level 1. Collects utilization metrics, device
105  // information, step time information, etc. Do not use this option if the TPU
106  // host is being very heavily used.
107  int32 monitoring_level = 2;
108  // True to display timestamp in monitoring result.
109  bool timestamp = 3;
110}
111
112// Next-ID: 11
113message MonitorResponse {
114  // Properly formatted string data that can be directly returned back to user.
115  string data = 1;
116
117  // A collection of monitoring results for each field show in data.
118  ProfilerServiceMonitorResult monitor_result = 10;
119
120  reserved 2, 3, 4, 5, 6, 7, 8, 9;
121}
122