Involved Source Files
Package channelz defines APIs for enabling channelz service, entry
registration/deletion, and accessing channelz data. It also defines channelz
metric struct formats.
All APIs in this package are experimental.
id.gologging.gotypes.gotypes_linux.goutil_linux.go
Package-Level Type Names (total 31, in which 17 are exported)
ChannelInternalMetric defines the struct that the implementor of Channel interface
should return from ChannelzMetric().
The number of calls that have a completed with a non-OK status.
The number of calls started on the channel.
The number of calls that have completed with an OK status.
The last time a call was started on the channel.
current connectivity state of the channel.
The target this channel originally tried to connect to. May be absent
func Channel.ChannelzMetric() *ChannelInternalMetric
func google.golang.org/grpc.(*ClientConn).channelzMetric() *ChannelInternalMetric
ChannelMetric defines the info channelz provides for a specific Channel, which
includes ChannelInternalMetric and channelz-specific data, such as channelz id,
child list, etc.
ChannelData contains channel internal metric reported by the channel through
ChannelzMetric().
ID is the channelz id of this channel.
NestedChans tracks the nested channel type children of this channel in the format of
a map from nested channel channelz id to corresponding reference string.
RefName is the human readable reference string of this channel.
Sockets tracks the socket type children of this channel in the format of a map
from socket channelz id to corresponding reference string.
Note current grpc implementation doesn't allow channel having sockets directly,
therefore, this is field is unused.
SubChans tracks the subchannel type children of this channel in the format of a
map from subchannel channelz id to corresponding reference string.
Trace contains the most recent traced events.
func GetChannel(id int64) *ChannelMetric
func GetTopChannels(id int64, maxResults int64) ([]*ChannelMetric, bool)
ChannelTrace stores traced events on a channel/subchannel and related info.
CreationTime is the creation time of the trace.
EventNum is the number of events that ever got traced (i.e. including those that have been deleted)
Events stores the most recent trace events (up to $maxTraceEntry, newer event will overwrite the
oldest one)
ServerInternalMetric defines the struct that the implementor of Server interface
should return from ChannelzMetric().
The number of incoming calls that have a completed with a non-OK status.
The number of incoming calls started on the server.
The number of incoming calls that have completed with an OK status.
The last time a call was started on the server.
func Server.ChannelzMetric() *ServerInternalMetric
func google.golang.org/grpc.(*Server).channelzMetric() *ServerInternalMetric
ServerMetric defines the info channelz provides for a specific Server, which
includes ServerInternalMetric and channelz-specific data, such as channelz id,
child list, etc.
ID is the channelz id of this server.
ListenSockets tracks the listener socket type children of this server in the
format of a map from socket channelz id to corresponding reference string.
RefName is the human readable reference string of this server.
ServerData contains server internal metric reported by the server through
ChannelzMetric().
func GetServer(id int64) *ServerMetric
func GetServers(id int64, maxResults int64) ([]*ServerMetric, bool)
Severity is the severity level of a trace event.
The canonical enumeration of all valid values is here:
https://github.com/grpc/grpc-proto/blob/9b13d199cc0d4703c7ea26c9c330ba695866eb23/grpc/channelz/v1/channelz.proto#L126.
const CtError
const CtInfo
const CtUnknown
const CtWarning
SocketInternalMetric defines the struct that the implementor of Socket interface
should return from ChannelzMetric().
The number of keep alives sent. This is typically implemented with HTTP/2
ping messages.
The last time a stream was created by this endpoint. Usually unset for
servers.
The last time a message was received by this endpoint.
The last time a message was sent by this endpoint.
The last time a stream was created by the remote endpoint. Usually unset
for clients.
The locally bound address.
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.
MessagesReceivedint64
The number of messages successfully sent on this socket.
The remote bound address. May be absent.
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.
Optional, represents the name of the remote endpoint, if different than
the original target name.
Securitycredentials.ChannelzSecurityValueSocketOptions*SocketOptionData
The number of streams that have ended unsuccessfully:
On client side, termination without receiving frame with eos bit set.
On server side, termination without sending frame with eos bit set.
The number of streams that have been started.
The number of streams that have ended successfully:
On client side, receiving frame with eos bit set.
On server side, sending frame with eos bit set.
func Socket.ChannelzMetric() *SocketInternalMetric
SocketMetric defines the info channelz provides for a specific Socket, which
includes SocketInternalMetric and channelz-specific data, such as channelz id, etc.
ID is the channelz id of this socket.
RefName is the human readable reference string of this socket.
SocketData contains socket internal metric reported by the socket through
ChannelzMetric().
func GetServerSockets(id int64, startID int64, maxResults int64) ([]*SocketMetric, bool)
func GetSocket(id int64) *SocketMetric
SocketOptionData defines the struct to hold socket option data, and related
getter function to obtain info from fd.
Linger*unix.LingerRecvTimeout*unix.TimevalSendTimeout*unix.TimevalTCPInfo*unix.TCPInfo
Getsockopt defines the function to get socket options requested by channelz.
It is to be passed to syscall.RawConn.Control().
func GetSocketOption(socket interface{}) *SocketOptionData
SubChannelMetric defines the info channelz provides for a specific SubChannel,
which includes ChannelInternalMetric and channelz-specific data, such as
channelz id, child list, etc.
ChannelData contains channel internal metric reported by the channel through
ChannelzMetric().
ID is the channelz id of this channel.
NestedChans tracks the nested channel type children of this channel in the format of
a map from nested channel channelz id to corresponding reference string.
RefName is the human readable reference string of this channel.
Sockets tracks the socket type children of this channel in the format of a map
from socket channelz id to corresponding reference string.
Note current grpc implementation doesn't allow channel having sockets directly,
therefore, this is field is unused.
SubChans tracks the subchannel type children of this channel in the format of a
map from subchannel channelz id to corresponding reference string.
Trace contains the most recent traced events.
func GetSubChannel(id int64) *SubChannelMetric
TraceEvent represent a single trace event
Desc is a simple description of the trace event.
RefID is the id of the entity that gets referenced in the event. RefID is 0 if no other entity is
involved in this event.
e.g. SubChannel (id: 4[]) Created. --> RefID = 4, RefName = "" (inside [])
RefName is the reference name for the entity that gets referenced in the event.
RefType indicates the referenced entity type, i.e Channel or SubChannel.
Severity states the severity of this trace event.
Timestamp is the event time.
TraceEventDesc is what the caller of AddTraceEvent should provide to describe
the event to be added to the channel trace.
The Parent field is optional. It is used for an event that will be recorded
in the entity's parent trace.
DescstringParent*TraceEventDescSeveritySeverity
func AddTraceEvent(l grpclog.DepthLoggerV2, id *Identifier, depth int, desc *TraceEventDesc)
cChannelcloseCalledboolcm*channelMapidint64nestedChansmap[int64]stringpidint64refNamestringsubChansmap[int64]stringtrace*channelTrace
traceRefCount is the number of trace events that reference this channel.
Non-zero traceRefCount means the trace of this channel cannot be deleted.
(*channel) addChild(id int64, e entry)(*channel) decrTraceRefCount()(*channel) deleteChild(id int64)
deleteSelfFromMap checks whether it is valid to delete the channel from the map, which means
deleting the channel from channelz's tracking entirely. Users can no longer use id to query the
channel, and its memory will be garbage collected.
The trace reference count of the channel must be 0 in order to be deleted from the map. This is
specified in the channel tracing gRFC that as long as some other trace has reference to an entity,
the trace of the referenced entity must not be deleted. In order to release the resource allocated
by grpc, the reference to the grpc object is reset to a dummy object.
deleteSelfFromMap must be called after deleteSelfFromTree returns true.
It returns a bool to indicate whether the channel can be safely deleted from map.
deleteSelfFromTree tries to delete the channel from the channelz entry relation tree, which means
deleting the channel reference from its parent's child list.
In order for a channel to be deleted from the tree, it must meet the criteria that, removal of the
corresponding grpc object has been invoked, and the channel does not have any children left.
The returned boolean value indicates whether the channel has been successfully deleted from tree.
deleteSelfIfReady tries to delete the channel itself from the channelz database.
The delete process includes two steps:
1. delete the channel from the entry relation tree, i.e. delete the channel reference from its
parent's child list.
2. delete the channel from the map, i.e. delete the channel entirely from channelz. Lookup by id
will return entry not found error.
(*channel) getChannelTrace() *channelTrace(*channel) getParentID() int64(*channel) getRefName() string(*channel) getTraceRefCount() int(*channel) incrTraceRefCount()(*channel) triggerDelete()
*channel : entry
*channel : tracedChannel
dbWarpper wraps around a reference to internal channelz data storage, and
provide synchronized functionality to set and get the reference.
DB*channelMapmusync.RWMutex(*dbWrapper) get() *channelMap(*dbWrapper) set(db *channelMap)
var db
entry represents a node in the channelz database.
addChild adds a child e, whose channelz id is id to child list
deleteChild deletes a child with channelz id to be id from child list
deleteSelfIfReady check whether triggerDelete() has been called before, and whether child
list is now empty. If both conditions are met, then delete self from database.
getParentID returns parent ID of the entry. 0 value parent ID means no parent.
triggerDelete tries to delete self from channelz database. However, if child
list is not empty, then deletion from the database is on hold until the last
child is deleted from database.
*channel
*dummyEntry
*listenSocket
*normalSocket
*server
*subChannel
cChannelcloseCalledboolcm*channelMapidint64pidint64refNamestringsocketsmap[int64]stringtrace*channelTracetraceRefCountint32(*subChannel) addChild(id int64, e entry)(*subChannel) decrTraceRefCount()(*subChannel) deleteChild(id int64)
deleteSelfFromMap checks whether it is valid to delete the subchannel from the map, which means
deleting the subchannel from channelz's tracking entirely. Users can no longer use id to query
the subchannel, and its memory will be garbage collected.
The trace reference count of the subchannel must be 0 in order to be deleted from the map. This is
specified in the channel tracing gRFC that as long as some other trace has reference to an entity,
the trace of the referenced entity must not be deleted. In order to release the resource allocated
by grpc, the reference to the grpc object is reset to a dummy object.
deleteSelfFromMap must be called after deleteSelfFromTree returns true.
It returns a bool to indicate whether the channel can be safely deleted from map.
deleteSelfFromTree tries to delete the subchannel from the channelz entry relation tree, which
means deleting the subchannel reference from its parent's child list.
In order for a subchannel to be deleted from the tree, it must meet the criteria that, removal of
the corresponding grpc object has been invoked, and the subchannel does not have any children left.
The returned boolean value indicates whether the channel has been successfully deleted from tree.
deleteSelfIfReady tries to delete the subchannel itself from the channelz database.
The delete process includes two steps:
1. delete the subchannel from the entry relation tree, i.e. delete the subchannel reference from
its parent's child list.
2. delete the subchannel from the map, i.e. delete the subchannel entirely from channelz. Lookup
by id will return entry not found error.
(*subChannel) getChannelTrace() *channelTrace(*subChannel) getParentID() int64(*subChannel) getRefName() string(*subChannel) getTraceRefCount() int(*subChannel) incrTraceRefCount()(*subChannel) triggerDelete()
*subChannel : entry
*subChannel : tracedChannel
Package-Level Functions (total 33, in which 27 are exported)
AddTraceEvent adds trace related to the entity with specified id, using the
provided TraceEventDesc.
If channelz is not turned ON, this will simply log the event descriptions.
Error logs and adds a trace event if channelz is on.
Errorf logs and adds a trace event if channelz is on.
GetChannel returns the ChannelMetric for the channel (identified by id).
GetServer returns the ServerMetric for the server (identified by id).
GetServers returns a slice of server's ServerMetric, along with a
boolean indicating whether there's more servers to be queried for.
The arg id specifies that only server with id at or above it will be included
in the result. The returned slice is up to a length of the arg maxResults or
EntryPerPage if maxResults is zero, and is sorted in ascending id order.
GetServerSockets returns a slice of server's (identified by id) normal socket's
SocketMetric, along with a boolean indicating whether there's more sockets to
be queried for.
The arg startID specifies that only sockets with id at or above it will be
included in the result. The returned slice is up to a length of the arg maxResults
or EntryPerPage if maxResults is zero, and is sorted in ascending id order.
GetSocket returns the SocketInternalMetric for the socket (identified by id).
GetSocketOption gets the socket option info of the conn.
GetSubChannel returns the SubChannelMetric for the subchannel (identified by id).
GetTopChannels returns a slice of top channel's ChannelMetric, along with a
boolean indicating whether there's more top channels to be queried for.
The arg id specifies that only top channel with id at or above it will be included
in the result. The returned slice is up to a length of the arg maxResults or
EntryPerPage if maxResults is zero, and is sorted in ascending id order.
Info logs and adds a trace event if channelz is on.
Infof logs and adds a trace event if channelz is on.
IsOn returns whether channelz data collection is on.
NewChannelzStorageForTesting initializes channelz data storage and id
generator for testing purposes.
Returns a cleanup function to be invoked by the test, which waits for up to
10s for all channelz state to be reset by the grpc goroutines when those
entities get closed. This cleanup function helps with ensuring that tests
don't mess up each other.
NewIdentifierForTesting returns a new opaque identifier to be used only for
testing purposes.
RegisterChannel registers the given channel c in the channelz database with
ref as its reference name, and adds it to the child list of its parent
(identified by pid). pid == nil means no parent.
Returns a unique channelz identifier assigned to this channel.
If channelz is not turned ON, the channelz database is not mutated.
RegisterListenSocket registers the given listen socket s in channelz database
with ref as its reference name, and add it to the child list of its parent
(identified by pid). It returns the unique channelz tracking id assigned to
this listen socket.
If channelz is not turned ON, the channelz database is not mutated.
RegisterNormalSocket registers the given normal socket s in channelz database
with ref as its reference name, and adds it to the child list of its parent
(identified by pid). It returns the unique channelz tracking id assigned to
this normal socket.
If channelz is not turned ON, the channelz database is not mutated.
RegisterServer registers the given server s in channelz database. It returns
the unique channelz tracking id assigned to this server.
If channelz is not turned ON, the channelz database is not mutated.
RegisterSubChannel registers the given subChannel c in the channelz database
with ref as its reference name, and adds it to the child list of its parent
(identified by pid).
Returns a unique channelz identifier assigned to this subChannel.
If channelz is not turned ON, the channelz database is not mutated.
RemoveEntry removes an entry with unique channelz tracking id to be id from
channelz database.
If channelz is not turned ON, this function is a no-op.
ResetMaxTraceEntryToDefault resets the maximum number of trace entry per entity to default.
SetMaxTraceEntry sets maximum number of trace entry per entity (i.e. channel/subchannel).
Setting it to 0 will disable channel tracing.
TurnOn turns on channelz data collection.
Warning logs and adds a trace event if channelz is on.
Warningf logs and adds a trace event if channelz is on.