observe

type APITracer struct{}

type Check struct {
	Name  string
	Probe func(ctx context.Context) error
}

type CheckResult struct {
	Name string `json:"name"`
	OK   bool   `json:"ok"`
	// Detail is the error's text when OK is false, and empty otherwise.
	Detail string `json:"detail,omitempty"`
	// Millis is how long the probe took, which is most of what distinguishes a
	// dependency that is there from one that is barely there.
	Millis int64 `json:"ms"`
}

type Config struct {
	// ServiceName is what this application is called in a collector. The
	// generated Tracing() passes the API's name from rig.yaml, so nothing has
	// to be typed twice.
	ServiceName string

	// ServiceVersion is the build, if it knows. Empty leaves the attribute off
	// rather than sending "unknown", which sorts and groups as a version.
	ServiceVersion string

	// Endpoint is an OTLP/HTTP collector, for example
	// "http://localhost:4318". Empty falls back to $OTEL_EXPORTER_OTLP_ENDPOINT
	// and, failing that, to exporting nothing at all.
	//
	// Nothing is the ordinary case rather than the broken one. An exporter
	// pointed at a host that was never there retries, and the retry comes due
	// during shutdown — so the failure mode of getting this wrong is a slow
	// exit in exactly the environments nobody is watching.
	Endpoint string

	// File is a path to write finished spans to, one JSON object per line.
	// Empty falls back to $RIG_TRACE_FILE and then to writing none.
	//
	// It is the small deployment's answer to a collector it is not going to
	// run: the file survives a restart, which is when you most want to know
	// what the last few requests were doing, and it is the store rig's own
	// monitoring page reads.
	File string

	// FileMaxBytes is where File rotates, keeping one previous generation.
	// Zero means [DefaultFileMaxBytes]. An append-only file with no ceiling is
	// the thing that fills a disk at three in the morning.
	FileMaxBytes int64

	// SampleRatio is the fraction of traces recorded, between 0 and 1. Zero
	// means one — every trace — because zero is what a field nobody set holds,
	// and a project that wants no traces leaves Endpoint and File empty
	// instead.
	//
	// A trace started elsewhere is honoured rather than re-decided: the sampler
	// is parent-based, so a request that arrives already sampled is recorded
	// whatever this says.
	SampleRatio float64
}

type LogConfig struct {
	// File is the path to append log lines to, one JSON object per line. Empty
	// falls back to $RIG_LOG_FILE and then to writing none, which is the
	// ordinary case rather than the broken one.
	File string

	// FileMaxBytes is where File rotates, keeping one previous generation. Zero
	// means [DefaultFileMaxBytes]. An append-only file with no ceiling is the
	// thing that fills a disk at three in the morning.
	FileMaxBytes int64

	// Level is what the *file* keeps, and nil means [log/slog.LevelDebug].
	//
	// Its own level, and not the application logger's, is the point. rig's
	// request line and its refusal line are at debug — logging a 404 at error
	// is how a log becomes a thing nobody reads — so a deployment running at
	// info writes them nowhere and nobody ever sees them. The file keeps them
	// and stderr does not, which is the whole reason the monitoring page has a
	// request to list at all.
	//
	// A [log/slog.Leveler] rather than a Level because Level's zero value is
	// LevelInfo, and a field whose zero meant debug would be a lie.
	Level slog.Leveler
}

type LogRecord struct {
	Time  time.Time `json:"time"`
	Level string    `json:"level"`
	Msg   string    `json:"msg"`

	// TraceID and SpanID are the trace this line was written inside, taken from
	// the context the log call was given. Empty for a line written outside a
	// request, or by a process that is not tracing.
	//
	// This is what makes a log line and a request the same view on the
	// monitoring page, and it is why every log call in rig passes the context:
	// slog hands the context to the handler, and a bare Info would arrive here
	// with nothing to find.
	TraceID string `json:"trace_id,omitempty"`
	SpanID  string `json:"span_id,omitempty"`

	// Attrs is everything else the line carried, nested rather than flattened
	// into the object above: a line is free to have an attribute called "level"
	// or "msg", and a flat record would let it overwrite one. A slog group is a
	// map here, so the generated server's slog.Any("request", rc) arrives as
	// attrs.request.route and attrs.request.request_id.
	Attrs map[string]any `json:"attrs,omitempty"`
}

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

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

