inspect

package
v0.15.1 Latest Latest
Warning

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

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package inspect implements the proximo hop that sits in front of routes under Inspection: it proxies to the backend, injects the reporting agent into HTML responses, ingests what the agent sends back, and keeps the resulting Exchanges in memory. See docs/adr/0001-inspection-injects-into-the-response-path.md.

Index

Constants

View Source
const (
	// ReservedPath is the prefix proximo answers for on a project's own origin,
	// so an inspected page can report same-origin. It is unavailable to the
	// project for as long as the route carries the label.
	ReservedPath = "/.proximo/"

	// BackendHeader carries the address of the container this request is really
	// for. Traefik always overwrites it, so it cannot be forged from outside.
	BackendHeader = "X-Proximo-Backend"
)
View Source
const DefaultBudget = 64 << 20

DefaultBudget is how much memory the Store is allowed before it starts evicting the oldest Exchanges.

Variables

This section is empty.

Functions

func Agent

func Agent() ([]byte, error)

Agent returns the script the hop injects. It is proximo's own — there is no vendored bundle to build, pin or regenerate — so this is a plain read.

func DeriveID added in v0.15.0

func DeriveID(e Exchange) string

DeriveID is the identity of an Exchange Traefik logged. Traefik mints none, so it is derived from what makes the Exchange unique — host, instant, backend — rather than drawn at random: two CLI invocations must name the same Exchange the same way, which is the only property an agent needs to say "that one".

func DeriveIDParts added in v0.15.0

func DeriveIDParts(parts ...string) string

DeriveIDParts hashes the fields that make one thing unique into the short, stable id proximo names it by. It is shared rather than repeated: an Incident is identified the same way an Exchange is — derived from what it is, so the id survives the restart that discards the thing it names, and stays computable from what is on screen.

func NewID

func NewID() string

NewID mints the correlation id that joins the two halves of an Exchange.

Types

type AdminHandler

type AdminHandler struct{ Store *Store }

AdminHandler is the read side of the hop. It is deliberately a separate handler so it can be bound to a loopback-only listener: served on the request path it would let any inspected page read every Exchange recorded for its host.

func (AdminHandler) ServeHTTP

