aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/proto
diff options
context:
space:
mode:
Diffstat (limited to 'src/proto')
-rw-r--r--src/proto/grpc/channelz/channelz.proto143
1 files changed, 102 insertions, 41 deletions
diff --git a/src/proto/grpc/channelz/channelz.proto b/src/proto/grpc/channelz/channelz.proto
index 14db66a654..d930dfcfb4 100644
--- a/src/proto/grpc/channelz/channelz.proto
+++ b/src/proto/grpc/channelz/channelz.proto
@@ -1,4 +1,4 @@
-// Copyright 2018 gRPC authors.
+// Copyright 2018 The gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -12,20 +12,30 @@
// See the License for the specific language governing permissions and
// limitations under the License.
+// This file defines an interface for exporting monitoring information
+// out of gRPC servers. See the full design at
+// https://github.com/grpc/proposal/blob/master/A14-channelz.md
+//
+// The canonical version of this proto can be found at
+// https://github.com/grpc/grpc-proto/blob/master/grpc/channelz/v1/channelz.proto
+
syntax = "proto3";
-package grpc.channelz;
+package grpc.channelz.v1;
import "google/protobuf/any.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
-// See go/grpc-channelz.
+option go_package = "google.golang.org/grpc/channelz/grpc_channelz_v1";
+option java_multiple_files = true;
+option java_package = "io.grpc.channelz.v1";
+option java_outer_classname = "ChannelzProto";
// Channel is a logical grouping of channels, subchannels, and sockets.
message Channel {
- // The identifier for this channel.
+ // The identifier for this channel. This should bet set.
ChannelRef ref = 1;
// Data specific to this channel.
ChannelData data = 2;
@@ -43,7 +53,7 @@ message Channel {
repeated SubchannelRef subchannel_ref = 4;
// There are no ordering guarantees on the order of sockets.
- repeated SocketRef socket = 5;
+ repeated SocketRef socket_ref = 5;
}
// Subchannel is a logical grouping of channels, subchannels, and sockets.
@@ -67,7 +77,7 @@ message Subchannel {
repeated SubchannelRef subchannel_ref = 4;
// There are no ordering guarantees on the order of sockets.
- repeated SocketRef socket = 5;
+ repeated SocketRef socket_ref = 5;
}
// These come from the specified states in this document:
@@ -84,20 +94,23 @@ message ChannelConnectivityState {
State state = 1;
}
+// Channel data is data related to a specific Channel or Subchannel.
message ChannelData {
-
+ // The connectivity state of the channel or subchannel. Implementations
+ // should always set this.
ChannelConnectivityState state = 1;
// The target this channel originally tried to connect to. May be absent
string target = 2;
+ // A trace of recent events on the channel. May be absent.
ChannelTrace trace = 3;
// The number of calls started on the channel
int64 calls_started = 4;
// The number of calls that have completed with an OK status
int64 calls_succeeded = 5;
- // The number of calls that have a completed with a non-OK status
+ // The number of calls that have completed with a non-OK status
int64 calls_failed = 6;
// The last time a call was started on the channel.
@@ -130,26 +143,29 @@ message ChannelTraceEvent {
}
}
+// ChannelTrace represents the recent events that have occurred on the channel.
message ChannelTrace {
// Number of events ever logged in this tracing object. This can differ from
// events.size() because events can be overwritten or garbage collected by
// implementations.
int64 num_events_logged = 1;
// Time that this channel was created.
- google.protobuf.Timestamp creation_time = 2;
+ google.protobuf.Timestamp creation_timestamp = 2;
// List of events that have occurred on this channel.
repeated ChannelTraceEvent events = 3;
}
+// ChannelRef is a reference to a Channel.
message ChannelRef {
// The globally unique id for this channel. Must be a positive number.
int64 channel_id = 1;
// An optional name associated with the channel.
string name = 2;
// Intentionally don't use field numbers from other refs.
- reserved 3, 4, 5, 6;
+ reserved 3, 4, 5, 6, 7, 8;
}
+// ChannelRef is a reference to a Subchannel.
message SubchannelRef {
// The globally unique id for this subchannel. Must be a positive number.
int64 subchannel_id = 7;
@@ -159,6 +175,7 @@ message SubchannelRef {
reserved 1, 2, 3, 4, 5, 6;
}
+// SocketRef is a reference to a Socket.
message SocketRef {
int64 socket_id = 3;
// An optional name associated with the socket.
@@ -167,8 +184,9 @@ message SocketRef {
reserved 1, 2, 5, 6, 7, 8;
}
+// ServerRef is a reference to a Server.
message ServerRef {
- // A globally unique identifier for this server. Must be a positive number.
+ // A globally unique identifier for this server. Must be a positive number.
int64 server_id = 5;
// An optional name associated with the server.
string name = 6;
@@ -176,16 +194,22 @@ message ServerRef {
reserved 1, 2, 3, 4, 7, 8;
}
+// Server represents a single server. There may be multiple servers in a single
+// program.
message Server {
+ // The identifier for a Server. This should be set.
ServerRef ref = 1;
+ // The associated data of the Server.
ServerData data = 2;
// The sockets that the server is listening on. There are no ordering
- // guarantees.
+ // guarantees. This may be absent.
repeated SocketRef listen_socket = 3;
}
+// ServerData is data for a specific Server.
message ServerData {
+ // A trace of recent events on the server. May be absent.
ChannelTrace trace = 1;
// The number of incoming calls started on the server
@@ -201,13 +225,17 @@ message ServerData {
// Information about an actual connection. Pronounced "sock-ay".
message Socket {
+ // The identifier for the Socket.
SocketRef ref = 1;
+ // Data specific to this Socket.
SocketData data = 2;
// The locally bound address.
Address local = 3;
// The remote bound address. May be absent.
Address remote = 4;
+ // Security details for this socket. May be absent if not available, or
+ // there is no security on the socket.
Security security = 5;
// Optional, represents the name of the remote endpoint, if different than
@@ -215,17 +243,23 @@ message Socket {
string remote_name = 6;
}
+// SocketData is data associated for a specific Socket. The fields present
+// are specific to the implementation, so there may be minor differences in
+// the semantics. (e.g. flow control windows)
message SocketData {
// The number of streams that have been started.
int64 streams_started = 1;
- // The number of streams that have ended successfully with the EoS bit set for
- // both end points
+ // The number of streams that have ended successfully:
+ // On client side, received frame with eos bit set;
+ // On server side, sent frame with eos bit set.
int64 streams_succeeded = 2;
- // The number of incoming streams that have a completed with a non-OK status
+ // The number of streams that have ended unsuccessfully:
+ // On client side, ended without receiving frame with eos bit set;
+ // On server side, ended without sending frame with eos bit set.
int64 streams_failed = 3;
-
- // The number of messages successfully sent on this socket.
+ // The number of grpc messages successfully sent on this socket.
int64 messages_sent = 4;
+ // The number of grpc messages received on this socket.
int64 messages_received = 5;
// The number of keep alives sent. This is typically implemented with HTTP/2
@@ -254,12 +288,14 @@ message SocketData {
// include stream level or TCP level flow control info.
google.protobuf.Int64Value remote_flow_control_window = 12;
+ // Socket options set on this socket. May be absent.
repeated SocketOption option = 13;
}
+// Address represents the address used to create the socket.
message Address {
message TcpIpAddress {
- // Either the IPv4 or IPv6 address in bytes. Will either be 4 bytes or 16
+ // Either the IPv4 or IPv6 address in bytes. Will be either 4 bytes or 16
// bytes in length.
bytes ip_address = 1;
// 0-64k, or -1 if not appropriate.
@@ -271,7 +307,7 @@ message Address {
}
// An address type not included above.
message OtherAddress {
- // The human readable version of the value.
+ // The human readable version of the value. This value should be set.
string name = 1;
// The actual address message.
google.protobuf.Any value = 2;
@@ -284,12 +320,17 @@ message Address {
}
}
+// Security represents details about how secure the socket is.
message Security {
message Tls {
- // The key exchange used. e.g. X25519
- string key_exchange = 1;
- // The cipher used. e.g. AES_128_GCM.
- string cipher = 2;
+ oneof cipher_suite {
+ // The cipher suite name in the RFC 4346 format:
+ // https://tools.ietf.org/html/rfc4346#appendix-C
+ string standard_name = 1;
+ // Some other way to describe the cipher suite if
+ // the RFC 4346 name is not available.
+ string other_name = 2;
+ }
// the certificate used by this endpoint.
bytes local_certificate = 3;
// the certificate used by the remote endpoint.
@@ -307,7 +348,11 @@ message Security {
}
}
+// SocketOption represents socket options for a socket. Specifically, these
+// are the options returned by getsockopt().
message SocketOption {
+ // The full name of the socket option. Typically this will be the upper case
+ // name, such as "SO_REUSEPORT".
string name = 1;
// The human readable value of this socket option. At least one of value or
// additional will be set.
@@ -323,12 +368,17 @@ message SocketOptionTimeout {
google.protobuf.Duration duration = 1;
}
+// For use with SocketOption's additional field. This is primarily used for
+// SO_LINGER.
message SocketOptionLinger {
+ // active maps to `struct linger.l_onoff`
bool active = 1;
+ // duration maps to `struct linger.l_linger`
google.protobuf.Duration duration = 2;
}
-// Tcp info for SOL_TCP, TCP_INFO
+// For use with SocketOption's additional field. Tcp info for
+// SOL_TCP and TCP_INFO.
message SocketOptionTcpInfo {
uint32 tcpi_state = 1;
@@ -366,8 +416,10 @@ message SocketOptionTcpInfo {
uint32 tcpi_reordering = 29;
}
+// Channelz is a service exposed by gRPC servers that provides detailed debug
+// information.
service Channelz {
- // Gets all root channels (e.g. channels the application has directly
+ // Gets all root channels (i.e. channels the application has directly
// created). This does not include subchannels nor non-top level channels.
rpc GetTopChannels(GetTopChannelsRequest) returns (GetTopChannelsResponse);
// Gets all servers that exist in the process.
@@ -382,6 +434,22 @@ service Channelz {
rpc GetSocket(GetSocketRequest) returns (GetSocketResponse);
}
+message GetTopChannelsRequest {
+ // start_channel_id indicates that only channels at or above this id should be
+ // included in the results.
+ int64 start_channel_id = 1;
+}
+
+message GetTopChannelsResponse {
+ // list of channels that the connection detail service knows about. Sorted in
+ // ascending channel_id order.
+ repeated Channel channel = 1;
+ // If set, indicates that the list of channels is the final list. Requesting
+ // more channels can only return more if they are created after this RPC
+ // completes.
+ bool end = 2;
+}
+
message GetServersRequest {
// start_server_id indicates that only servers at or above this id should be
// included in the results.
@@ -415,42 +483,35 @@ message GetServerSocketsResponse {
bool end = 2;
}
-message GetTopChannelsRequest {
- // start_channel_id indicates that only channels at or above this id should be
- // included in the results.
- int64 start_channel_id = 1;
-}
-
-message GetTopChannelsResponse {
- // list of channels that the connection detail service knows about. Sorted in
- // ascending channel_id order.
- repeated Channel channel = 1;
- // If set, indicates that the list of channels is the final list. Requesting
- // more channels can only return more if they are created after this RPC
- // completes.
- bool end = 2;
-}
-
message GetChannelRequest {
+ // channel_id is the identifier of the specific channel to get.
int64 channel_id = 1;
}
message GetChannelResponse {
+ // The Channel that corresponds to the requested channel_id. This field
+ // should be set.
Channel channel = 1;
}
message GetSubchannelRequest {
+ // subchannel_id is the identifier of the specific subchannel to get.
int64 subchannel_id = 1;
}
message GetSubchannelResponse {
+ // The Subchannel that corresponds to the requested subchannel_id. This
+ // field should be set.
Subchannel subchannel = 1;
}
message GetSocketRequest {
+ // socket_id is the identifier of the specific socket to get.
int64 socket_id = 1;
}
message GetSocketResponse {
+ // The Socket that corresponds to the requested socket_id. This field
+ // should be set.
Socket socket = 1;
}