package grpc.channelz.v1

Get desktop application:
View/edit binary Protocol Buffers messages

Channelz is a service exposed by gRPC servers that provides detailed debug information.

• rpc GetChannel (GetChannelRequest, GetChannelResponse)

  channelz.proto:445

  Returns a single Channel, or else a NOT_FOUND code.

  message GetChannelRequest

  channelz.proto:539

  • int64 channel_id = 1

    channel_id is the identifier of the specific channel to get.

  message GetChannelResponse

  channelz.proto:544

  • optional Channel channel = 1

    The Channel that corresponds to the requested channel_id. This field should be set.

• rpc GetServer (GetServerRequest, GetServerResponse)

  channelz.proto:441

  Returns a single Server, or else a NOT_FOUND code.

  message GetServerRequest

  channelz.proto:502

  • int64 server_id = 1

    server_id is the identifier of the specific server to get.

  message GetServerResponse

  channelz.proto:507

  • optional Server server = 1

    The Server that corresponds to the requested server_id. This field should be set.

• rpc GetServerSockets (GetServerSocketsRequest, GetServerSocketsResponse)

  channelz.proto:443

  Gets all server sockets that exist in the process.

  message GetServerSocketsRequest

  channelz.proto:513

  • int64 server_id = 1

  • int64 start_socket_id = 2

    start_socket_id indicates that only sockets at or above this id should be included in the results. To request the first page, this must be set to 0. To request subsequent pages, the client generates this value by adding 1 to the highest seen result ID.

  • int64 max_results = 3

    If non-zero, the server will return a page of results containing at most this many items. If zero, the server will choose a reasonable page size. Must never be negative.

  message GetServerSocketsResponse

  channelz.proto:528

  • repeated SocketRef socket_ref = 1

    list of socket refs that the connection detail service knows about. Sorted in ascending socket_id order. Must contain at least 1 result, otherwise 'end' must be true.

  • bool end = 2

    If set, indicates that the list of sockets is the final list. Requesting more sockets will only return more if they are created after this RPC completes.

• rpc GetServers (GetServersRequest, GetServersResponse)

  channelz.proto:439

  Gets all servers that exist in the process.

  message GetServersRequest

  channelz.proto:477

  • int64 start_server_id = 1

    start_server_id indicates that only servers at or above this id should be included in the results. To request the first page, this must be set to 0. To request subsequent pages, the client generates this value by adding 1 to the highest seen result ID.

  • int64 max_results = 2

    If non-zero, the server will return a page of results containing at most this many items. If zero, the server will choose a reasonable page size. Must never be negative.

  message GetServersResponse

  channelz.proto:491

  • repeated Server server = 1

    list of servers that the connection detail service knows about. Sorted in ascending server_id order. Must contain at least 1 result, otherwise 'end' must be true.

  • bool end = 2

    If set, indicates that the list of servers is the final list. Requesting more servers will only return more if they are created after this RPC completes.

• rpc GetSocket (GetSocketRequest, GetSocketResponse)

  channelz.proto:449

  Returns a single Socket or else a NOT_FOUND code.

  message GetSocketRequest

  channelz.proto:561

  • int64 socket_id = 1

    socket_id is the identifier of the specific socket to get.

  • bool summary = 2

    If true, the response will contain only high level information that is inexpensive to obtain. Fields that may be omitted are documented.

  message GetSocketResponse

  channelz.proto:571

  • optional Socket socket = 1

    The Socket that corresponds to the requested socket_id. This field should be set.

• rpc GetSubchannel (GetSubchannelRequest, GetSubchannelResponse)

  channelz.proto:447

  Returns a single Subchannel, or else a NOT_FOUND code.

  message GetSubchannelRequest

  channelz.proto:550

  • int64 subchannel_id = 1

    subchannel_id is the identifier of the specific subchannel to get.

  message GetSubchannelResponse

  channelz.proto:555

  • optional Subchannel subchannel = 1

    The Subchannel that corresponds to the requested subchannel_id. This field should be set.

