channelz

package
v1.68.0 Latest Latest
Warning

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

 Go to latest Published: Nov 7, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package channelz defines internal APIs for enabling channelz service, entry registration/deletion, and accessing channelz data. It also defines channelz metric struct formats.

Index

Constants

View Source 
const (
	SocketTypeNormal = "NormalSocket"
	SocketTypeListen = "ListenSocket"
)

SocketType can be one of these.

Variables

This section is empty.

Functions

func AddTraceEvent added in v1.16.0 

func AddTraceEvent(l grpclog.DepthLoggerV2, e Entity, depth int, desc *TraceEvent)

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, e Entity, args ...any)

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

func Errorf added in v1.28.0 

func Errorf(l grpclog.DepthLoggerV2, e Entity, format string, args ...any)

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

func Info added in v1.28.0 

func Info(l grpclog.DepthLoggerV2, e Entity, args ...any)

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

func Infof added in v1.28.0 

func Infof(l grpclog.DepthLoggerV2, e Entity, format string, args ...any)

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 RemoveEntry 

func RemoveEntry(id int64)

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 entries per entity to default.

func SetMaxTraceEntry added in v1.16.0 

func SetMaxTraceEntry(i int32)

SetMaxTraceEntry sets maximum number of trace entries 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, e Entity, args ...any)

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

func Warningf added in v1.28.0 

func Warningf(l grpclog.DepthLoggerV2, e Entity, format string, args ...any)

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

Types

type Channel 

type Channel struct {
	Entity
	// ID is the channelz id of this channel.
	ID int64
	// RefName is the human readable reference string of this channel.
	RefName string

	Parent *Channel

	// ChannelMetrics holds connectivity state, target and call metrics for the
	// channel within channelz.
	ChannelMetrics ChannelMetrics
	// contains filtered or unexported fields
}

Channel represents a channel within channelz, which includes metrics and internal channelz data, such as channelz id, child list, etc.

func GetChannel 

func GetChannel(id int64) *Channel

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

func GetTopChannels 

