model

type Attributes map[string]any

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

type HTTPInfo struct {
	Method        string `json:"method"`
	URI           string `json:"uri"`
	Route         string `json:"route,omitempty"`
	Host          string `json:"host"`
	Protocol      string `json:"protocol"`
	RemoteAddress string `json:"remote_address"`
	UserAgent     string `json:"user_agent,omitempty"`
	Status        int    `json:"status,omitempty"`
	ResponseBytes int64  `json:"response_bytes"`
}

type HostStat struct {
	Host string `json:"host"`

	// Requests counts every request the host was seen in, sampled or not, for
	// the lifetime of the process.
	Requests uint64 `json:"requests"`

	// Traces counts the traces of this host retained in the rolling window.
	Traces uint64 `json:"traces"`

	Errors          uint64        `json:"errors"`
	Share           float64       `json:"share_percent"`
	Routes          int           `json:"routes"`
	AverageDuration time.Duration `json:"average_duration_ns"`
	MaxDuration     time.Duration `json:"max_duration_ns"`
	Spans           uint64        `json:"spans"`
	// contains filtered or unexported fields
}

type Kind string

type LogEntry struct {
	Time    time.Time `json:"time"`
	Level   string    `json:"level"`
	Message string    `json:"message"`
	SpanID  int       `json:"span_id,omitempty"`

	// RequestID is the ID of the trace the entry was recorded on, the value
	// the Request-Id header carries. Every entry of a trace shares it, and it
	// keeps an entry attributable once the log is read apart from its trace.
	RequestID string `json:"request_id,omitempty"`

	// Attributes carry the slog-style key/value arguments of the call. The
	// message is stored verbatim, never formatted.
	Attributes Attributes `json:"attributes,omitempty"`
}

type Memory struct {
	HeapAlloc     uint64  `json:"heap_alloc_bytes"`
	HeapInuse     uint64  `json:"heap_inuse_bytes"`
	HeapObjects   uint64  `json:"heap_objects"`
	StackInuse    uint64  `json:"stack_inuse_bytes"`
	System        uint64  `json:"system_bytes"`
	NextGC        uint64  `json:"next_gc_bytes"`
	NumGC         uint32  `json:"gc_cycles"`
	GCPauseTotal  uint64  `json:"gc_pause_total_ns"`
	GCCPUFraction float64 `json:"gc_cpu_fraction"`
	Limit         uint64  `json:"memory_limit_bytes,omitempty"`
}

type MemoryUse struct {
	HeapDelta      int64         `json:"heap_delta_bytes"`
	AllocatedBytes uint64        `json:"allocated_bytes"`
	Allocations    uint64        `json:"allocations"`
	GCCycles       uint32        `json:"gc_cycles"`
	GCPause        time.Duration `json:"gc_pause_ns"`
}