• rpc GetTopChannels (GetTopChannelsRequest, GetTopChannelsResponse)

  channelz.proto:437

  Gets all root channels (i.e. channels the application has directly created). This does not include subchannels nor non-top level channels.

  message GetTopChannelsRequest

  channelz.proto:452

  • int64 start_channel_id = 1

    start_channel_id indicates that only channels at or above this id should be included in the results. To request the first page, this should be set to 0. To request subsequent pages, the client generates this value by adding 1 to the highest seen result ID.

  • int64 max_results = 2

    If non-zero, the server will return a page of results containing at most this many items. If zero, the server will choose a reasonable page size. Must never be negative.

  message GetTopChannelsResponse

  channelz.proto:466

  • repeated Channel channel = 1

    list of channels that the connection detail service knows about. Sorted in ascending channel_id order. Must contain at least 1 result, otherwise 'end' must be true.

  • bool end = 2

    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.

Address represents the address used to create the socket.

Used in: Socket

• oneof address

  • Address.TcpIpAddress tcpip_address = 1

  • Address.UdsAddress uds_address = 2

  • Address.OtherAddress other_address = 3

An address type not included above.

Used in: Address

• string name = 1

  The human readable version of the value. This value should be set.

• optional google.protobuf.Any value = 2

  The actual address message.

Used in: Address

• bytes ip_address = 1

  Either the IPv4 or IPv6 address in bytes. Will be either 4 bytes or 16 bytes in length.

• int32 port = 2

  0-64k, or -1 if not appropriate.

A Unix Domain Socket address.

Used in: Address

• string filename = 1

Channel is a logical grouping of channels, subchannels, and sockets.

Used in: GetChannelResponse, GetTopChannelsResponse

• optional ChannelRef ref = 1

  The identifier for this channel. This should be set.

• optional ChannelData data = 2

  Data specific to this channel.

  At most one of 'channel_ref+subchannel_ref' and 'socket' is set.

• repeated ChannelRef channel_ref = 3

  There are no ordering guarantees on the order of channel refs. There may not be cycles in the ref graph. A channel ref may be present in more than one channel or subchannel.

• repeated SubchannelRef subchannel_ref = 4

  At most one of 'channel_ref+subchannel_ref' and 'socket' is set. There are no ordering guarantees on the order of subchannel refs. There may not be cycles in the ref graph. A sub channel ref may be present in more than one channel or subchannel.

• repeated SocketRef socket_ref = 5

  There are no ordering guarantees on the order of sockets.

These come from the specified states in this document: https://github.com/grpc/grpc/blob/master/doc/connectivity-semantics-and-api.md

Used in: ChannelData

• ChannelConnectivityState.State state = 1

Used in: ChannelConnectivityState

• UNKNOWN = 0

• IDLE = 1

• CONNECTING = 2

• READY = 3

• TRANSIENT_FAILURE = 4

• SHUTDOWN = 5

Channel data is data related to a specific Channel or Subchannel.

Used in: Channel, Subchannel

• optional ChannelConnectivityState state = 1

  The connectivity state of the channel or subchannel. Implementations should always set this.

• string target = 2

  The target this channel originally tried to connect to. May be absent

• optional ChannelTrace trace = 3

  A trace of recent events on the channel. May be absent.

• int64 calls_started = 4

  The number of calls started on the channel

• int64 calls_succeeded = 5

  The number of calls that have completed with an OK status

• int64 calls_failed = 6

  The number of calls that have completed with a non-OK status

• optional google.protobuf.Timestamp last_call_started_timestamp = 7

  The last time a call was started on the channel.

• uint32 max_connections_per_subchannel = 8

  Populated for subchannels only.

ChannelRef is a reference to a Channel.

Used in: Channel, ChannelTraceEvent, Subchannel

• int64 channel_id = 1

  The globally unique id for this channel. Must be a positive number.

• string name = 2

  An optional name associated with the channel.

ChannelTrace represents the recent events that have occurred on the channel.

Used in: ChannelData, ServerData

• int64 num_events_logged = 1

  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.

• optional google.protobuf.Timestamp creation_timestamp = 2

  Time that this channel was created.

• repeated ChannelTraceEvent events = 3

  List of events that have occurred on this channel.

A trace event is an interesting thing that happened to a channel or subchannel, such as creation, address resolution, subchannel creation, etc.

Used in: ChannelTrace

