Documentation
¶
Overview ¶
Package telemetry holds bastion's tracing helpers: the tracer, root spans for background work, error recording that never copies an error's text, and the client span every outbound HTTP call gets.
Index ¶
- Constants
- func Detach(ctx context.Context) context.Context
- func EndClient(span trace.Span, resp *http.Response, err error, stream bool) *http.Response
- func ErrorType(err error) string
- func Fail(span trace.Span, class string, err error)
- func RecordRoundTripError(span trace.Span, err error)
- func RecordStatus(span trace.Span, status int)
- func RequestAttributes(req *http.Request) []attribute.KeyValue
- func Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- func StartClient(req *http.Request, name string, opts ...trace.SpanStartOption) (*http.Request, trace.Span)
- func StartRoot(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- func Tracer() trace.Tracer
- func URLAttributes(method string, u *url.URL) []attribute.KeyValue
- type Transport
Constants ¶
const ScopeName = "github.com/xraph/bastion"
ScopeName is the instrumentation scope of every span bastion starts.
Variables ¶
This section is empty.
Functions ¶
func Detach ¶
Detach returns ctx without its span, keeping its values and cancellation. A loop or goroutine that outlives the code that started it makes its ctx with Detach first. context.WithCancel, WithoutCancel and WithTimeout all keep the parent's span, so without it every call the loop makes before its own root span exists (and every query grove traces) would land under a span that ended long ago: Forge's boot span for anything started in Start, the server span for anything a request handler started.
func EndClient ¶
EndClient records how the round trip ended on span, the span StartClient returned. A failed round trip, a stream (stream true) and a response with no body to read end the span now. Otherwise resp comes back with its body wrapped, and the span ends once the body is read to the end or closed, so it covers the whole response.
A 5xx marks the span failed. A 4xx doesn't: it is the upstream's answer to the client, which the gateway passes on. A client that went away first is not a failure either; the span gets bastion.canceled instead.
func ErrorType ¶
ErrorType returns the Go type of the innermost error in err's chain, such as "*net.OpError" or "syscall.Errno". A joined error reports its own type.
func Fail ¶
Fail marks span as failed. class is a short fixed description of what went wrong. err adds an exception event carrying only its Go type: error text from drivers and libraries quotes URLs, hosts and values, so it is never recorded.
func RecordRoundTripError ¶
RecordRoundTripError records a round trip that got no response. A client that went away first only sets bastion.canceled; anything else sets error.type to the error's Go type and marks the span failed.
func RecordStatus ¶
RecordStatus records the response status on a client span. A 5xx marks the span failed; anything below is the upstream's answer.
func RequestAttributes ¶
RequestAttributes returns the attributes a client span records for req.
func Start ¶
func Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
Start starts a span as a child of whatever span ctx carries.
func StartClient ¶
func StartClient(req *http.Request, name string, opts ...trace.SpanStartOption) (*http.Request, trace.Span)
StartClient starts a Client span named name as a child of req's context and returns a clone of req that carries the span and its trace headers. Pair it with EndClient.
The span records the method, the scheme and the upstream's host and port. It leaves out the URL's path and query and every header: for a gateway those are the client's request, and they carry IDs, emails and tokens. That is also why bastion doesn't use otelhttp, which records the full URL and copies transport error text into the span status.
When the span isn't part of any trace (tracing off and no incoming trace context), req is returned unchanged.
func StartRoot ¶
func StartRoot(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
StartRoot starts the span for one unit of background work as the root of a new trace. Background loops run on the context Start was given, which carries Forge's boot span, and their spans must not hang off it.
Types ¶
type Transport ¶
type Transport struct {
// Base sends the request. Nil means http.DefaultTransport.
Base http.RoundTripper
// Name is the span name, such as "fetch farp manifest".
Name string
}
Transport gives every request a Client span named Name and sends the trace context with it. Bastion's background fetches (FARP manifests, OpenAPI and AsyncAPI specs, JWKS, forward auth) go through it.
func NewTransport ¶
func NewTransport(base http.RoundTripper, name string) *Transport
NewTransport wraps base, nil meaning http.DefaultTransport, in a Transport whose spans are called name.
func (*Transport) CloseIdleConnections ¶
func (t *Transport) CloseIdleConnections()
CloseIdleConnections closes the base transport's idle connections, so http.Client.CloseIdleConnections still reaches it.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package telemetrytest records bastion's spans and scrapes its metrics in tests.
|
Package telemetrytest records bastion's spans and scrapes its metrics in tests. |