rpcinfo

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Jan 26, 2026 License: Apache-2.0 Imports: 18 Imported by: 993

Documentation

Index

Constants

View Source
const (
	ConnResetTag     = "crrst"
	RetryTag         = "retry"
	RetryLastCostTag = "last_cost"
	RetryPrevInstTag = "prev_inst"
	ShmIPCTag        = "shmipc"
	RemoteClosedTag  = "remote_closed"
)

Tag names in EndpointInfo. Notice: These keys just be used for framework.

View Source
const (
	// connection full url
	HTTPURL = "http_url"
	// specify host header
	HTTPHost = "http_host"
	// http header for remote message tag
	HTTPHeader = "http_header"
)

client HTTP

View Source
const (
	BitRPCTimeout = 1 << iota
	BitConnectTimeout
	BitReadWriteTimeout
	BitIOBufferSize
)

Mask bits.

View Source
const InvocationServiceInfoKey = "service_info_key"

InvocationServiceInfoKey is the extra key of invocation which stores the ServiceInfo of the rpc call. The reason for adding the extra key is to shield ServiceInfo from users in the Invocation interface definition, as it is a pointer type and may be modified insecurely if obtained by users.

Variables

This section is empty.

Functions

func CalcEventCostUs added in v0.6.0

func CalcEventCostUs(start, end Event) uint64

CalcEventCostUs calculates the duration between start and end and returns in microsecond.

func ClientPanicToErr added in v0.6.0

func ClientPanicToErr(ctx context.Context, panicInfo interface{}, ri RPCInfo, logErr bool) error

ClientPanicToErr to transform the panic info to error, and output the error if needed.

func EnablePool added in v0.8.0

func EnablePool(enable bool)

EnablePool allows user to enable/disable rpcInfoPool. It's enabled by default for performance, but may cause trouble due to misuses:

referencing RPCInfo in another goroutine other than the one running the handler.

By turning off the pool, we can quickly confirm whether the concurrency issues is caused by such cases, but do remember there's a PERFORMANCE LOSS.

func FreezeRPCInfo added in v0.2.0

func FreezeRPCInfo(ctx context.Context) context.Context

FreezeRPCInfo returns a new context containing an RPCInfo that is safe to be used asynchronically. Note that the RPCStats of the freezed RPCInfo will be nil and the FreezeRPCInfo itself should not be used asynchronically.

Example:

func (p *MyServiceImpl) MyMethod(ctx context.Context, req *MyRequest) (resp *MyResponse, err error) {
    ri := rpcinfo.GetRPCInfo(ctx)
    go func(ctx context.Context) {
        ...
        ri := rpcinfo.GetRPCInfo(ctx) // not concurrent-safe
        ...
    }(ctx)

    ctx2 := rpcinfo.FreezeRPCInfo(ctx) // this creates a read-only copy of `ri` and attaches it to the new context
    go func(ctx context.Context) {
        ...
        ri := rpcinfo.GetRPCInfo(ctx) // OK
        ...
    }(ctx2)
}

func NewCtxWithRPCInfo

func NewCtxWithRPCInfo(ctx context.Context, ri RPCInfo) context.Context

NewCtxWithRPCInfo creates a new context with the RPCInfo given.

func NewInvocation

func NewInvocation(service, method string, pkgOpt ...string) *invocation

NewInvocation creates a new Invocation with the given service, method and optional package.

func PoolEnabled added in v0.9.0

func PoolEnabled() bool

PoolEnabled returns true if rpcInfoPool is enabled.

func PutRPCInfo

func PutRPCInfo(ri RPCInfo)

PutRPCInfo recycles the RPCInfo. This function is for internal use only.

func Record added in v0.6.0

func Record(ctx context.Context, ri RPCInfo, event stats.Event, err error)

Record records the event to RPCStats.

Types

type ClientStreamEventHandler added in v0.16.0

type ClientStreamEventHandler struct {
	HandleStreamStartEvent      func(ctx context.Context, ri RPCInfo, evt StreamStartEvent)
	HandleStreamRecvHeaderEvent func(ctx context.Context, ri RPCInfo, evt StreamRecvHeaderEvent)
	HandleStreamRecvEvent       func(ctx context.Context, ri RPCInfo, evt StreamRecvEvent)
	HandleStreamSendEvent       func(ctx context.Context, ri RPCInfo, evt StreamSendEvent)
	HandleStreamFinishEvent     func(ctx context.Context, ri RPCInfo, evt StreamFinishEvent)
}

ClientStreamEventHandler defines a series handler for client-side detailed Streaming Event tracing.