• string description = 1

  High level description of the event.

• ChannelTraceEvent.Severity severity = 2

  the severity of the trace event

• optional google.protobuf.Timestamp timestamp = 3

  When this event occurred.

• oneof child_ref

  ref of referenced channel or subchannel. Optional, only present if this event refers to a child object. For example, this field would be filled if this trace event was for a subchannel being created.

  • ChannelRef channel_ref = 4

  • SubchannelRef subchannel_ref = 5

The supported severity levels of trace events.

Used in: ChannelTraceEvent

• CT_UNKNOWN = 0

• CT_INFO = 1

• CT_WARNING = 2

• CT_ERROR = 3

Security represents details about how secure the socket is.

Used in: Socket

• oneof model

  • Security.Tls tls = 1

  • Security.OtherSecurity other = 2

Used in: Security

• string name = 1

  The human readable version of the value.

• optional google.protobuf.Any value = 2

  The actual security details message.

Used in: Security

• oneof cipher_suite

  • string standard_name = 1

    The cipher suite name in the RFC 4346 format: https://tools.ietf.org/html/rfc4346#appendix-C

  • string other_name = 2

    Some other way to describe the cipher suite if the RFC 4346 name is not available.

• bytes local_certificate = 3

  the certificate used by this endpoint.

• bytes remote_certificate = 4

  the certificate used by the remote endpoint.

Server represents a single server. There may be multiple servers in a single program.

Used in: GetServerResponse, GetServersResponse

• optional ServerRef ref = 1

  The identifier for a Server. This should be set.

• optional ServerData data = 2

  The associated data of the Server.

• repeated SocketRef listen_socket = 3

  The sockets that the server is listening on. There are no ordering guarantees. This may be absent.

ServerData is data for a specific Server.

Used in: Server

• optional ChannelTrace trace = 1

  A trace of recent events on the server. May be absent.

• int64 calls_started = 2

  The number of incoming calls started on the server

• int64 calls_succeeded = 3

  The number of incoming calls that have completed with an OK status

• int64 calls_failed = 4

  The number of incoming calls that have a completed with a non-OK status

• optional google.protobuf.Timestamp last_call_started_timestamp = 5

  The last time a call was started on the server.

ServerRef is a reference to a Server.

Used in: Server

• int64 server_id = 5

  A globally unique identifier for this server. Must be a positive number.

• string name = 6

  An optional name associated with the server.

Information about an actual connection. Pronounced "sock-ay".

Used in: GetSocketResponse

• optional SocketRef ref = 1

  The identifier for the Socket.

• optional SocketData data = 2

  Data specific to this Socket.

• optional Address local = 3

  The locally bound address.

• optional Address remote = 4

  The remote bound address. May be absent.

• optional Security security = 5

  Security details for this socket. May be absent if not available, or there is no security on the socket.

• string remote_name = 6

  Optional, represents the name of the remote endpoint, if different than the original target name.

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)

Used in: Socket

• int64 streams_started = 1

  The number of streams that have been started.

• int64 streams_succeeded = 2

  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_failed = 3

  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 messages_sent = 4

  The number of grpc messages successfully sent on this socket.

• int64 messages_received = 5

  The number of grpc messages received on this socket.

• int64 keep_alives_sent = 6

  The number of keep alives sent. This is typically implemented with HTTP/2 ping messages.

• optional google.protobuf.Timestamp last_local_stream_created_timestamp = 7

  The last time a stream was created by this endpoint. Usually unset for servers.

• optional google.protobuf.Timestamp last_remote_stream_created_timestamp = 8

  The last time a stream was created by the remote endpoint. Usually unset for clients.

• optional google.protobuf.Timestamp last_message_sent_timestamp = 9

  The last time a message was sent by this endpoint.

• optional google.protobuf.Timestamp last_message_received_timestamp = 10

  The last time a message was received by this endpoint.

• optional google.protobuf.Int64Value local_flow_control_window = 11

  The amount of window, granted to the local endpoint by the remote endpoint. This may be slightly out of date due to network latency. This does NOT include stream level or TCP level flow control info.

• optional google.protobuf.Int64Value remote_flow_control_window = 12

  The amount of window, granted to the remote endpoint by the local endpoint. This may be slightly out of date due to network latency. This does NOT include stream level or TCP level flow control info.