type Options struct {
	// Path is the mount path of the debug front end.
	Path string `yaml:"path"`

	// ServiceName is displayed in the front end and recorded on every trace.
	ServiceName string `yaml:"service_name"`

	// Enabled records traces. A disabled tracer passes requests through.
	Enabled bool `yaml:"enabled"`

	// RingBufferSize is the number of completed traces retained.
	RingBufferSize int `yaml:"ring_buffer_size"`

	// TopRequests is the maximum number of groups in rolling statistics.
	TopRequests int `yaml:"top_requests"`

	// MaxSpansPerTrace bounds the spans recorded in a single trace. Excess
	// spans are counted in Trace.DroppedSpans. Zero means unlimited.
	MaxSpansPerTrace int `yaml:"max_spans_per_trace"`

	// SampleRate is the percentage of requests traced, between 0 and 100. It
	// is ignored when Sampler is set.
	SampleRate float64 `yaml:"sample_rate"`

	// TrackMemoryUse records process-wide allocation changes for each trace.
	TrackMemoryUse bool `yaml:"track_memory_use"`

	// TrustRequestID reuses a client supplied Request-Id header. Only enable
	// this behind a trusted proxy.
	TrustRequestID bool `yaml:"trust_request_id"`

	// IgnorePaths lists request paths that are never traced. Entries ending in
	// "/*" match by prefix.
	IgnorePaths []string `yaml:"ignore_paths"`

	// RefreshInterval is the fallback auto refresh interval of the live view in
	// seconds, used when the browser cannot stream. Zero disables it.
	RefreshInterval int `yaml:"refresh_interval"`

	// LiveStream serves the live view over server sent events, so recorded
	// traces appear as they happen instead of on a timer.
	LiveStream bool `yaml:"live_stream"`

	// CaptureLogs records Trace.Info and Trace.Error log entries on traces.
	// Disabled, Info does nothing and Error records its formatted text as an
	// error on the active span, the way RecordError does, so the message is
	// not lost.
	CaptureLogs bool `yaml:"capture_logs"`

	// ReadEnv applies the OIDA_* environment to these options when the tracer
	// is built. NewOptions turns it on, so a service configured in code still
	// takes its deployment settings from the environment; options built as a
	// literal leave it off.
	ReadEnv bool `yaml:"read_env"`

	// Sampler decides whether a request is traced. It replaces SampleRate.
	Sampler Sampler `yaml:"-"`

	// Storage retains completed traces. Defaults to a memory ring buffer sized
	// by RingBufferSize; disk storage retains them across restarts.
	Storage Storage `yaml:"-"`

	// RouteFunc returns the routed pattern of a request, so statistics group
	// /users/1 and /users/2 into GET /users/{id}. With chi:
	//
	//	opts.RouteFunc = func(r *http.Request) string {
	//		return chi.RouteContext(r.Context()).RoutePattern()
	//	}
	//
	// The function decides on its own: returning an empty string means the
	// request has no route worth grouping by, and it groups by path instead.
	// A nil function falls back to the pattern the router recorded on the
	// request, which is what http.ServeMux and chi both set.
	RouteFunc func(r *http.Request) string `yaml:"-"`

	// OnError receives storage and recording errors. The package never writes
	// to stdout or stderr, so this is the only way to observe them.
	OnError func(error) `yaml:"-"`

	// Authorize gates access to the debug front end. A nil function allows
	// every request.
	Authorize func(r *http.Request) bool `yaml:"-"`

	// Clock is the time source of the tracer. Defaults to time.Now.
	Clock func() time.Time `yaml:"-"`

	// AllowedNetworks restricts the debug front end to peers inside these
	// CIDR ranges, such as 127.0.0.0/8 or 10.0.0.0/8. IPv4 and IPv6 both
	// work; an empty list allows every network. A request from outside
	// receives a 404 response, like a failed Authorize.
	AllowedNetworks []string `yaml:"allowed_networks"`

	// Users maps usernames to bcrypt password hashes for the front end login
	// screen. Setting any user puts the front end behind a login.
	Users map[string]string `yaml:"users"`

	// UsersFile is the path of an .htpasswd style file with one
	// username:bcrypt-hash per line. It is read once, when the front end is
	// mounted, and merged under Users.
	UsersFile string `yaml:"users_file"`

	// SigningSecret signs the session cookie issued by the login screen and
	// verifies "Authorization: Bearer" JWTs (HS256). When empty a per-process
	// secret is generated: logins work, but sessions do not survive a restart
	// and no externally minted token verifies.
	SigningSecret string `yaml:"signing_secret"`

	// AuthorizeUser authenticates a login when the configured users do not.
	// Returning nil grants a session naming the given username.
	AuthorizeUser func(ctx context.Context, username, password string) error `yaml:"-"`
	// contains filtered or unexported fields
}

type PoolEstimate struct {
	Samples               uint64 `json:"samples"`
	AverageAllocatedBytes uint64 `json:"average_allocated_bytes"`
	BeforeNextGC          uint64 `json:"traces_before_next_gc,omitempty"`
	WithinMemoryLimit     uint64 `json:"traces_within_memory_limit,omitempty"`
}

type Recorder interface {
	// StartTrace begins a trace the caller must complete with Finish.
	StartTrace(ctx context.Context, name string) (context.Context, *Trace, error)

	// Finish completes a trace and retains it.
	Finish(t *Trace)

	// Snapshot returns a race free copy of the recorded state.
	Snapshot() Snapshot

	// Traces returns the retained traces, newest first.
	Traces() []Trace

	// Trace returns the retained or in flight trace with the given ID.
	Trace(id string) (Trace, bool)

	// Live returns the traces currently in flight, newest first.
	Live() []Trace

	// Subscribe returns a channel notified whenever a trace starts or
	// completes, and a function releasing it.
	Subscribe() (<-chan struct{}, func())

	// Options returns the options the recorder was built with.
	Options() Options

	// Enabled reports whether the recorder records traces.
	Enabled() bool

	// SetEnabled turns recording on or off at runtime.
	SetEnabled(enabled bool)

	// Reset drops every retained trace and the lifetime counters.
	Reset()

	// ReportError forwards a failure to Options.OnError.
	ReportError(err error)
}

type Sampler interface {
	Sample(r *http.Request) bool
}

type SamplerFunc func(r *http.Request) bool

type Snapshot struct {
	Service    string        `json:"service"`
	StartedAt  time.Time     `json:"started_at"`
	Uptime     time.Duration `json:"uptime_ns"`
	PID        int           `json:"pid"`
	GoVersion  string        `json:"go_version"`
	GOMAXPROCS int           `json:"gomaxprocs"`
	Goroutines int           `json:"goroutines"`

	Total   uint64 `json:"total_requests"`
	Sampled uint64 `json:"sampled_traces"`
	Dropped uint64 `json:"dropped_traces"`
	Active  int    `json:"active_traces"`

	// Errors counts recorded traces that failed, and SLA is the share of
	// recorded traces that did not, as a percentage. Requests the sampler
	// rejected have unknown outcomes, so they are not in the denominator.
	Errors uint64  `json:"failed_traces"`
	SLA    float64 `json:"sla_percent"`

	StateTime []StateDuration `json:"state_time"`
	Memory    Memory          `json:"memory"`
	Pool      PoolEstimate    `json:"pool_estimate"`

	Live       []Trace `json:"live"`
	Log        []Trace `json:"log"`
	Statistics Stats   `json:"statistics"`
}

