tracer

Documentation

Index

• Constants
• func GetDecompressor(encoding string) connect.Decompressor
• func TracingHTTP2Conn(conn net.Conn, isServer bool, collector Collector) net.Conn
• func TracingHTTP2Listener(listener net.Listener, collector Collector) net.Listener
• func TracingHandler(handler http.Handler, collector Collector) http.Handler
• func TracingRoundTripper(transport http.RoundTripper, collector Collector) http.RoundTripper
• type Collector
• type Envelope
• type Event
• type RequestBodyData
• type RequestBodyEnd
• type RequestCanceled
• type RequestStart
• type ResponseBodyData
• type ResponseBodyEnd
• type ResponseBodyEndStream
• type ResponseError
• type ResponseStart
• type Trace
  • func (t *Trace) Print(printer internal.Printer)
• type Tracer
  • func (t *Tracer) Await(ctx context.Context, testName string) (*Trace, error)
  • func (t *Tracer) Clear(testName string)
  • func (t *Tracer) Complete(trace Trace)
  • func (t *Tracer) Init(testName string)

Constants

const (
	// TraceTimeout is the delay that a consumer should be willing to wait
	// for a trace, since they are produced asynchronously.
	TraceTimeout = 5 * time.Second
)

Functions

func GetDecompressor

func GetDecompressor(encoding string) connect.Decompressor

GetDecompressor returns a decompressor that can handle the given encoding.

func TracingHTTP2Conn

func TracingHTTP2Conn(conn net.Conn, isServer bool, collector Collector) net.Conn

TracingHTTP2Conn applies tracing to the given net.Conn, which uses the HTTP/2 protocol. If TLS is used, it should already be applied, so the given conn should be used for reading/writing clear-text (i.e. pre-encryption, post-decryption).

If isServer is true, this is a server connection, so requests are read and responses are written. Otherwise, this is a client connection, and requests are written and responses are read.

func TracingHTTP2Listener

func TracingHTTP2Listener(listener net.Listener, collector Collector) net.Listener

TracingHTTP2Listener applies tracing to the given net.Listener, which accepts sockets that use the HTTP/2 protocol. If TLS is used, it should already be applied, so the given listener should return connections that can be used for reading/writing clear-text (i.e. pre-encryption, post-decryption).

This function calls TracingHTTP2Conn for each connection accepted. All connections accepted are considered server connections.

func TracingHandler

func TracingHandler(handler http.Handler, collector Collector) http.Handler

TracingHandler applies tracing middleware to the given handler. The returned handler will record traces of all operations to the given tracer.

func TracingRoundTripper

func TracingRoundTripper(transport http.RoundTripper, collector Collector) http.RoundTripper

TracingRoundTripper applies tracing to the given transport. The returned round tripper will record traces of all operations to the given tracer.

Types

type Collector

type Collector interface {
	// Complete accepts a trace once it is completed.
	Complete(Trace)
}

Collector is a consumer of traces. This is usually an instance of *Tracer, but is an interface so that the implementation can vary, even allowing decorating or intercepting the method on *Tracer.

type Envelope

type Envelope struct {
	Flags byte
	Len   uint32
}

Envelope represents the metadata about an enveloped message in an RPC stream. Streaming protocols prefix each message with this metadata.

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event is a single item in a sequence of activity for an HTTP operation.

type RequestBodyData

type RequestBodyData struct {
	// For streaming protocols, each message is
	// enveloped and this should be non-nil. It may
	// be nil in a streaming protocol if an envelope
	// prefix was expected, but only a partial prefix
	// could be written/read. In such a case, a
	// RequestBodyData event is emitted that has no
	// envelope and whose Len field indicates the
	// number of bytes written/read of the incomplete
	// prefix.
	Envelope *Envelope
	// Actual length of the data, which could differ
	// from the length indicated in the envelope if
	// the full message could not be written/read.
	Len uint64

	// Sequentially numbered index. The first message
	// in the stream should have an index of zero, and
	// then one, etc.
	MessageIndex int
	// contains filtered or unexported fields
}

RequestBodyData represents some data written to or read from the request body. These operations are "chunked" so that a single event represents a full message (or incomplete, partial message if a full message is not written or read).

type RequestBodyEnd

