Documentation
¶
Overview ¶
Package plugintrace provides mechanisms to trace events in rpcplugin clients and servers, so that calling applications can record those events in their own application-specific logs or other trace mechanisms.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithClientTracer ¶
func WithClientTracer(ctx context.Context, tracer *ClientTracer) context.Context
WithClientTracer creates a child of the given context that has the given ClientTracer attached to it.
Callers must not modify any part of ClientTracer object after passing it to this function, or behavior is undefined.
func WithServerTracer ¶
func WithServerTracer(ctx context.Context, tracer *ServerTracer) context.Context
WithServerTracer creates a child of the given context that has the given ServerTracer attached to it.
Callers must not modify any part of ServerTracer object after passing it to this function, or behavior is undefined.
Types ¶
type ClientTracer ¶
type ClientTracer struct {
// ProcessStart is called just before the client launches the child process
// where the plugin server will run. The argument is the command definition
// it will use.
ProcessStart func(cmd *exec.Cmd)
// ProcessRunning is called after after the server process is started.
ProcessRunning func(proc *os.Process)
// ProcessStartFailed is called if the server process failed to start,
// giving the error value describing the failure.
ProcessStartFailed func(cmd *exec.Cmd, err error)
// ProcessExited is called when a server process terminates.
ProcessExited func(state *os.ProcessState)
// TLSConfig is called when client TLS configuration is complete. If and
// only if the auto-negotiation protocol was used to produce a single-use
// certificate, auto is true.
TLSConfig func(config *tls.Config, auto bool)
// ServerStarted is called once the server process has successfully
// completed the handshake protocol and is ready to be used.
ServerStarted func(proc *os.Process, addr net.Addr, protoVersion int)
// ServerStartTimeout is called if the server program doesn't complete
// the handshake before the configured timeout.
ServerStartTimeout func(proc *os.Process, timeout time.Duration)
// Connect is called just before the client opens a connection to the
// server's listen socket.
Connect func(addr net.Addr)
// Connected is called once a connection to the server's listen socket
// is successfully established.
Connected func(addr net.Addr)
// ConnectFailed is called if connecting to the server's listen socket
// returned an error.
ConnectFailed func(addr net.Addr, err error)
// Closing is called when a plugin instance is asked to shut down, before
// the child process is killed.
Closing func(proc *os.Process)
}
ClientTracer contains function pointers that, if set, will be called when certain events occur in a plugin client whose context has this object registered.
Some trace functions recieve mutable data structures via pointers for efficiency. Making any modifications to those data structures is forbidden, and these pointers must be discarded before each function returns.
func ClientLogTracer ¶
func ClientLogTracer(logger *log.Logger) *ClientTracer
ClientLogTracer constructs a ClientTracer that will emit human-oriented log entries into the given logger when trace events occur.
The format of these log entries is not customizable and may change in future versions. For more control, construct your own ClientTracer and build log messages yourself.
func ContextClientTracer ¶
func ContextClientTracer(ctx context.Context) *ClientTracer
ContextClientTracer retrieves the ClientTracer object associated with the given context. If none is associated, a no-op tracer is returned.
Do not modify any part of the returned tracer.
type ServerTracer ¶
type ServerTracer struct {
// TLSConfig is called when server TLS configuration is complete. If and
// only if the auto-negotiation protocol was used to produce a single-use
// certificate, auto is true.
TLSConfig func(config *tls.Config, auto bool)
// Listening is called once the server listener is configured, with the
// address where it is listening and other negotiated parameters.
Listening func(addr net.Addr, tlsConfig *tls.Config, protoVersion int)
// InterruptIgnored is called if the server is monitoring interrupt
// signals and such a signal is received. The count argument is how many
// interrupts have been received since the server started.
//
// If the ServerConfig has NoSignalHandlers set, this function will never
// be called.
InterruptIgnored func(count int)
// InvalidClientHandshakeVersion is called if the server finds an invalid
// version number in the supported proto version list while performing
// version negotiation. The given string is the invalid "number".
InvalidClientHandshakeVersion func(invalid string)
// VersionNegotationFailed is called if the server can find no proto
// versions in common with the client using the negotiation protocol.
// The argument is the set of version numbers the client supports.
VersionNegotationFailed func(clientVersions []int)
// GRPCServeError is called if the GRPC server exits with an error.
GRPCServeError func(error)
}
ServerTracer contains function pointers that, if set, will be called when certain events occur in a plugin server whose context has this object registered.
Some trace functions recieve mutable data structures via pointers for efficiency. Making any modifications to those data structures is forbidden.
func ContextServerTracer ¶
func ContextServerTracer(ctx context.Context) *ServerTracer
ContextServerTracer retrieves the ServerTracer object associated with the given context. If none is associated, a no-op tracer is returned.
Do not modify any part of the returned tracer.
func ServerLogTracer ¶
func ServerLogTracer(logger *log.Logger) *ServerTracer
ServerLogTracer constructs a ServerTracer that will emit human-oriented log entries into the given logger when trace events occur.
The format of these log entries is not customizable and may change in future versions. For more control, construct your own ServerTracer and build log messages yourself.
Source Files