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
- func Agent() ([]byte, error)
- func DeriveID(e Exchange) string
- func DeriveIDParts(parts ...string) string
- func NewID() string
- type AdminHandler
- type Breadcrumb
- type Exchange
- type Frame
- type Handler
- type Query
- type Report
- type Store
- func (s *Store) Add(e *Exchange)
- func (s *Store) Attach(id string, in ingested) bool
- func (s *Store) Complete(id string, status int, took time.Duration, bytes int64, warnings []string)
- func (s *Store) List(q Query) []Exchange
- func (s *Store) NoteRouteWarning(host, msg string)
- func (s *Store) RouteWarnings() map[string][]string
- func (s *Store) Snapshot(id string) []byte
- func (s *Store) Started() time.Time
Constants ¶
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" )
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 ¶
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
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
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.
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 ¶
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"`
// Peer marks an Exchange that arrived on a peer name — a colleague's
// browser asked. Set by the CLI, which knows the Peer suffix; the hop never does.
// An agent reading the JSON knows neither the TLD nor the suffix, so it
// could not classify Host without a second command.
Peer bool `json:"peer,omitempty"`
// 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
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
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
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
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 ¶
NewHandler returns a hop recording into store and serving agent as the injected script.
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 ¶
NewStore returns a Store bounded to budget bytes. A budget of zero or less uses DefaultBudget.
func (*Store) Add ¶
Add records the server half of an Exchange, evicting the oldest entries until the Store is back inside its budget.
func (*Store) Attach ¶
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 ¶
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) NoteRouteWarning ¶
NoteRouteWarning records a warning against a host, ignoring one already held.
func (*Store) RouteWarnings ¶
RouteWarnings returns the per-host warnings, for `proximo status`.