telemetry

package
v1.4.2 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
const ScopeName = "github.com/xraph/bastion"

ScopeName is the instrumentation scope of every span bastion starts.

Variables

This section is empty.

Functions

func Detach

func Detach(ctx context.Context) context.Context

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

func EndClient(span trace.Span, resp *http.Response, err error, stream bool) *http.Response

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

func ErrorType(err error) string

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

func Fail(span trace.Span, class string, err error)

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

func RecordRoundTripError(span trace.Span, err error)

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

func RecordStatus(span trace.Span, status int)

RecordStatus records the response status on a client span. A 5xx marks the span failed; anything below is the upstream's answer.

func RequestAttributes

func RequestAttributes(req *http.Request) []attribute.KeyValue

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.

func Tracer

func Tracer() trace.Tracer

Tracer returns bastion's tracer from the global provider. It is looked up on each call, so a provider installed later (forge.New installs one, and tests swap them) is the one used.

func URLAttributes

func URLAttributes(method string, u *url.URL) []attribute.KeyValue

URLAttributes returns the attributes a client span records for a request with method to u: the method, the scheme, and u's host and port. u's path and query are left out.

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.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

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.

Jump to

Keyboard shortcuts

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