type Span struct {
	ID         int           `json:"id"`
	ParentID   int           `json:"parent_id,omitempty"`
	TraceID    string        `json:"trace_id"`
	Name       string        `json:"name"`
	Kind       Kind          `json:"kind"`
	StartedAt  time.Time     `json:"started_at"`
	Duration   time.Duration `json:"duration_ns,omitempty"`
	Depth      int           `json:"depth"`
	Filename   string        `json:"filename,omitempty"`
	Line       int           `json:"line,omitempty"`
	Attributes Attributes    `json:"attributes,omitempty"`

	// ErrorText is the message of the error recorded on the span. The JSON
	// key stays "error"; the Go name makes room for the Error log method.
	ErrorText string `json:"error,omitempty"`
	// contains filtered or unexported fields
}

type Spans []*Span

type State string

type StateDuration struct {
	State    State         `json:"state"`
	Label    string        `json:"label"`
	Duration time.Duration `json:"duration_ns"`
	Share    float64       `json:"share_percent"`
}

type Statistic struct {
	Name                  string        `json:"name"`
	Host                  string        `json:"host,omitempty"`
	Count                 uint64        `json:"count"`
	Errors                uint64        `json:"errors"`
	Share                 float64       `json:"share_percent"`
	AverageDuration       time.Duration `json:"average_duration_ns"`
	MaxDuration           time.Duration `json:"max_duration_ns"`
	AverageResponseBytes  uint64        `json:"average_response_bytes"`
	AverageAllocatedBytes uint64        `json:"average_allocated_bytes"`
	AverageSpans          float64       `json:"average_spans"`
	// contains filtered or unexported fields
}

type Stats struct {
	WindowSize  int         `json:"window_size"`
	WindowLimit int         `json:"window_limit"`
	TopLimit    int         `json:"top_limit"`
	Top         []Statistic `json:"top"`
	Hosts       []HostStat  `json:"hosts"`
}

type Storage interface {
	// Save retains a completed trace. The pointer is only lent for the
	// call: a driver copies what it keeps, with Clone or CloneInto, and
	// must not hold on to it.
	Save(ctx context.Context, trace *Trace) error

	// Load returns a retained trace, or ErrTraceNotFound.
	Load(ctx context.Context, id string) (Trace, error)

	// List returns retained traces newest first, at most limit of them. A limit
	// of zero or less returns everything retained.
	List(ctx context.Context, limit int) ([]Trace, error)

	// Len returns the number of retained traces.
	Len(ctx context.Context) (int, error)

	// Cap returns the retention limit, or zero when unbounded.
	Cap() int

	// Reset drops every retained trace.
	Reset(ctx context.Context) error

	// Prune drops retained traces older than maxAge. A driver with nothing
	// to prune returns nil.
	Prune(ctx context.Context, maxAge time.Duration) error

	// Restore fills the read path from what the driver persisted, so a new
	// process can list what an earlier one recorded. A driver holding nothing
	// of its own returns nil.
	Restore(ctx context.Context) error
}

type Trace struct {
	ID        string        `json:"id"`
	Name      string        `json:"name"`
	Service   string        `json:"service,omitempty"`
	State     State         `json:"state"`
	StartedAt time.Time     `json:"started_at"`
	UpdatedAt time.Time     `json:"updated_at"`
	Duration  time.Duration `json:"duration_ns"`

	// ErrorText is the message of the error recorded on the trace. The JSON
	// key stays "error"; the Go name makes room for the Error log method.
	ErrorText string `json:"error,omitempty"`

	// InFlight reports whether the trace was still running when it was copied.
	InFlight bool `json:"in_flight,omitempty"`

	HTTP   *HTTPInfo `json:"http,omitempty"`
	Memory MemoryUse `json:"memory"`

	// Attributes is what the transaction recorded about itself, such as the
	// memory limit it ran under.
	Attributes Attributes `json:"attributes,omitempty"`

	Spans        Spans `json:"spans,omitempty"`
	DroppedSpans int   `json:"dropped_spans,omitempty"`

	// Logs are the log lines recorded while the trace ran, in write order,
	// each linked to the span that was active when it was written. They are
	// bounded by the span limit; excess entries are counted in DroppedLogs.
	Logs        []LogEntry `json:"logs,omitempty"`
	DroppedLogs int        `json:"dropped_logs,omitempty"`
	// contains filtered or unexported fields
}

type TraceOptions struct {
	// Service is recorded on every trace, so a snapshot names the process it
	// came from.
	Service string

	// MaxSpans bounds the spans one trace records. Excess spans are counted in
	// Trace.DroppedSpans. It also bounds the log entries of the trace, whose
	// excess is counted in Trace.DroppedLogs. Zero means unlimited.
	MaxSpans int

	// Clock is the time source of the trace. A nil clock uses time.Now.
	Clock func() time.Time

	// CaptureLogs records Info and Error log entries on the trace. Disabled,
	// Info is a no-op and Error records through RecordError instead.
	CaptureLogs bool
}