1// Copyright 2019 gRPC authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package grpc.go.profiling.v1alpha;
18
19// This package defines the proto messages and RPC services exposed by gRPC for
20// profiling management. A reference client implementation to interact with
21// this service is provided as a command-line application. This service can be
22// used to toggle profiling on and off and retrieve stats from a gRPC
23// application.
24option go_package = "google.golang.org/grpc/profiling/proto";
25
26// EnableRequest defines the fields in a /Profiling/Enable method request to
27// toggle profiling on and off within a gRPC program.
28message EnableRequest {
29 // Setting this to true will enable profiling. Setting this to false will
30 // disable profiling.
31 bool enabled = 1;
32}
33
34// EnableResponse defines the fields in a /Profiling/Enable method response.
35message EnableResponse {
36}
37
38// GetStreamStatsRequest defines the fields in a /Profiling/GetStreamStats
39// method request to retrieve stream-level stats in a gRPC client/server.
40message GetStreamStatsRequest {
41}
42
43// GetStreamStatsResponse defines the fields in a /Profiling/GetStreamStats
44// method response.
45message GetStreamStatsResponse {
46 repeated Stat stream_stats = 1;
47}
48
49// A Timer measures the start and end of execution of a component within
50// gRPC that's being profiled. It includes a tag and some additional metadata
51// to identify itself.
52message Timer {
53 // tags is a comma-separated list of strings used to tag a timer.
54 string tags = 1;
55
56 // begin_sec and begin_nsec are the start epoch second and nanosecond,
57 // respectively, of the component profiled by this timer in UTC. begin_nsec
58 // must be a non-negative integer.
59 int64 begin_sec = 2;
60 int32 begin_nsec = 3;
61
62 // end_sec and end_nsec are the end epoch second and nanosecond,
63 // respectively, of the component profiled by this timer in UTC. end_nsec
64 // must be a non-negative integer.
65 int64 end_sec = 4;
66 int32 end_nsec = 5;
67
68 // go_id is the goroutine ID of the component being profiled.
69 int64 go_id = 6;
70}
71
72// A Stat is a collection of Timers along with some additional
73// metadata to tag and identify itself.
74message Stat {
75 // tags is a comma-separated list of strings used to categorize a stat.
76 string tags = 1;
77
78 // timers is an array of Timers, each representing a different
79 // (but possibly overlapping) component within this stat.
80 repeated Timer timers = 2;
81
82 // metadata is an array of bytes used to uniquely identify a stat with an
83 // undefined encoding format. For example, the Stats returned by the
84 // /Profiling/GetStreamStats service use the metadata field to encode the
85 // connection ID and the stream ID of each query.
86 bytes metadata = 3;
87}
88
89// The Profiling service exposes functions to remotely manage the gRPC
90// profiling behaviour in a program.
91service Profiling {
92 // Enable allows users to toggle profiling on and off remotely.
93 rpc Enable (EnableRequest) returns (EnableResponse);
94
95 // GetStreamStats is used to retrieve an array of stream-level stats from a
96 // gRPC client/server.
97 rpc GetStreamStats (GetStreamStatsRequest) returns (GetStreamStatsResponse);
98}
View as plain text