func (a AdminHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type Breadcrumb struct {
	At       time.Time `json:"at"`
	Category string    `json:"category"`
	Level    string    `json:"level"`
	Message  string    `json:"message"`
}

Breadcrumb is one thing the page did before a Client report: a console call, a request it made, a click, a navigation.

type Exchange

type Exchange struct {
	ID       string        `json:"id"`
	At       time.Time     `json:"at"`
	Host     string        `json:"host"`
	Method   string        `json:"method"`
	Path     string        `json:"path"`
	Status   int           `json:"status"`
	Duration time.Duration `json:"duration_ns"`
	Bytes    int64         `json:"bytes"`
	Warnings []string      `json:"warnings,omitempty"`
	Reports  []Report      `json:"reports,omitempty"`

	// Backend is the address — host:port — of the container this request was
	// served by, in the form Traefik's access log names a server by. It is what
	// a Transcript is looked up from, so an Access record without it can only be
	// joined to the wrong container's output, or to none.
	Backend string `json:"backend,omitempty"`

	// Suppressed counts the reports this Exchange saw beyond maxReports. They are
	// bounded, not discarded quietly: a page in a render loop must not be able to
	// evict every other Exchange, and a developer must still be told it happened.
	Suppressed int `json:"suppressed,omitempty"`

	// HasSnapshot tells a consumer of the JSON that `proximo errors dom` would
	// return something for this Exchange. Set by List.
	HasSnapshot bool `json:"has_snapshot"`

	// Snapshot is the page's DOM as it stood when the first Client report was
	// raised. It is never rendered inline, and never serialized with the rest:
	// the CLI asks for it separately and writes it to a file.
	Snapshot []byte `json:"-"`
}

Exchange is one request through an inspected route — the Access record — joined to the Client reports raised while the page it served was live.

func DecodeAccessLine added in v0.15.0

func DecodeAccessLine(line []byte) (Exchange, bool)

DecodeAccessLine reads one line of Traefik's stdout as an Access record. It reports false for anything that is not one: Traefik's operational log shares the stream, and only access lines are JSON carrying a request.

func Select added in v0.15.0

func Select(all []Exchange, host string, since time.Time, limit int, onlyProblems bool) []Exchange

Select narrows a listing of Exchanges, most recently active first. The Store and the CLI both need it — the CLI's listing is merged from two sources, so it cannot ask the Store to narrow it — and they must narrow it the same way, or the same flags mean two different things depending on where an Exchange came from.

The window and the order follow Activity, never the request instant: a page served ten minutes ago that threw a moment ago is fresher news than a request served since. Windowing by the instant would drop exactly the Client report this exists for, and ordering by it would sink that report below every clean request, where a limit cuts it first.

func (Exchange) Activity added in v0.15.0

func (e Exchange) Activity() time.Time

Activity is when something last happened on an Exchange. A page served ten minutes ago that threw just now is fresher news than a request served since, so ordering by the Exchange alone would sink it — and windowing by it alone would drop it.

func (Exchange) Interesting added in v0.15.0

func (e Exchange) Interesting() bool

Interesting reports whether an Exchange is worth a developer's attention: the browser reported something, proximo had to warn about something, or the stack itself answered with a failure.

type Frame

type Frame struct {
	File string `json:"file"`
	Line int    `json:"line"`
	Col  int    `json:"col,omitempty"`
	Func string `json:"func,omitempty"`
}

Frame is one entry of a Client report's stack trace.

type Handler

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

Handler is the hop itself: it proxies an inspected route to its backend, injects the reporting agent into HTML on the way back, and serves the reserved path. It is reachable from the browser, so it exposes nothing but the agent and the ingest endpoint — reading Exchanges back is AdminHandler's job, on a loopback-only listener.

func NewHandler

func NewHandler(store *Store, agent []byte) *Handler

NewHandler returns a hop recording into store and serving agent as the injected script.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Query

type Query struct {
	Host  string        // exact host match; empty matches any
	Since time.Duration // only Exchanges newer than this; zero means no bound
	Limit int           // most recent N; zero or less means no bound

	// OnlyProblems drops the Exchanges with nothing to say. It exists because
	// the alternative buries the one page that broke under every clean request
	// that did not, and the limit then cuts the interesting one first.
	OnlyProblems bool
}

Query narrows what List returns. The zero value holds nothing back.

type Report

type Report struct {
	At          time.Time    `json:"at"`
	Type        string       `json:"type"`
	Message     string       `json:"message"`
	Level       string       `json:"level"`
	Frames      []Frame      `json:"frames,omitempty"`
	Stack       string       `json:"stack,omitempty"` // as the browser formatted it
	Breadcrumbs []Breadcrumb `json:"breadcrumbs,omitempty"`
}

Report is one Client report: what the browser observed, with the Breadcrumbs that led up to it.

type Store

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

Store holds recent Exchanges in memory, bounded by total bytes rather than by count: one Exchange carrying a DOM Snapshot can outweigh a thousand without one. Nothing is written to disk — a Client report carries whatever the page held, and in development that is routinely real data.

func NewStore

func NewStore(budget int64) *Store

NewStore returns a Store bounded to budget bytes. A budget of zero or less uses DefaultBudget.

func (*Store) Add

func (s *Store) Add(e *Exchange)

Add records the server half of an Exchange, evicting the oldest entries until the Store is back inside its budget.

func (*Store) Attach

func (s *Store) Attach(id string, in ingested) bool

Attach adds a Client report — and, the first time one carries it, the DOM Snapshot — to the Exchange that served the page. It reports whether the id was known: an unknown id means the Exchange has already been evicted.

func (*Store) Complete

func (s *Store) Complete(id string, status int, took time.Duration, bytes int64, warnings []string)

Complete fills in the half of an Access record that is only known once the response has gone out. The Exchange was registered before that, so the page it served could already have reported against it.

func (*Store) List

func (s *Store) List(q Query) []Exchange

List returns the Exchanges matching q, most recently active first.

func (*Store) NoteRouteWarning

func (s *Store) NoteRouteWarning(host, msg string)

NoteRouteWarning records a warning against a host, ignoring one already held.

func (*Store) RouteWarnings

func (s *Store) RouteWarnings() map[string][]string

RouteWarnings returns the per-host warnings, for `proximo status`.

func (*Store) Snapshot

func (s *Store) Snapshot(id string) []byte

Snapshot returns the DOM captured for one Exchange, or nil when there is none.

func (*Store) Started

func (s *Store) Started() time.Time

Started reports when the Store came up, so an empty listing can say whether a restart is the reason.

Jump to

Keyboard shortcuts

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