type EndpointBasicInfo

type EndpointBasicInfo struct {
	ServiceName string
	Method      string
	Tags        map[string]string
}

EndpointBasicInfo should be immutable after created.

type EndpointInfo

type EndpointInfo interface {
	ServiceName() string
	Method() string
	Address() net.Addr
	Tag(key string) (value string, exist bool)
	DefaultTag(key, def string) string
}

EndpointInfo contains info for endpoint.

func EmptyEndpointInfo

func EmptyEndpointInfo() EndpointInfo

EmptyEndpointInfo creates an empty EndpointInfo.

func FromBasicInfo

func FromBasicInfo(bi *EndpointBasicInfo) EndpointInfo

FromBasicInfo converts an EndpointBasicInfo into EndpointInfo.

func NewEndpointInfo

func NewEndpointInfo(serviceName, method string, address net.Addr, tags map[string]string) EndpointInfo

NewEndpointInfo creates an immutable EndpointInfo with the given information.

type Event

type Event interface {
	Event() stats.Event
	Status() stats.Status
	Info() string
	Time() time.Time
	IsNil() bool
}

Event is the abstraction of an event happened at a specific time.

func NewEvent added in v0.9.0

func NewEvent(statsEvent stats.Event, status stats.Status, info string) Event

NewEvent creates a new Event based on the given event, status and info.

It's only used by ReportStreamEvent

type InteractionMode added in v0.0.6

type InteractionMode int32
const (
	PingPong  InteractionMode = 0
	Oneway    InteractionMode = 1
	Streaming InteractionMode = 2
)

type Invocation

type Invocation interface {
	PackageName() string
	ServiceName() string
	MethodName() string
	MethodInfo() serviceinfo.MethodInfo
	StreamingMode() serviceinfo.StreamingMode
	SeqID() int32
	BizStatusErr() kerrors.BizStatusErrorIface
	Extra(key string) interface{}
}

Invocation contains specific information about the call.

func NewServerInvocation

func NewServerInvocation() Invocation

NewServerInvocation to get Invocation for new request in server side

type InvocationSetter

type InvocationSetter interface {
	SetPackageName(name string)
	SetServiceName(name string)
	SetMethodName(name string)
	SetMethodInfo(methodInfo serviceinfo.MethodInfo)
	SetStreamingMode(mode serviceinfo.StreamingMode)
	SetSeqID(seqID int32)
	SetBizStatusErr(err kerrors.BizStatusErrorIface)
	SetExtra(key string, value interface{})
	Reset()
}

InvocationSetter is used to set information about an RPC.

type MutableEndpointInfo

type MutableEndpointInfo interface {
	SetServiceName(service string) error
	SetMethod(method string) error
	SetAddress(addr net.Addr) error
	SetTag(key, value string) error
	ImmutableView() EndpointInfo
	Reset()
	ResetFromBasicInfo(bi *EndpointBasicInfo)
}

MutableEndpointInfo is used to change the information in the EndpointInfo.

func AsMutableEndpointInfo

func AsMutableEndpointInfo(ei EndpointInfo) MutableEndpointInfo

AsMutableEndpointInfo converts an EndpointInfo into a MutableEndpointInfo. Returns nil if impossible.

func NewMutableEndpointInfo

func NewMutableEndpointInfo(serviceName, method string, address net.Addr, tags map[string]string) MutableEndpointInfo

NewMutableEndpointInfo creates a new MutableEndpointInfo with the given information.

type MutableRPCConfig

type MutableRPCConfig interface {
	SetRPCTimeout(to time.Duration) error
	IsRPCTimeoutLocked() bool
	SetConnectTimeout(to time.Duration) error
	IsConnectTimeoutLocked() bool
	SetReadWriteTimeout(to time.Duration) error
	IsReadWriteTimeoutLocked() bool
	SetIOBufferSize(sz int) error
	SetTransportProtocol(tp transport.Protocol) error
	SetInteractionMode(mode InteractionMode) error
	LockConfig(bits int)
	Clone() MutableRPCConfig
	CopyFrom(from RPCConfig)
	ImmutableView() RPCConfig
	SetPayloadCodec(codec serviceinfo.PayloadCodec)

	SetStreamRecvTimeout(timeout time.Duration)
	SetStreamRecvTimeoutConfig(cfg streaming.TimeoutConfig)
}

MutableRPCConfig is used to change the information in the RPCConfig.

func AsMutableRPCConfig

func AsMutableRPCConfig(r RPCConfig) MutableRPCConfig

AsMutableRPCConfig .

