diff options
Diffstat (limited to 'src/proto')
| -rw-r--r-- | src/proto/grpc/channelz/channelz.proto | 143 |
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; } |