channelz

package
v1.56.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2023 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

View Source 
var (

	// EntryPerPage defines the number of channelz entries to be shown on a web page.
	EntryPerPage = int64(50)
)

Functions

func AddTraceEvent added in v1.16.0 

func AddTraceEvent(l grpclog.DepthLoggerV2, id *Identifier, depth int, desc *TraceEventDesc)

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.

func Error added in v1.28.0 

func Error(l grpclog.DepthLoggerV2, id *Identifier, args ...interface{})

Error logs and adds a trace event if channelz is on.

func Errorf added in v1.28.0 

func Errorf(l grpclog.DepthLoggerV2, id *Identifier, format string, args ...interface{})

Errorf logs and adds a trace event if channelz is on.

func Info added in v1.28.0 

func Info(l grpclog.DepthLoggerV2, id *Identifier, args ...interface{})

Info logs and adds a trace event if channelz is on.

func Infof added in v1.28.0 

func Infof(l grpclog.DepthLoggerV2, id *Identifier, format string, args ...interface{})

Infof logs and adds a trace event if channelz is on.

func IsOn 

func IsOn() bool

IsOn returns whether channelz data collection is on.

func NewChannelzStorageForTesting added in v1.45.0 

func NewChannelzStorageForTesting() (cleanup func() error)

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.

func RemoveEntry 

func RemoveEntry(id *Identifier)

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.

func ResetMaxTraceEntryToDefault added in v1.16.0 

func ResetMaxTraceEntryToDefault()

ResetMaxTraceEntryToDefault resets the maximum number of trace entry per entity to default.

func SetMaxTraceEntry added in v1.16.0 

func SetMaxTraceEntry(i int32)

SetMaxTraceEntry sets maximum number of trace entry per entity (i.e. channel/subchannel). Setting it to 0 will disable channel tracing.

func TurnOn 

func TurnOn()

TurnOn turns on channelz data collection.

func Warning added in v1.28.0 

func Warning(l grpclog.DepthLoggerV2, id *Identifier, args ...interface{})

Warning logs and adds a trace event if channelz is on.

func Warningf added in v1.28.0 

func Warningf(l grpclog.DepthLoggerV2, id *Identifier, format string, args ...interface{})

Warningf logs and adds a trace event if channelz is on.

Types

type Channel 

type Channel interface {
	ChannelzMetric() *ChannelInternalMetric
}

Channel is the interface that should be satisfied in order to be tracked by channelz as Channel or SubChannel.

type ChannelInternalMetric 

type ChannelInternalMetric struct {
	// current connectivity state of the channel.
	State connectivity.State
	// The target this channel originally tried to connect to.  May be absent
	Target string
	// The number of calls started on the channel.
	CallsStarted int64
	// The number of calls that have completed with an OK status.
	CallsSucceeded int64
	// The number of calls that have a completed with a non-OK status.
	CallsFailed int64
	// The last time a call was started on the channel.
	LastCallStartedTimestamp time.Time
}

ChannelInternalMetric defines the struct that the implementor of Channel interface should return from ChannelzMetric().

type ChannelMetric 

type ChannelMetric struct {
	// ID is the channelz id of this channel.
	ID int64
	// RefName is the human readable reference string of this channel.
	RefName string
	// ChannelData contains channel internal metric reported by the channel through
	// ChannelzMetric().
	ChannelData *ChannelInternalMetric
	// 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.
	NestedChans map[int64]string
	// SubChans tracks the subchannel type children of this channel in the format of a
	// map from subchannel channelz id to corresponding reference string.
	SubChans map[int64]string
	// 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.
	Sockets map[int64]string
	// Trace contains the most recent traced events.
	Trace *ChannelTrace
}

ChannelMetric defines the info channelz provides for a specific Channel, which includes ChannelInternalMetric and channelz-specific data, such as channelz id, child list, etc.

func GetChannel 

func GetChannel(id int64) *ChannelMetric

GetChannel returns the ChannelMetric for the channel (identified by id).

func GetTopChannels 

func GetTopChannels(id int64, maxResults int64) ([]*ChannelMetric, bool)

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.

type ChannelTrace added in v1.16.0 

type ChannelTrace struct {
	// EventNum is the number of events that ever got traced (i.e. including those that have been deleted)
	EventNum int64
	// CreationTime is the creation time of the trace.
	CreationTime time.Time
	// Events stores the most recent trace events (up to $maxTraceEntry, newer event will overwrite the
	// oldest one)
	Events []*TraceEvent
}

ChannelTrace stores traced events on a channel/subchannel and related info.

type Identifier added in v1.46.0 

type Identifier struct {
	// contains filtered or unexported fields
}

Identifier is an opaque identifier which uniquely identifies an entity in the channelz database.

func NewIdentifierForTesting added in v1.46.0 

func NewIdentifierForTesting(typ RefChannelType, id int64, pid *Identifier) *Identifier

NewIdentifierForTesting returns a new opaque identifier to be used only for testing purposes.

func RegisterChannel 

func RegisterChannel(c Channel, pid *Identifier, ref string) *Identifier

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.

func RegisterListenSocket 

func RegisterListenSocket(s Socket, pid *Identifier, ref string) (*Identifier, error)

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.

func RegisterNormalSocket 

func RegisterNormalSocket(s Socket, pid *Identifier, ref string) (*Identifier, error)

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.

func RegisterServer 

func RegisterServer(s Server, ref string) *Identifier

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.

func RegisterSubChannel 

func RegisterSubChannel(c Channel, pid *Identifier, ref string) (*Identifier, error)

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.

func (*Identifier) Equal added in v1.46.0 

func (id *Identifier) Equal(other *Identifier) bool

Equal returns true if other is the same as id.

func (*Identifier) Int added in v1.46.0 

func (id *Identifier) Int() int64

Int returns the integer identifier corresponding to id.

func (*Identifier) String added in v1.46.0 

func (id *Identifier) String() string

String returns a string representation of the entity corresponding to id.