type MutableRPCStats

type MutableRPCStats interface {
	SetSendSize(size uint64)
	SetRecvSize(size uint64)
	SetError(err error)
	SetPanicked(x interface{})
	SetLevel(level stats.Level)
	Reset()
	ImmutableView() RPCStats
	IncrSendSize(size uint64)
	IncrRecvSize(size uint64)
}

MutableRPCStats is used to change the information in the RPCStats.

func AsMutableRPCStats

func AsMutableRPCStats(r RPCStats) MutableRPCStats

AsMutableRPCStats converts an rpcStats into a MutableRPCStats. Returns nil if impossible.

type RPCConfig

type RPCConfig interface {
	Timeouts
	StreamConfig
	IOBufferSize() int
	TransportProtocol() transport.Protocol
	InteractionMode() InteractionMode
	PayloadCodec() serviceinfo.PayloadCodec
}

RPCConfig contains configuration for RPC.

func NewRPCConfig

func NewRPCConfig() RPCConfig

NewRPCConfig creates a default RPCConfig.

type RPCInfo

type RPCInfo interface {
	From() EndpointInfo
	To() EndpointInfo
	Invocation() Invocation
	Config() RPCConfig
	Stats() RPCStats
}

RPCInfo is the core abstraction of information about an RPC in Kitex.

func GetRPCInfo

func GetRPCInfo(ctx context.Context) RPCInfo

GetRPCInfo gets RPCInfo from ctx. Returns nil if not found.

func NewRPCInfo

func NewRPCInfo(from, to EndpointInfo, ink Invocation, config RPCConfig, stats RPCStats) RPCInfo

NewRPCInfo creates a new RPCInfo using the given information.

type RPCStats

type RPCStats interface {
	Record(ctx context.Context, event stats.Event, status stats.Status, info string)
	SendSize() uint64
	// LastSendSize returns the size of the last sent message in a stream.
	LastSendSize() uint64
	RecvSize() uint64
	// LastRecvSize returns the size of the last received message in a stream.
	LastRecvSize() uint64
	Error() error
	Panicked() (bool, interface{})
	GetEvent(event stats.Event) Event
	Level() stats.Level
	CopyForRetry() RPCStats
}

RPCStats is used to collect statistics about the RPC.

func NewRPCStats

func NewRPCStats() RPCStats

NewRPCStats creates a new RPCStats.

type ServerStreamEventHandler added in v0.16.0

type ServerStreamEventHandler struct {
	HandleStreamStartEvent  func(ctx context.Context, ri RPCInfo, evt StreamStartEvent)
	HandleStreamRecvEvent   func(ctx context.Context, ri RPCInfo, evt StreamRecvEvent)
	HandleStreamSendEvent   func(ctx context.Context, ri RPCInfo, evt StreamSendEvent)
	HandleStreamFinishEvent func(ctx context.Context, ri RPCInfo, evt StreamFinishEvent)
}

ServerStreamEventHandler defines a series handler for server-side detailed Streaming Event tracing.

type StreamConfig added in v0.12.0

type StreamConfig interface {
	StreamRecvTimeout() time.Duration
	StreamRecvTimeoutConfig() streaming.TimeoutConfig
}

type StreamEventReporter added in v0.9.0

type StreamEventReporter interface {
	// ReportStreamEvent is for collecting Recv/Send events on stream
	// NOTE: The callee should NOT hold references to event, which may be recycled later
	ReportStreamEvent(ctx context.Context, ri RPCInfo, event Event)
}

StreamEventReporter should be implemented by any tracer that wants to report stream events

type StreamFinishEvent added in v0.16.0

type StreamFinishEvent struct {
	GRPCTrailer     map[string][]string
	TTStreamTrailer map[string]string
}

StreamFinishEvent indicates the end of a stream. - When a gRPC Trailer Frame is received, GRPCTrailer is not nil. - When a TTHeader Streaming Trailer Frame is received, TTStreamTrailer is not nil. All other cases resulting in stream termination (e.g., rst) cause both GRPCTrailer and TTStreamTrailer to be nil.

type StreamRecvEvent added in v0.16.0

type StreamRecvEvent struct {
	Time time.Time
	Err  error
}

StreamRecvEvent corresponds to Stream.Recv. - Err is nil: Indicating a successful receive of a deserialized Msg. - Err is not nil: Indicating a failure in this receive operation.

type StreamRecvHeaderEvent added in v0.16.0

type StreamRecvHeaderEvent struct {
	GRPCHeader     map[string][]string
	TTStreamHeader map[string]string
}