type PageConfig struct {
	// ServiceName is what the page calls this application, and it comes from
	// project.name in rig.yaml.
	ServiceName string

	// Addr is where the page listens, as host:port — "127.0.0.1:9090", or
	// ":9090" for every interface. $RIG_MONITOR_ADDR overrides it; see
	// [AddrEnv].
	//
	// The page gets a listener of its own rather than a route on the API's mux,
	// and this is the whole reason: [PageConfig.Allow] is matched against the
	// connection's own address, so behind a load balancer it matches everything
	// or nothing, and the only boundary left that a client cannot talk its way
	// around is which interface the socket is bound to. Loopback is a boundary
	// the kernel keeps.
	//
	// Empty is not defaulted. Nothing here knows what port is free on the
	// machine this runs on, and a page reachable from an interface nobody chose
	// is the failure this field exists to prevent — so an empty one is a page
	// that does not listen, the same as a missing password, and [Page.Unarmed]
	// says which.
	//
	// Serving it is [Page.Handler] and the application's own server; this
	// package opens no listeners.
	Addr string

	// BasePath is where the page is mounted on that listener. Empty means
	// [DefaultMonitorPath]. It must be absolute and must not end in a slash.
	//
	// Nothing else is on the listener to collide with. It is kept because it is
	// the URL projects already have, and because a reverse proxy in front of
	// [PageConfig.Addr] needs a prefix to key on.
	BasePath string

	// MaxTraces is how many requests the page lists, newest first. Zero means
	// [DefaultMaxTraces].
	MaxTraces int

	// MaxLogs is how many log lines the page reads, newest first. Zero means
	// [DefaultMaxLogs].
	MaxLogs int

	// Logs is the log file this process is writing, and nil is a page with no
	// log half — which is what a project that never wired one gets, and it says
	// so rather than showing an empty list.
	//
	// It is the sink itself and not a path, for the reason the span file is not
	// a field here either: the page and the writer agreeing on a file should not
	// be something a main arranges twice. Open it with [OpenLogs], tee
	// [Logs.Handler] into the logger the application already has, and set the
	// same object here.
	//
	// It is not in rig.yaml and cannot be, because it is an object rather than a
	// value. A generated Monitoring() therefore leaves it empty — but a
	// generated NewProcess() fills it, because that constructor is where the
	// sink is opened. A main that builds its own page is the caller that still
	// sets this by hand.
	Logs *Logs

	// Password is a literal from rig.yaml, for a project that wants the page
	// working without an environment to set. Empty — the ordinary case — falls
	// back to PasswordEnv.
	Password string

	// PasswordEnv names the variable the password is read from. Empty means
	// [PasswordEnv].
	PasswordEnv string

	// Allow is the addresses that may reach the page, as CIDR ranges or single
	// addresses — "10.0.0.0/8", "127.0.0.1", "::1". Empty, the default, allows
	// any address and leaves the password as the only check.
	//
	// It narrows; it does not replace. An address that is not on the list is
	// answered 404 before the password is looked at, so a scan learns nothing
	// and a leaked password is still not enough on its own.
	//
	// It is matched against the connection's own address and never against a
	// forwarded header, for the reason auth.trusted_proxies exists: an address
	// read from a header a client controls is an address a client chooses, and
	// an allowlist keyed on one is an allowlist anybody walks around.
	//
	// The cost of that choice is worth knowing before you rely on this: behind
	// a load balancer every request arrives from the balancer, so the list
	// matches everything or nothing and is no boundary at all. There,
	// [PageConfig.Addr] is the boundary — bind the page somewhere the balancer
	// is not — and this list is what narrows the addresses on that network.
	Allow []string

	// Checks are the dependencies the page shows the state of, beside the
	// requests and the logs.
	//
	// The page holds the probe rather than a state somebody pushed to it, which
	// is what makes it answer the question actually being asked — "is the
	// database there now" — rather than "was it there when something last
	// happened to touch it". A dependency that comes back is visible on the next
	// poll without any traffic having to discover it first.
	//
	// It is not in rig.yaml and cannot be: a probe is a function. A generated
	// Monitoring() therefore leaves this empty, and the wiring that has the pool
	// and the sync proxy calls [Page.Watch].
	Checks []Check

	// CheckTimeout bounds one round of Checks, all of them together. Zero means
	// [DefaultCheckTimeout].
	CheckTimeout time.Duration
}

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

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

type SpanRecord struct {
	// Time is when the span ended, which is when the line was written and so
	// the order the file is in.
	Time time.Time `json:"time"`

	TraceID string `json:"trace_id"`
	SpanID  string `json:"span_id"`
	// ParentID is empty for the root of a trace — the request span, usually.
	ParentID string `json:"parent_id,omitempty"`

	Name string `json:"name"`
	Kind string `json:"kind"`

	Start time.Time `json:"start"`
	// DurationMS is milliseconds, as a float, because the interesting spans
	// here are shorter than one and an integer would round most of them to
	// zero.
	DurationMS float64 `json:"duration_ms"`

	// Status is "error" or absent. A span that succeeded says nothing, which is
	// what makes `grep '"status":"error"'` the first thing to try.
	Status string `json:"status,omitempty"`
	// Error is the status description — for rig's spans, the error that caused
	// the failure.
	Error string `json:"error,omitempty"`

	Service    string         `json:"service,omitempty"`
	Attributes map[string]any `json:"attributes,omitempty"`
}

type TraceRecord struct {
	// ID is the trace id every span in it carries — the same string the
	// generated server puts in an error body as requestId, so an identifier
	// from somebody's screenshot is a search on this field.
	ID string `json:"id"`

	// Root is the span with no parent, usually the request. It is nil for a
	// trace whose beginning has been rotated away, or one still in flight when
	// the file was read; the rest of the trace is still worth showing, which is
	// why this is a pointer and not an assumption.
	Root *SpanRecord `json:"root,omitempty"`

	// Spans is every record in the trace, in start order. Nesting is not a
	// field: each record carries [SpanRecord.ParentID] and rebuilding the tree
	// from that is the reader's business, which for rig is the page.
	Spans []SpanRecord `json:"spans"`

	// Start is the earliest start in the trace and End the latest end, so the
	// duration covers the whole of it even when the root is missing.
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
	// DurationMS is End minus Start, in milliseconds. Not the root's own
	// duration: a trace missing its root would otherwise be zero.
	DurationMS float64 `json:"duration_ms"`

	// Status is "error" when any span in the trace failed, and absent
	// otherwise — the same convention [SpanRecord.Status] uses, so the page
	// filters both with one test.
	Status string `json:"status,omitempty"`
	// Name is the root's name, which for a request is its route. Empty when
	// there is no root.
	Name string `json:"name,omitempty"`
	// Service is who wrote the trace, from the first span that says.
	Service string `json:"service,omitempty"`
}