This includes some information about the parent as well. Examples: Top-level channel: [Channel #channel-number] Nested channel: [Channel #parent-channel-number Channel #channel-number] Sub channel: [Channel #parent-channel SubChannel #subchannel-number]

func (*Identifier) Type added in v1.46.0 

func (id *Identifier) Type() RefChannelType

Type returns the entity type corresponding to id.

type RefChannelType added in v1.16.0 

type RefChannelType int

RefChannelType is the type of the entity being referenced in a trace event. 

const (
	// RefUnknown indicates an unknown entity type, the zero value for this type.
	RefUnknown RefChannelType = iota
	// RefChannel indicates the referenced entity is a Channel.
	RefChannel
	// RefSubChannel indicates the referenced entity is a SubChannel.
	RefSubChannel
	// RefServer indicates the referenced entity is a Server.
	RefServer
	// RefListenSocket indicates the referenced entity is a ListenSocket.
	RefListenSocket
	// RefNormalSocket indicates the referenced entity is a NormalSocket.
	RefNormalSocket
)

func (RefChannelType) String added in v1.46.0 

func (r RefChannelType) String() string

type Server 

type Server interface {
	ChannelzMetric() *ServerInternalMetric
}

Server is the interface to be satisfied in order to be tracked by channelz as Server.

type ServerInternalMetric 

type ServerInternalMetric struct {
	// The number of incoming calls started on the server.
	CallsStarted int64
	// The number of incoming calls that have completed with an OK status.
	CallsSucceeded int64
	// The number of incoming calls that have a completed with a non-OK status.
	CallsFailed int64
	// The last time a call was started on the server.
	LastCallStartedTimestamp time.Time
}

ServerInternalMetric defines the struct that the implementor of Server interface should return from ChannelzMetric().

type ServerMetric 

type ServerMetric struct {
	// ID is the channelz id of this server.
	ID int64
	// RefName is the human readable reference string of this server.
	RefName string
	// ServerData contains server internal metric reported by the server through
	// ChannelzMetric().
	ServerData *ServerInternalMetric
	// ListenSockets tracks the listener socket type children of this server in the
	// format of a map from socket channelz id to corresponding reference string.
	ListenSockets map[int64]string
}

ServerMetric defines the info channelz provides for a specific Server, which includes ServerInternalMetric and channelz-specific data, such as channelz id, child list, etc.

func GetServer added in v1.18.0 

func GetServer(id int64) *ServerMetric

GetServer returns the ServerMetric for the server (identified by id).

func GetServers 

func GetServers(id int64, maxResults int64) ([]*ServerMetric, bool)

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.

type Severity added in v1.16.0 

type Severity int

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 (
	// CtUnknown indicates unknown severity of a trace event.
	CtUnknown Severity = iota
	// CtInfo indicates info level severity of a trace event.
	CtInfo
	// CtWarning indicates warning level severity of a trace event.
	CtWarning
	// CtError indicates error level severity of a trace event.
	CtError
)

type Socket 

type Socket interface {
	ChannelzMetric() *SocketInternalMetric
}

Socket is the interface that should be satisfied in order to be tracked by channelz as Socket.

type SocketInternalMetric 

type SocketInternalMetric struct {
	// The number of streams that have been started.
	StreamsStarted int64
	// 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.
	StreamsSucceeded int64
	// 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.
	StreamsFailed int64
	// The number of messages successfully sent on this socket.
	MessagesSent     int64
	MessagesReceived int64
	// The number of keep alives sent.  This is typically implemented with HTTP/2
	// ping messages.
	KeepAlivesSent int64
	// The last time a stream was created by this endpoint.  Usually unset for
	// servers.
	LastLocalStreamCreatedTimestamp time.Time
	// The last time a stream was created by the remote endpoint.  Usually unset
	// for clients.
	LastRemoteStreamCreatedTimestamp time.Time
	// The last time a message was sent by this endpoint.
	LastMessageSentTimestamp time.Time
	// The last time a message was received by this endpoint.
	LastMessageReceivedTimestamp time.Time
	// 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.
	LocalFlowControlWindow int64
	// 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.
	RemoteFlowControlWindow int64
	// The locally bound address.
	LocalAddr net.Addr
	// The remote bound address.  May be absent.
	RemoteAddr net.Addr
	// Optional, represents the name of the remote endpoint, if different than
	// the original target name.
	RemoteName    string
	SocketOptions *SocketOptionData
	Security      credentials.ChannelzSecurityValue
}

SocketInternalMetric defines the struct that the implementor of Socket interface should return from ChannelzMetric().

type SocketMetric 

type SocketMetric struct {
	// ID is the channelz id of this socket.
	ID int64
	// RefName is the human readable reference string of this socket.
	RefName string
	// SocketData contains socket internal metric reported by the socket through
	// ChannelzMetric().
	SocketData *SocketInternalMetric
}

SocketMetric defines the info channelz provides for a specific Socket, which includes SocketInternalMetric and channelz-specific data, such as channelz id, etc.

func GetServerSockets 

func GetServerSockets(id int64, startID int64, maxResults int64) ([]*SocketMetric, bool)

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.

func GetSocket 

func GetSocket(id int64) *SocketMetric

GetSocket returns the SocketInternalMetric for the socket (identified by id).

type SocketOptionData added in v1.14.0 

type SocketOptionData struct {
	Linger      *unix.Linger
	RecvTimeout *unix.Timeval
	SendTimeout *unix.Timeval
	TCPInfo     *unix.TCPInfo
}

SocketOptionData defines the struct to hold socket option data, and related getter function to obtain info from fd.

func GetSocketOption added in v1.14.0 

func GetSocketOption(socket interface{}) *SocketOptionData

GetSocketOption gets the socket option info of the conn.

func (*SocketOptionData) Getsockopt added in v1.14.0 

func (s *SocketOptionData) Getsockopt(fd uintptr)

Getsockopt defines the function to get socket options requested by channelz. It is to be passed to syscall.RawConn.Control().

type SubChannelMetric 

type SubChannelMetric struct {
	// ID is the channelz id of this subchannel.
	ID int64
	// RefName is the human readable reference string of this subchannel.
	RefName string
	// ChannelData contains subchannel internal metric reported by the subchannel
	// through ChannelzMetric().
	ChannelData *ChannelInternalMetric
	// NestedChans tracks the nested channel type children of this subchannel in the format of
	// a map from nested channel channelz id to corresponding reference string.
	// Note current grpc implementation doesn't allow subchannel to have nested channels
	// as children, therefore, this field is unused.
	NestedChans map[int64]string
	// SubChans tracks the subchannel type children of this subchannel in the format of a
	// map from subchannel channelz id to corresponding reference string.
	// Note current grpc implementation doesn't allow subchannel to have subchannels
	// as children, therefore, this field is unused.
	SubChans map[int64]string
	// Sockets tracks the socket type children of this subchannel in the format of a map
	// from socket channelz id to corresponding reference string.
	Sockets map[int64]string
	// Trace contains the most recent traced events.
	Trace *ChannelTrace
}

SubChannelMetric defines the info channelz provides for a specific SubChannel, which includes ChannelInternalMetric and channelz-specific data, such as channelz id, child list, etc.

func GetSubChannel 

func GetSubChannel(id int64) *SubChannelMetric

GetSubChannel returns the SubChannelMetric for the subchannel (identified by id).

type TraceEvent added in v1.16.0 

type TraceEvent struct {
	// Desc is a simple description of the trace event.
	Desc string
	// Severity states the severity of this trace event.
	Severity Severity
	// Timestamp is the event time.
	Timestamp time.Time
	// 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 [])
	RefID int64
	// RefName is the reference name for the entity that gets referenced in the event.
	RefName string
	// RefType indicates the referenced entity type, i.e Channel or SubChannel.
	RefType RefChannelType
}

TraceEvent represent a single trace event

type TraceEventDesc added in v1.16.0 

type TraceEventDesc struct {
	Desc     string
	Severity Severity
	Parent   *TraceEventDesc
}

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.