StreamRecvHeaderEvent indicates the reception of a header frame sent by the peer. - When a gRPC header frame is received, GRPCHeader is not nil. - when a TTHeader Streaming header frame is received, TTStreamHeader is not nil.

type StreamSendEvent added in v0.16.0

type StreamSendEvent struct {
	Time time.Time
	Err  error
}

StreamSendEvent corresponds to Stream.Send. - Err is nil: indicating successful writing of the serialized Msg to the buffer. - Err is not nil: indicating that the Send operation failed.

type StreamStartEvent added in v0.16.0

type StreamStartEvent struct{}

StreamStartEvent marks the beginning of a stream. - client side: writing the Header Frame to the underlying connection. - server side, receiving the Header Frame and parses all RPC-related metadata.

type Taggable

type Taggable interface {
	SetTag(key, value string) error
}

Taggable is a type that supports setting tag.

func AsTaggable

func AsTaggable(i interface{}) Taggable

AsTaggable converts an object into a Taggable. Returns nil if impossible.

type TimeoutProvider added in v0.0.5

type TimeoutProvider interface {
	Timeouts(ri RPCInfo) Timeouts
}

TimeoutProvider provides timeout settings.

type Timeouts added in v0.0.5

type Timeouts interface {
	RPCTimeout() time.Duration
	ConnectTimeout() time.Duration
	ReadWriteTimeout() time.Duration
}

Timeouts contains settings of timeouts.

type TraceController added in v0.6.0

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

TraceController controls tracers.

func (*TraceController) Append added in v0.6.0

func (c *TraceController) Append(col stats.Tracer)

Append appends a new tracer to the controller.

func (*TraceController) AppendClientStreamEventHandler added in v0.16.0

func (c *TraceController) AppendClientStreamEventHandler(hdl ClientStreamEventHandler)

AppendClientStreamEventHandler appends a new ClientStreamEventHandler to the controller. nil handler would be ignored.

func (*TraceController) AppendServerStreamEventHandler added in v0.16.0

func (c *TraceController) AppendServerStreamEventHandler(hdl ServerStreamEventHandler)

AppendServerStreamEventHandler appends a new ServerStreamEventHandler to the controller. nil handler would be ignored.

func (*TraceController) DoFinish added in v0.6.0

func (c *TraceController) DoFinish(ctx context.Context, ri RPCInfo, err error)

DoFinish calls the tracers in reversed order.

func (*TraceController) DoStart added in v0.6.0

func (c *TraceController) DoStart(ctx context.Context, ri RPCInfo) context.Context

DoStart starts the tracers.

func (*TraceController) GetStreamEventHandler added in v0.9.0

func (c *TraceController) GetStreamEventHandler() stream.StreamEventHandler

GetStreamEventHandler returns the stream event handler If there's no StreamEventReporter, nil is returned for client/server to skip adding tracing middlewares Deprecated: there is no need to invoke GetStreamEventHandler anymore

func (*TraceController) HandleStreamFinishEvent added in v0.16.0

func (c *TraceController) HandleStreamFinishEvent(ctx context.Context, ri RPCInfo, evt StreamFinishEvent)

func (*TraceController) HandleStreamRecvEvent added in v0.16.0

func (c *TraceController) HandleStreamRecvEvent(ctx context.Context, ri RPCInfo, evt StreamRecvEvent)

func (*TraceController) HandleStreamRecvHeaderEvent added in v0.16.0

func (c *TraceController) HandleStreamRecvHeaderEvent(ctx context.Context, ri RPCInfo, evt StreamRecvHeaderEvent)

func (*TraceController) HandleStreamSendEvent added in v0.16.0

func (c *TraceController) HandleStreamSendEvent(ctx context.Context, ri RPCInfo, evt StreamSendEvent)

func (*TraceController) HandleStreamStartEvent added in v0.16.0

func (c *TraceController) HandleStreamStartEvent(ctx context.Context, ri RPCInfo, evt StreamStartEvent)

func (*TraceController) HasStreamEventReporter added in v0.9.0

func (c *TraceController) HasStreamEventReporter() bool

HasStreamEventReporter reports whether there exists any StreamEventReporter.

func (*TraceController) HasTracer added in v0.6.0

func (c *TraceController) HasTracer() bool

HasTracer reports whether there exists any tracer.

func (*TraceController) ReportStreamEvent added in v0.9.0

func (c *TraceController) ReportStreamEvent(ctx context.Context, statsEvent stats.Event, err error)

ReportStreamEvent is for collecting Recv/Send events on stream

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL