trcweb

Documentation

Overview

Package trcweb provides an HTTP interface to traces.

Index

• Constants
• func Categorize(r *http.Request) string
• func Middleware(constructor func(context.Context, string) (context.Context, trc.Trace), ...) func(http.Handler) http.Handler
• func SetSourceLinkFunc(f SourceLinkFunc)
• func SourceLinkVSCode(fileline string) template.URL
• type HTTPClient
• type SearchClient
  • func NewSearchClient(client HTTPClient, uri string) *SearchClient
  • func (c *SearchClient) Search(ctx context.Context, req *trc.SearchRequest) (_ *trc.SearchResponse, err error)
• type SearchData
• type Searcher
• type SourceLinkFunc
• type StreamClient
  • func NewStreamClient(uri string) *StreamClient
  • func (c *StreamClient) Stream(ctx context.Context, f trc.Filter, ch chan<- trc.Trace) (err error)
• type Streamer
• type TraceServer
  • func NewTraceServer(c *trc.Collector) *TraceServer
  • func (s *TraceServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

Constants

const AssetsDirEnvKey = "TRC_ASSETS_DIR"

AssetsDirEnvKey can be set to a local path for the assets directory, in which case those files will be used when rendering assets, instead of the embedded assets. This is especially useful when developing.

Functions

func Categorize

func Categorize(r *http.Request) string

Categorize the request for a Middleware.

func Middleware

func Middleware(
	constructor func(context.Context, string) (context.Context, trc.Trace),
	categorize func(*http.Request) string,
) func(http.Handler) http.Handler

Middleware decorates an HTTP handler by creating a trace for each request via the constructor function. The trace category is determined by the categorize function. Basic metadata, such as method, path, duration, and response code, is recorded in the trace.

This is meant as a convenience for simple use cases. Users who want different or more sophisticated behavior should implement their own middlewares.

func SetSourceLinkFunc

func SetSourceLinkFunc(f SourceLinkFunc)

SetSourceLinkFunc sets the function used to produce clickable links to source code in stack traces. By default links are not clickable.

func SourceLinkVSCode

func SourceLinkVSCode(fileline string) template.URL

SourceLinkVSCode produces links that open in VS Code.

Types

type HTTPClient

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient models an http.Client.

type SearchClient

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

SearchClient implements trc.Searcher by querying a search server.

func NewSearchClient

func NewSearchClient(client HTTPClient, uri string) *SearchClient

NewSearchClient returns a search client using the given HTTP client to query the given search server URI.

func (*SearchClient) Search

func (c *SearchClient) Search(ctx context.Context, req *trc.SearchRequest) (_ *trc.SearchResponse, err error)

Search implements trc.Searcher.

type SearchData

type SearchData struct {
	Request  trc.SearchRequest  `json:"request"`
	Response trc.SearchResponse `json:"response"`
	Problems []error            `json:"-"` // for rendering, not transmitting
}

SearchData is returned by normal trace search requests.

type Searcher

type Searcher trc.Searcher

Searcher is just a trc.Searcher.

type SourceLinkFunc

type SourceLinkFunc func(fileline string) template.URL

SourceLinkFunc converts a local source code file and line to a URL that can be opened by a browser.

type StreamClient

type StreamClient struct {
	// HTTPClient used to make the stream request. Optional.
	HTTPClient HTTPClient

	// URI of the remote stream server. Required.
	URI string

	// SendBuffer used by the remote stream server. Min 0, max 100k.
	SendBuffer int

	// OnRead is called for every stream event received by the client.
	// Implementations must not block.
	OnRead func(ctx context.Context, eventType string, eventData []byte)

	// RetryInterval between reconnect attempts. Default 3s, min 1s, max 60s.
	RetryInterval time.Duration

	// StatsInterval for stream stats updates. Default 10s, min 1s, max 60s.
	StatsInterval time.Duration
}

StreamClient streams trace data from a server.

func NewStreamClient

func NewStreamClient(uri string) *StreamClient

NewStreamClient constructs a stream client connecting to the provided URI.

func (*StreamClient) Stream

func (c *StreamClient) Stream(ctx context.Context, f trc.Filter, ch chan<- trc.Trace) (err error)

Stream trace data from the remote server, filtered by the provided filter, to the provided channel. The stream stops when the context is canceled, or a non-recoverable error occurs.

type Streamer

type Streamer interface {
	Stream(ctx context.Context, f trc.Filter, ch chan<- trc.Trace) (trc.StreamStats, error)
	StreamStats(ctx context.Context, ch chan<- trc.Trace) (trc.StreamStats, error)
}

Streamer models the subscriber methods of a trc.Collector.

type TraceServer

type TraceServer struct {
	// Collector is the default implementation for Searcher and Streamer.
	Collector *trc.Collector

	// Searcher is used to serve requests which Accept: text/html and/or
	// application/json. If not provided, the Collector will be used.
	Searcher Searcher

	// Streamer is used to serve requests which Accept: text/event-stream. If
	// not provided, the Collector will be used.
	Streamer Streamer
}

TraceServer provides an HTTP interface to a trace collector.

func NewTraceServer

func NewTraceServer(c *trc.Collector) *TraceServer

NewTraceServer returns a standard trace server wrapping the collector.

func (*TraceServer) ServeHTTP

func (s *TraceServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.