func GetTopChannels(id int64, maxResults int) ([]*Channel, 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 EntriesPerPage if maxResults is zero, and is sorted in ascending id order.

func RegisterChannel 

func RegisterChannel(parent *Channel, target string) *Channel

RegisterChannel registers the given channel c in the channelz database with target as its target and reference name, and adds it to the child list of its parent. parent == 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 (*Channel) NestedChans added in v1.63.0 

func (c *Channel) NestedChans() map[int64]string

NestedChans returns a copy of the map of nested channels associated with the Channel.

func (*Channel) String added in v1.63.0 

func (c *Channel) String() string

String returns a string representation of the Channel, including its parent entity and ID.

func (*Channel) SubChans added in v1.63.0 

func (c *Channel) SubChans() map[int64]string

SubChans returns a copy of the map of sub-channels associated with the Channel.

func (*Channel) Trace added in v1.63.0 

func (c *Channel) Trace() *ChannelTrace

Trace returns a copy of the Channel's trace data.

type ChannelMetrics added in v1.63.0 

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

ChannelMetrics holds connectivity state, target and call metrics for the channel within channelz.

func NewChannelMetricForTesting added in v1.63.0 

func NewChannelMetricForTesting(state connectivity.State, target string, started, succeeded, failed, timestamp int64) *ChannelMetrics

NewChannelMetricForTesting creates a new instance of ChannelMetrics with specified initial values for testing purposes.

func (*ChannelMetrics) CopyFrom added in v1.63.0 

func (c *ChannelMetrics) CopyFrom(o *ChannelMetrics)

CopyFrom copies the metrics in o to c. For testing only.

func (*ChannelMetrics) Equal added in v1.63.0 

func (c *ChannelMetrics) Equal(o any) bool

Equal returns true iff the metrics of c are the same as the metrics of o. For testing only.

func (*ChannelMetrics) String added in v1.63.0 

func (c *ChannelMetrics) String() string

String returns a string representation of the ChannelMetrics, including its state, target, and call metrics.

type ChannelTrace added in v1.16.0 

type ChannelTrace struct {

	// The time when the trace was created.
	CreationTime time.Time
	// A counter for the number of events recorded in the
	// trace.
	EventNum int64

	// A slice of traceEvent pointers representing the events recorded for
	// this channel.
	Events []*traceEvent
	// contains filtered or unexported fields
}

ChannelTrace provides tracing information for a channel. It tracks various events and metadata related to the channel's lifecycle and operations.

type Entity added in v1.63.0 

type Entity interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

Entity is implemented by all channelz types.

type EphemeralSocketMetrics added in v1.63.0 

type EphemeralSocketMetrics struct {
	// 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
}

EphemeralSocketMetrics are metrics that change rapidly and are tracked outside of channelz.

type IDGenerator added in v1.58.0 

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

IDGenerator is an incrementing atomic that tracks IDs for channelz entities. 

var (
	// IDGen is the global channelz entity ID generator.  It should not be used
	// outside this package except by tests.
	IDGen IDGenerator

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

func (*IDGenerator) Reset added in v1.58.0 

func (i *IDGenerator) Reset()

Reset resets the generated ID back to zero. Should only be used at initialization or by tests sensitive to the ID number.

type Identifier added in v1.46.0 

type Identifier interface {
	Entity
	// contains filtered or unexported methods
}

Identifier is an opaque channelz identifier used to expose channelz symbols outside of grpc. Currently only implemented by Channel since no other types require exposure outside grpc.

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

String returns a string representation of the RefChannelType

type Server 

type Server struct {
	Entity
	ID      int64
	RefName string

	ServerMetrics ServerMetrics
	// contains filtered or unexported fields
}

Server is the channelz representation of a server.

func GetServer added in v1.18.0 

func GetServer(id int64) *Server

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

func GetServers 

func GetServers(id int64, maxResults int) ([]*Server, 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 EntriesPerPage if maxResults is zero, and is sorted in ascending id order.

func RegisterServer 

func RegisterServer(ref string) *Server

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 (*Server) ListenSockets added in v1.63.0 

func (s *Server) ListenSockets() map[int64]string

ListenSockets returns the listening sockets for s.

func (*Server) String added in v1.63.0 

func (s *Server) String() string

String returns a printable description of s.

type ServerMetrics added in v1.63.0 

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

ServerMetrics defines a struct containing metrics for servers.

func NewServerMetricsForTesting added in v1.63.0 

func NewServerMetricsForTesting(started, succeeded, failed, timestamp int64) *ServerMetrics

NewServerMetricsForTesting returns an initialized ServerMetrics.

func (*ServerMetrics) CopyFrom added in v1.63.0 

func (sm *ServerMetrics) CopyFrom(o *ServerMetrics)

CopyFrom copies the metrics data from the provided ServerMetrics instance into the current instance.

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 struct {
	Entity
	SocketType SocketType
	ID         int64
	Parent     Entity

	SocketMetrics    SocketMetrics
	EphemeralMetrics func() *EphemeralSocketMetrics

	RefName string
	// The locally bound address.  Immutable.
	LocalAddr net.Addr
	// The remote bound address.  May be absent.  Immutable.
	RemoteAddr net.Addr
	// Optional, represents the name of the remote endpoint, if different than
	// the original target name.  Immutable.
	RemoteName string
	// Immutable.
	SocketOptions *SocketOptionData
	// Immutable.
	Security credentials.ChannelzSecurityValue
	// contains filtered or unexported fields
}

Socket represents a socket within channelz which includes socket metrics and data related to socket activity and provides methods for managing and interacting with sockets.

func GetServerSockets 

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

GetServerSockets returns a slice of server's (identified by id) normal socket's SocketMetrics, 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 EntriesPerPage if maxResults is zero, and is sorted in ascending id order.

func GetSocket 

func GetSocket(id int64) *Socket

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

func RegisterSocket added in v1.63.0 

func RegisterSocket(skt *Socket) *Socket

RegisterSocket 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 skt.Parent, which must be set). 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 (*Socket) String added in v1.63.0 

func (ls *Socket) String() string

String returns a string representation of the Socket, including its parent entity, socket type, and ID.

type SocketMetrics added in v1.63.0 

type SocketMetrics struct {
	// The number of streams that have been started.
	StreamsStarted atomic.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 atomic.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 atomic.Int64
	// The number of messages successfully sent on this socket.
	MessagesSent     atomic.Int64
	MessagesReceived atomic.Int64
	// The number of keep alives sent.  This is typically implemented with HTTP/2
	// ping messages.
	KeepAlivesSent atomic.Int64
	// The last time a stream was created by this endpoint.  Usually unset for
	// servers.
	LastLocalStreamCreatedTimestamp atomic.Int64
	// The last time a stream was created by the remote endpoint.  Usually unset
	// for clients.
	LastRemoteStreamCreatedTimestamp atomic.Int64
	// The last time a message was sent by this endpoint.
	LastMessageSentTimestamp atomic.Int64
	// The last time a message was received by this endpoint.
	LastMessageReceivedTimestamp atomic.Int64
}

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

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 any) *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 SocketType added in v1.63.0 

type SocketType string

SocketType represents the type of socket.

type SubChannel added in v1.63.0 

type SubChannel struct {
	Entity
	// ID is the channelz id of this subchannel.
	ID int64
	// RefName is the human readable reference string of this subchannel.
	RefName string

	ChannelMetrics ChannelMetrics
	// contains filtered or unexported fields
}

SubChannel is the channelz representation of a subchannel.

func GetSubChannel 

func GetSubChannel(id int64) *SubChannel

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

func RegisterSubChannel 

func RegisterSubChannel(parent *Channel, ref string) *SubChannel

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 (*SubChannel) Sockets added in v1.63.0 

func (sc *SubChannel) Sockets() map[int64]string

Sockets returns a copy of the sockets map associated with the SubChannel.

func (*SubChannel) String added in v1.63.0 

func (sc *SubChannel) String() string

func (*SubChannel) Trace added in v1.63.0 

func (sc *SubChannel) Trace() *ChannelTrace

Trace returns a copy of the ChannelTrace associated with the SubChannel.

type TraceEvent added in v1.16.0 

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

TraceEvent 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.