• repeated SocketOption option = 13

  Socket options set on this socket. May be absent if 'summary' is set on GetSocketRequest.

• optional google.protobuf.UInt32Value received_goaway_error = 14

  Populated if a GOAWAY has been received. The value will be the HTTP/2 error code from the GOAWAY.

• uint32 peer_max_concurrent_streams = 15

  The value of MAX_CONCURRENT_STREAMS set by the peer. Populated on client side only.

SocketOption represents socket options for a socket. Specifically, these are the options returned by getsockopt().

Used in: SocketData

• string name = 1

  The full name of the socket option. Typically this will be the upper case name, such as "SO_REUSEPORT".

• string value = 2

  The human readable value of this socket option. At least one of value or additional will be set.

• optional google.protobuf.Any additional = 3

  Additional data associated with the socket option. At least one of value or additional will be set.

For use with SocketOption's additional field. This is primarily used for SO_LINGER.

• bool active = 1

  active maps to `struct linger.l_onoff`

• optional google.protobuf.Duration duration = 2

  duration maps to `struct linger.l_linger`

For use with SocketOption's additional field. Tcp info for SOL_TCP and TCP_INFO.

• uint32 tcpi_state = 1

• uint32 tcpi_ca_state = 2

• uint32 tcpi_retransmits = 3

• uint32 tcpi_probes = 4

• uint32 tcpi_backoff = 5

• uint32 tcpi_options = 6

• uint32 tcpi_snd_wscale = 7

• uint32 tcpi_rcv_wscale = 8

• uint32 tcpi_rto = 9

• uint32 tcpi_ato = 10

• uint32 tcpi_snd_mss = 11

• uint32 tcpi_rcv_mss = 12

• uint32 tcpi_unacked = 13

• uint32 tcpi_sacked = 14

• uint32 tcpi_lost = 15

• uint32 tcpi_retrans = 16

• uint32 tcpi_fackets = 17

• uint32 tcpi_last_data_sent = 18

• uint32 tcpi_last_ack_sent = 19

• uint32 tcpi_last_data_recv = 20

• uint32 tcpi_last_ack_recv = 21

• uint32 tcpi_pmtu = 22

• uint32 tcpi_rcv_ssthresh = 23

• uint32 tcpi_rtt = 24

• uint32 tcpi_rttvar = 25

• uint32 tcpi_snd_ssthresh = 26

• uint32 tcpi_snd_cwnd = 27

• uint32 tcpi_advmss = 28

• uint32 tcpi_reordering = 29

For use with SocketOption's additional field. This is primarily used for SO_RCVTIMEO and SO_SNDTIMEO

• optional google.protobuf.Duration duration = 1

SocketRef is a reference to a Socket.

Used in: Channel, GetServerSocketsResponse, Server, Socket, Subchannel

• int64 socket_id = 3

  The globally unique id for this socket. Must be a positive number.

• string name = 4

  An optional name associated with the socket.

Subchannel is a logical grouping of channels, subchannels, and sockets. A subchannel is load balanced over by its ancestor

Used in: GetSubchannelResponse

• optional SubchannelRef ref = 1

  The identifier for this channel.

• optional ChannelData data = 2

  Data specific to this channel.

  At most one of 'channel_ref+subchannel_ref' and 'socket' is set.

• repeated ChannelRef channel_ref = 3

  There are no ordering guarantees on the order of channel refs. There may not be cycles in the ref graph. A channel ref may be present in more than one channel or subchannel.

• repeated SubchannelRef subchannel_ref = 4

  At most one of 'channel_ref+subchannel_ref' and 'socket' is set. There are no ordering guarantees on the order of subchannel refs. There may not be cycles in the ref graph. A sub channel ref may be present in more than one channel or subchannel.

• repeated SocketRef socket_ref = 5

  There are no ordering guarantees on the order of sockets.

SubchannelRef is a reference to a Subchannel.

Used in: Channel, ChannelTraceEvent, Subchannel

• int64 subchannel_id = 7

  The globally unique id for this subchannel. Must be a positive number.

• string name = 8

  An optional name associated with the subchannel.