type RequestBodyEnd struct {
	Err error
	// contains filtered or unexported fields
}

RequestBodyEnd represents the end of the request body being reached. The Err value is the error returned from the final read (on the server) or call to close the body (on the client). If the final read returned io.EOF, Err will be nil. So a non-nil Err means an abnormal conclusion to the operation. No more request events will appear after this.

type RequestCanceled

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

RequestCanceled represents the instant the request is cancelled by the client. No more events will appear after this.

type RequestStart

type RequestStart struct {
	Request *http.Request
	// contains filtered or unexported fields
}

RequestStart is an event that represents when the request starts. This is recorded when the client sends the request or when the server receives it. This is always the first event for an HTTP operation.

type ResponseBodyData

type ResponseBodyData struct {
	// For streaming protocols, each message is
	// enveloped and this should be non-nil. It may
	// be nil in a streaming protocol if an envelope
	// prefix was expected, but only a partial prefix
	// could be written/read. In such a case, a
	// ResponseBodyData event is emitted that has no
	// envelope and whose Len field indicates the
	// number of bytes written/read of the incomplete
	// prefix.
	Envelope *Envelope
	// Actual length of the data, which could differ
	// from the length indicated in the envelope if
	// the full message could not be written/read.
	Len uint64

	// Sequentially numbered index. The first message
	// in the stream should have an index of zero, and
	// then one, etc.
	MessageIndex int
	// contains filtered or unexported fields
}

ResponseBodyData represents some data written to or read from the response body. These operations are "chunked" so that a single event represents a full message (or incomplete, partial message if a full message is not written or read).

type ResponseBodyEnd

type ResponseBodyEnd struct {
	Err error
	// contains filtered or unexported fields
}

ResponseBodyEnd represents the end of the response body being reached. The Err value is the error returned from the final read (on the client) or final write (on the server). If the final read returned io.EOF, Err will be nil. So a non-nil Err means an abnormal conclusion to the operation. No more events will appear after this.

type ResponseBodyEndStream

type ResponseBodyEndStream struct {
	Content string
	// contains filtered or unexported fields
}

ResponseBodyEndStream represents the an "end-stream" message in the Connect streaming and gRPC-Web protocols. It is a special representation of the operation's status and trailers that is part of the response body.

type ResponseError

type ResponseError struct {
	Err error
	// contains filtered or unexported fields
}

ResponseError is an event that represents when the response fails. This is recorded when the client receives an error instead of a response, like due to a network error. No more events will appear after this.

type ResponseStart

type ResponseStart struct {
	Response *http.Response
	// contains filtered or unexported fields
}

ResponseStart is an event that represents when the response starts. This is recorded when the client receives the response headers or when the server sends them. This will precede all other response events.

type Trace

type Trace struct {
	TestName string
	Request  *http.Request
	Response *http.Response
	Err      error
	Events   []Event
}

Trace represents the sequence of activity for a single HTTP operation.

func (*Trace) Print

func (t *Trace) Print(printer internal.Printer)

type Tracer

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

Tracer stores traces as they are produced and makes them available to a consumer. Each operation, identified by a test name, must first be initialized by the consumer via Init. The producer then populates the information for that operation via Complete. The consumer can then use Await to retrieve the trace (which may be produced asynchronously) and should finally use Clear, to free up resources associated with the operation. (If Clear is never called, the Tracer will use more and more memory, but limited by the amount to store all traces for every operation traced.)

func (*Tracer) Await

func (t *Tracer) Await(ctx context.Context, testName string) (*Trace, error)

Await waits for the given test to complete and for its trace data to become available. It returns a context error if the given context is cancelled or its deadline is reached before completion. It also returns an error if Clear has alreadu been called for the test or if Init was never called.

func (*Tracer) Clear

func (t *Tracer) Clear(testName string)

Clear clears the data for the given test name. This frees up resources so that the tracer doesn't use more memory than necessary.

func (*Tracer) Complete

func (t *Tracer) Complete(trace Trace)

Complete marks a test as complete with the given trace data. If Clear has already been called or Init was never called, this does nothing.

func (*Tracer) Init

func (t *Tracer) Init(testName string)

Init initializes the tracer to accept data for a trace for the given test name. This must be called before Clear, Complete, or Await for the same name.