From 6f8ad72ea693b39e147551776c172029b251f53d Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Tue, 3 Nov 2026 05:33:38 +0200 Subject: [PATCH 01/89] refactor(tracequery): delegate trace query and search UI to shared packages Trace search and filtering logic and the OTel search UI are now provided by the shared commons-db query/tracequery package and the clicky-ui data components. The local tracequery and otel webapp modules become thin adapters that delegate to them, so behavior is unchanged while the implementation lives in one place. Also adds a proxy token scope, an Endpoints field on token records, and ignores /docs/plans/. Callers of the removed internal helpers and components must use the shared equivalents. --- .gitignore | 1 + internal/tracequery/facets.go | 85 --------- internal/tracequery/filter.go | 127 ------------- internal/tracequery/opensearch.go | 104 ----------- internal/tracequery/opensearch_test.go | 85 --------- internal/tracequery/search.go | 242 ------------------------- internal/tracequery/search_test.go | 118 ------------ internal/tracequery/service.go | 122 +------------ internal/tracequery/types.go | 109 ++--------- pkg/credentials/apitoken/token.go | 11 +- pkg/credentials/apitoken/verify.go | 1 + webapp/src/main.tsx | 2 +- webapp/src/otel/OperationList.tsx | 44 ----- webapp/src/otel/OtelPage.test.tsx | 2 +- webapp/src/otel/OtelPage.tsx | 114 ++---------- webapp/src/otel/QueryBar.tsx | 87 --------- webapp/src/otel/TraceDetail.tsx | 201 -------------------- webapp/src/otel/TraceResults.test.tsx | 19 -- webapp/src/otel/TraceResults.tsx | 135 -------------- webapp/src/otel/api.ts | 143 +-------------- webapp/src/otel/model.test.tsx | 44 ----- webapp/src/otel/model.ts | 46 ----- webapp/src/otel/query.test.tsx | 60 ------ webapp/src/otel/query.ts | 68 ------- 24 files changed, 53 insertions(+), 1917 deletions(-) delete mode 100644 internal/tracequery/facets.go delete mode 100644 internal/tracequery/filter.go delete mode 100644 internal/tracequery/opensearch.go delete mode 100644 internal/tracequery/opensearch_test.go delete mode 100644 internal/tracequery/search.go delete mode 100644 internal/tracequery/search_test.go delete mode 100644 webapp/src/otel/OperationList.tsx delete mode 100644 webapp/src/otel/QueryBar.tsx delete mode 100644 webapp/src/otel/TraceDetail.tsx delete mode 100644 webapp/src/otel/TraceResults.test.tsx delete mode 100644 webapp/src/otel/TraceResults.tsx delete mode 100644 webapp/src/otel/model.test.tsx delete mode 100644 webapp/src/otel/model.ts delete mode 100644 webapp/src/otel/query.test.tsx delete mode 100644 webapp/src/otel/query.ts diff --git a/.gitignore b/.gitignore index d423a37..70eb739 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ sdk/java/.gradle/ sdk/java/build/ pkg/agentinstall/java/assets/* !pkg/agentinstall/java/assets/.gitkeep +/docs/plans/ diff --git a/internal/tracequery/facets.go b/internal/tracequery/facets.go deleted file mode 100644 index ab68a63..0000000 --- a/internal/tracequery/facets.go +++ /dev/null @@ -1,85 +0,0 @@ -package tracequery - -import ( - "cmp" - "fmt" - "slices" -) - -const ( - maxAttributeSuggestions = 100 - maxAttributeValueLength = 100 -) - -// facets gather what a search's traces hold, for its filters to offer: the -// traces of each root operation and the values of their root spans' attributes. -type facets struct { - byOperation map[string][]Summary - byAttribute map[string]int -} - -func newFacets() *facets { - return &facets{byOperation: map[string][]Summary{}, byAttribute: map[string]int{}} -} - -func (f *facets) add(summary Summary, root Span) { - f.byOperation[summary.Operation] = append(f.byOperation[summary.Operation], summary) - seen := map[string]bool{} - for _, values := range []map[string]any{root.Attributes, root.Resource} { - for key, value := range values { - switch value.(type) { - case string, bool, int, int32, int64, uint64, float32, float64: - default: - continue - } - text := fmt.Sprint(value) - if len(text) > maxAttributeValueLength || seen[key] { - continue - } - seen[key] = true - f.byAttribute[key+"="+text]++ - } - } -} - -// operations are the root operations, those of multi-span traces first, then the most frequent. -func (f *facets) operations() []OperationStats { - result := []OperationStats{} - for operation, traces := range f.byOperation { - durations := []float64{} - single := true - for _, trace := range traces { - durations = append(durations, trace.DurationMs) - single = single && trace.SpanCount == 1 - } - slices.Sort(durations) - result = append(result, OperationStats{Operation: operation, Count: len(traces), SingleSpan: single, P50Ms: quantile(durations, 0.5), P95Ms: quantile(durations, 0.95)}) - } - slices.SortFunc(result, func(a, b OperationStats) int { - if a.SingleSpan != b.SingleSpan { - if a.SingleSpan { - return 1 - } - return -1 - } - return cmp.Or(cmp.Compare(b.Count, a.Count), cmp.Compare(a.Operation, b.Operation)) - }) - return result -} - -// attributes are the most frequent root span attribute values, key=value. -func (f *facets) attributes() []AttributeCount { - result := []AttributeCount{} - for value, count := range f.byAttribute { - result = append(result, AttributeCount{Value: value, Count: count}) - } - slices.SortFunc(result, func(a, b AttributeCount) int { - return cmp.Or(cmp.Compare(b.Count, a.Count), cmp.Compare(a.Value, b.Value)) - }) - return result[:min(len(result), maxAttributeSuggestions)] -} - -// quantile is the q-quantile of sorted values, the nearest rank at or below it. -func quantile(sorted []float64, q float64) float64 { - return sorted[min(len(sorted)-1, int(q*float64(len(sorted))))] -} diff --git a/internal/tracequery/filter.go b/internal/tracequery/filter.go deleted file mode 100644 index a585643..0000000 --- a/internal/tracequery/filter.go +++ /dev/null @@ -1,127 +0,0 @@ -package tracequery - -import ( - "fmt" - "regexp" - "strings" -) - -// Mode includes or excludes a filter value. -type Mode string - -const ( - Include Mode = "include" - Exclude Mode = "exclude" -) - -// Modes are a filter's values, each included or excluded: a trace passes -// when it has one of the included values (or none is included) and none of -// the excluded ones. -type Modes map[string]Mode - -func (Modes) JSONSchema() map[string]any { - return map[string]any{"type": "object", "additionalProperties": map[string]any{"type": "string", "enum": []string{string(Include), string(Exclude)}}} -} - -func (m Modes) validate(name string, value func(string) error) error { - for key, mode := range m { - if mode != Include && mode != Exclude { - return fmt.Errorf("%s %q: mode must be include or exclude, not %q", name, key, mode) - } - if err := value(key); err != nil { - return fmt.Errorf("%s %q: %w", name, key, err) - } - } - return nil -} - -func (m Modes) values(mode Mode) []string { - result := []string{} - for key, value := range m { - if value == mode { - result = append(result, key) - } - } - return result -} - -// pass reports whether a trace, holding the values has reports, passes m. -func (m Modes) pass(has func(string) bool) bool { - included := m.values(Include) - matched := len(included) == 0 - for _, value := range included { - matched = matched || has(value) - } - for _, value := range m.values(Exclude) { - if has(value) { - return false - } - } - return matched -} - -// passAttributes reports whether spans pass attribute filters: included -// expressions are any-of per key and all-of across keys, and any span -// matching an excluded expression rejects the trace. -func (m Modes) passAttributes(spans []Span) bool { - byKey := map[string][]string{} - for _, expr := range m.values(Include) { - key, _, _ := strings.Cut(expr, "=") - byKey[key] = append(byKey[key], expr) - } - anySpan := func(expr string) bool { - for _, span := range spans { - if attributeMatches(span, expr) { - return true - } - } - return false - } - for _, exprs := range byKey { - matched := false - for _, expr := range exprs { - matched = matched || anySpan(expr) - } - if !matched { - return false - } - } - for _, expr := range m.values(Exclude) { - if anySpan(expr) { - return false - } - } - return true -} - -func validAttribute(expr string) error { - key, _, _ := strings.Cut(expr, "=") - if strings.TrimSpace(key) == "" { - return fmt.Errorf("an attribute filter is key, key=value or key=prefix*") - } - return nil -} - -func validStatus(status string) error { - if status != "ok" && status != "error" { - return fmt.Errorf("status must be error or ok") - } - return nil -} - -// attributeMatches reports whether span has the attribute expr names: a bare -// key matches its presence, key=value its value, with * as a wildcard. Span -// attributes win over resource attributes of the same key. -func attributeMatches(span Span, expr string) bool { - key, want, hasValue := strings.Cut(expr, "=") - key = strings.TrimSpace(key) - value, ok := span.Attributes[key] - if !ok { - value, ok = span.Resource[key] - } - if !ok || !hasValue { - return ok - } - pattern := strings.ReplaceAll(regexp.QuoteMeta(strings.TrimSpace(want)), `\*`, ".*") - return regexp.MustCompile("^" + pattern + "$").MatchString(fmt.Sprint(value)) -} diff --git a/internal/tracequery/opensearch.go b/internal/tracequery/opensearch.go deleted file mode 100644 index 10feed1..0000000 --- a/internal/tracequery/opensearch.go +++ /dev/null @@ -1,104 +0,0 @@ -package tracequery - -import ( - "context" - "fmt" - - dbcontext "github.com/flanksource/commons-db/context" - "github.com/flanksource/commons-db/models" - "github.com/flanksource/commons-db/query" - "github.com/flanksource/commons-db/query/esdsl" - "github.com/flanksource/commons-db/query/providers" - "github.com/flanksource/commons-db/types" - imported "github.com/flanksource/telltale/pkg/tracing/opensearch" -) - -func (s Service) openSearch(ctx context.Context, r Request, c *models.Connection, ids []string) ([]Span, error) { - if c.Type != models.ConnectionTypeOpenSearch && c.Type != models.ConnectionTypeOpenTelemetry { - return nil, fmt.Errorf("source %q has unsupported type %q", r.Source, c.Type) - } - queryContext := s.Connections.Attach(dbcontext.NewContext(ctx)) - reference := r.Source - if c.Type == models.ConnectionTypeOpenSearch { - reference = "connection://telltale-trace-query" - next := queryContext.ConnectionResolver() - queryContext = queryContext.WithConnectionResolver(func(ctx dbcontext.Context, ref string) (*models.Connection, error) { - if ref == reference { - return &models.Connection{Name: "telltale-trace-query", Type: models.ConnectionTypeOpenTelemetry, Properties: types.JSONStringMap{"connection": c.ID.String()}}, nil - } - return next(ctx, ref) - }) - } - options := map[string]any{} - for _, key := range []string{"index", "format", "dateField", "traceIdField", "spanIdField", "parentIdField", "parentRefType", "serviceField", "operationField"} { - if value := c.Properties[key]; value != "" { - options[key] = value - } - } - if r.Index != "" { - options["index"] = r.Index - } - if r.Format != "" { - options["format"] = string(r.Format) - } - format, _ := options["format"].(string) - if format == "jaeger" { - jaegerDefaults(options) - } - if len(ids) == 0 && r.TraceID != "" { - ids = []string{r.TraceID} - } - if len(ids) > 0 { - field := "trace_id" - if value, ok := options["traceIdField"].(string); ok { - field = value - } - values := make([]esdsl.Value, len(ids)) - for i, id := range ids { - values[i] = *esdsl.Literal(id) - } - options["search"] = &esdsl.Search{Query: &esdsl.Condition{Op: "terms", Field: field, Values: values}} - } - return readOpenSearch(queryContext, providers.OpenTelemetryRead{Connection: reference, Options: options, From: r.From, To: r.Until}) -} - -func jaegerDefaults(options map[string]any) { - for key, value := range map[string]string{"dateField": "startTimeMillis", "traceIdField": "traceID", "spanIdField": "spanID", "parentRefType": "CHILD_OF", "serviceField": "process.serviceName", "operationField": "operationName"} { - if _, ok := options[key]; !ok { - options[key] = value - } - } -} - -func readOpenSearch(ctx dbcontext.Context, request providers.OpenTelemetryRead) ([]Span, error) { - readCtx, cancel := context.WithCancel(ctx) - defer cancel() - spans := []Span{} - var readErr error - err := providers.ReadOpenTelemetrySpans(ctx.Wrap(readCtx), request, func(row query.Row) { - if readErr != nil { - return - } - span, err := imported.FromRow(row) - if err != nil { - readErr = err - cancel() - return - } - converted, err := fromSpan(span, false) - if err != nil { - readErr = err - cancel() - return - } - spans = append(spans, converted) - if len(spans) > maxSpans { - readErr = fmt.Errorf("OpenSearch read exceeds %d spans; narrow the time window or index", maxSpans) - cancel() - } - }) - if readErr != nil { - return nil, readErr - } - return spans, err -} diff --git a/internal/tracequery/opensearch_test.go b/internal/tracequery/opensearch_test.go deleted file mode 100644 index e64b9a8..0000000 --- a/internal/tracequery/opensearch_test.go +++ /dev/null @@ -1,85 +0,0 @@ -package tracequery - -import ( - "context" - "encoding/json" - "net/http" - "net/http/httptest" - "strings" - "time" - - "github.com/flanksource/commons-db/connection/crd" - "github.com/flanksource/commons-db/connection/store" - "github.com/flanksource/commons-db/models" - "github.com/flanksource/commons-db/types" - . "github.com/onsi/ginkgo/v2" - . "github.com/onsi/gomega" -) - -var _ = Describe("OpenSearch trace search", func() { - DescribeTable("reads mapped spans through the shared provider", func(format, sourceType string) { - at := time.Now().UTC().Add(-time.Minute).Truncate(time.Millisecond) - index := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - defer GinkgoRecover() - if r.Method == http.MethodHead { - w.WriteHeader(200) - return - } - w.Header().Set("Content-Type", "application/json") - fieldType := "date" - if format == "jaeger" { - fieldType = "long" - } - if strings.HasSuffix(r.URL.Path, "/_field_caps") { - Expect(json.NewEncoder(w).Encode(map[string]any{"fields": map[string]any{r.URL.Query().Get("fields"): map[string]any{fieldType: map[string]any{"searchable": true, "aggregatable": true}}}})).To(Succeed()) - return - } - if strings.Contains(r.URL.Path, "/_mapping/field/") { - field := r.URL.Path[strings.LastIndex(r.URL.Path, "/")+1:] - Expect(json.NewEncoder(w).Encode(map[string]any{"traces-example": map[string]any{"mappings": map[string]any{field: map[string]any{"full_name": field, "mapping": map[string]any{field: map[string]any{"type": fieldType}}}}}})).To(Succeed()) - return - } - var body map[string]any - Expect(json.NewDecoder(r.Body).Decode(&body)).To(Succeed()) - hits := []any{} - if body["search_after"] == nil { - for i, id := range []string{"root", "child"} { - started := at.Add(time.Duration(i) * 20 * time.Millisecond) - doc := map[string]any{"@timestamp": started.Format(time.RFC3339Nano), "trace_id": "trace-search", "span_id": id, "operation_name": id, "service_name": "checkout", "duration_ms": 100} - if i > 0 { - doc["parent_id"] = "root" - } - if format == "jaeger" { - doc = map[string]any{"startTimeMillis": started.UnixMilli(), "traceID": "trace-search", "spanID": id, "operationName": id, "process": map[string]any{"serviceName": "checkout"}, "duration": 100000} - if i > 0 { - doc["references"] = []any{map[string]any{"refType": "CHILD_OF", "spanID": "root"}} - } - } - hits = append(hits, map[string]any{"_index": "traces-example", "_id": id, "_source": doc, "sort": []any{started.UnixMilli(), id}}) - } - } - Expect(json.NewEncoder(w).Encode(map[string]any{"took": 1, "hits": map[string]any{"total": map[string]any{"value": len(hits), "relation": "eq"}, "hits": hits}})).To(Succeed()) - })) - DeferCleanup(index.Close) - catalog, err := store.New(store.Layer{Name: store.LayerCWD, Dir: GinkgoT().TempDir()}) - Expect(err).NotTo(HaveOccurred()) - search, err := crd.FromModel(models.Connection{Name: "search", Type: models.ConnectionTypeOpenSearch, URL: index.URL}) - Expect(err).NotTo(HaveOccurred()) - Expect(catalog.Save(store.LayerCWD, search)).To(Succeed()) - source := "search" - if sourceType == "opentelemetry" { - outer, err := crd.FromModel(models.Connection{Name: "traces", Type: models.ConnectionTypeOpenTelemetry, Properties: types.JSONStringMap{"connection": "connection://search"}}) - Expect(err).NotTo(HaveOccurred()) - Expect(catalog.Save(store.LayerCWD, outer)).To(Succeed()) - source = "traces" - } - service := Service{Connections: catalog} - request := Request{Source: source, Index: "traces-*", Format: DocumentFormat(format)} - result, err := service.Search(context.Background(), request) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Traces).To(HaveExactElements(And(HaveField("TraceID", "trace-search"), HaveField("SpanCount", 2)))) - detail, err := service.Trace(context.Background(), request, "trace-search") - Expect(err).NotTo(HaveOccurred()) - Expect(detail.Spans[1].ParentID).To(Equal("root")) - }, Entry("flat OpenSearch", "flat", "opensearch"), Entry("Jaeger OpenTelemetry connection", "jaeger", "opentelemetry")) -}) diff --git a/internal/tracequery/search.go b/internal/tracequery/search.go deleted file mode 100644 index ca97b54..0000000 --- a/internal/tracequery/search.go +++ /dev/null @@ -1,242 +0,0 @@ -package tracequery - -import ( - "errors" - "fmt" - "math" - "reflect" - "slices" - "strings" - "time" -) - -// isError reads the canonical status every span source normalizes to. -func isError(status string) bool { return status == "error" } - -func duration(value string) (float64, error) { - if value == "" { - return 0, nil - } - d, err := time.ParseDuration(value) - if err != nil || d < 0 { - return 0, fmt.Errorf("invalid duration %q: expected a nonnegative duration such as 100ms", value) - } - return float64(d) / float64(time.Millisecond), nil -} - -func (r Request) validate() error { - min, err := duration(r.MinDuration) - if err != nil { - return err - } - max, err := duration(r.MaxDuration) - if err != nil { - return err - } - if r.MaxDuration != "" && max < min { - return fmt.Errorf("maximum duration must be at least minimum duration") - } - if r.Limit < 0 || r.Limit > 1000 { - return fmt.Errorf("trace limit must be between 1 and 1000") - } - if r.MinSpans < 0 { - return fmt.Errorf("minimum spans must not be negative") - } - anyValue := func(string) error { return nil } - if err := errors.Join(r.Services.validate("service", anyValue), r.Operations.validate("operation", anyValue), r.Statuses.validate("status", validStatus), r.Attributes.validate("attribute", validAttribute)); err != nil { - return err - } - if r.Format != "" && r.Format != "flat" && r.Format != "jaeger" { - return fmt.Errorf("format must be flat or jaeger") - } - for _, value := range []string{r.From, r.Until} { - if value != "" { - if _, err := time.Parse(time.RFC3339Nano, value); err != nil { - return fmt.Errorf("invalid timestamp %q: %w", value, err) - } - } - } - return nil -} - -func groups(spans []Span) (map[string][]Span, error) { - result := map[string][]Span{} - seen := map[string]Span{} - for _, span := range spans { - if span.TraceID == "" || span.SpanID == "" || span.StartedAt.IsZero() || math.IsNaN(span.DurationMs) || math.IsInf(span.DurationMs, 0) || span.DurationMs < 0 || span.DurationMs >= float64(math.MaxInt64)/float64(time.Millisecond) { - return nil, fmt.Errorf("invalid span %q in trace %q: identity, start time and a representable nonnegative duration are required", span.SpanID, span.TraceID) - } - key := span.TraceID + "/" + span.SpanID - if old, ok := seen[key]; ok { - if !reflect.DeepEqual(old, span) { - return nil, fmt.Errorf("conflicting span %s", key) - } - continue - } - seen[key] = span - result[span.TraceID] = append(result[span.TraceID], span) - } - return result, nil -} - -// summarize is a trace's summary and its root span: the parentless one, or the earliest. -func summarize(spans []Span) (Summary, Span) { - first := spans[0] - start, end := first.StartedAt, first.StartedAt - root := first - services := map[string]bool{} - errors := 0 - for _, span := range spans { - if span.StartedAt.Before(start) { - start = span.StartedAt - } - if finish := span.StartedAt.Add(time.Duration(span.DurationMs * float64(time.Millisecond))); finish.After(end) { - end = finish - } - if span.ParentID == "" && root.ParentID != "" { - root = span - } else if (span.ParentID == "" || root.ParentID != "") && span.StartedAt.Before(root.StartedAt) { - root = span - } - services[span.Service] = true - if isError(span.Status) { - errors++ - } - } - result := Summary{TraceID: first.TraceID, Service: root.Service, Operation: root.Operation, StartedAt: start, DurationMs: float64(end.Sub(start)) / float64(time.Millisecond), SpanCount: len(spans), Errors: errors, Services: []string{}} - for service := range services { - result.Services = append(result.Services, service) - } - slices.Sort(result.Services) - return result, root -} - -// inWindow reports whether span starts in the request's window and trace. -func inWindow(span Span, r Request) bool { - if r.From != "" { - from, _ := time.Parse(time.RFC3339Nano, r.From) - if span.StartedAt.Before(from) { - return false - } - } - if r.Until != "" { - until, _ := time.Parse(time.RFC3339Nano, r.Until) - if !span.StartedAt.Before(until) { - return false - } - } - return r.TraceID == "" || r.TraceID == span.TraceID -} - -// passes reports whether a trace passes every filter but the root operation -// and span-count ones, which the root operation counts leave out. -func (r Request) passes(summary Summary, spans []Span, min, max float64) bool { - return summary.DurationMs >= min && (r.MaxDuration == "" || summary.DurationMs <= max) && - r.Services.pass(func(service string) bool { return slices.Contains(summary.Services, service) }) && - r.Statuses.pass(func(status string) bool { return (status == "error") == (summary.Errors > 0) }) && - r.Attributes.passAttributes(spans) -} - -// Search filters whole traces with a span in the window: by their duration, -// services, status, any span's attributes, root operation and span count. -func Search(spans []Span, r Request) (SearchResult, error) { - result := SearchResult{Traces: []Summary{}, Services: []string{}, RootOperations: []OperationStats{}, Attributes: []AttributeCount{}} - if err := r.validate(); err != nil { - return result, err - } - grouped, err := groups(spans) - if err != nil { - return result, err - } - min, _ := duration(r.MinDuration) - max, _ := duration(r.MaxDuration) - services := map[string]bool{} - facets := newFacets() - for _, trace := range grouped { - if !slices.ContainsFunc(trace, func(span Span) bool { return inWindow(span, r) }) { - continue - } - summary, root := summarize(trace) - for _, service := range summary.Services { - services[service] = true - } - if !r.passes(summary, trace, min, max) { - continue - } - facets.add(summary, root) - if summary.SpanCount >= r.MinSpans && r.Operations.pass(func(operation string) bool { return operation == summary.Operation }) { - result.Traces = append(result.Traces, summary) - } - } - result.RootOperations, result.Attributes = facets.operations(), facets.attributes() - slices.SortFunc(result.Traces, func(a, b Summary) int { - if cmp := b.StartedAt.Compare(a.StartedAt); cmp != 0 { - return cmp - } - return strings.Compare(a.TraceID, b.TraceID) - }) - result.Total = len(result.Traces) - limit := r.Limit - if limit == 0 { - limit = 100 - } - if len(result.Traces) > limit { - result.Traces = result.Traces[:limit] - } - for key := range services { - result.Services = append(result.Services, key) - } - slices.Sort(result.Services) - return result, nil -} - -func Trace(spans []Span, id string) (Detail, error) { - grouped, err := groups(spans) - if err != nil { - return Detail{}, err - } - selected := grouped[id] - if len(selected) == 0 { - return Detail{}, fmt.Errorf("%w: %q", ErrTraceNotFound, id) - } - slices.SortFunc(selected, func(a, b Span) int { - if cmp := a.StartedAt.Compare(b.StartedAt); cmp != 0 { - return cmp - } - return strings.Compare(a.SpanID, b.SpanID) - }) - parents := map[string]string{} - for _, span := range selected { - parents[span.SpanID] = span.ParentID - } - missing := map[string]bool{} - finished := map[string]bool{} - for _, span := range selected { - visited := map[string]bool{} - for id := span.SpanID; id != ""; { - if finished[id] { - break - } - if visited[id] { - return Detail{}, fmt.Errorf("parent cycle in trace %s at span %s", span.TraceID, id) - } - visited[id] = true - parent, ok := parents[id] - if !ok { - missing[id] = true - break - } - id = parent - } - for id := range visited { - finished[id] = true - } - } - summary, _ := summarize(selected) - result := Detail{Summary: summary, Spans: selected, MissingParents: []string{}} - for id := range missing { - result.MissingParents = append(result.MissingParents, id) - } - slices.Sort(result.MissingParents) - return result, nil -} diff --git a/internal/tracequery/search_test.go b/internal/tracequery/search_test.go deleted file mode 100644 index d9833d2..0000000 --- a/internal/tracequery/search_test.go +++ /dev/null @@ -1,118 +0,0 @@ -package tracequery - -import ( - "testing" - "time" - - . "github.com/onsi/ginkgo/v2" - . "github.com/onsi/gomega" -) - -func TestTraceQuery(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Trace query") } - -var _ = Describe("trace search", func() { - at := time.Date(2026, 10, 29, 10, 0, 0, 0, time.UTC) - var spans []Span - BeforeEach(func() { - spans = []Span{ - {TraceID: "trace-a", SpanID: "root", Service: "checkout", Operation: "POST /orders", StartedAt: at, DurationMs: 100, Status: "ok"}, - {TraceID: "trace-a", SpanID: "child", ParentID: "root", Service: "payments", Operation: "charge", StartedAt: at.Add(10 * time.Millisecond), DurationMs: 40, Status: "error", Attributes: map[string]any{"http.status_code": 500}}, - {TraceID: "trace-b", SpanID: "other", Service: "checkout", Operation: "GET /orders", StartedAt: at.Add(time.Second), DurationMs: 10, Status: "ok"}, - } - }) - It("filters whole traces by their services, root operation, status and any span's attributes, returning whole-trace totals", func() { - result, err := Search(spans, Request{ - Services: Modes{"payments": Include}, Operations: Modes{"POST /orders": Include}, Statuses: Modes{"error": Include}, - Attributes: Modes{"http.status_code=5*": Include}, MinDuration: "90ms", - }) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Traces).To(HaveExactElements(Summary{TraceID: "trace-a", Service: "checkout", Operation: "POST /orders", StartedAt: at, DurationMs: 100, SpanCount: 2, Errors: 1, Services: []string{"checkout", "payments"}})) - result, err = Search(spans, Request{Operations: Modes{"charge": Include}}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Total).To(BeZero(), "charge runs in a trace but is not its root") - }) - DescribeTable("includes are any-of, excludes reject, and attribute includes are any-of per key and all-of across keys", - func(request Request, want []string) { - result, err := Search(spans, request) - Expect(err).NotTo(HaveOccurred()) - ids := []string{} - for _, trace := range result.Traces { - ids = append(ids, trace.TraceID) - } - Expect(ids).To(Equal(want)) - }, - Entry("either root operation", Request{Operations: Modes{"POST /orders": Include, "GET /orders": Include}}, []string{"trace-b", "trace-a"}), - Entry("an excluded service", Request{Services: Modes{"payments": Exclude}}, []string{"trace-b"}), - Entry("ok traces", Request{Statuses: Modes{"ok": Include}}, []string{"trace-b"}), - Entry("a bare key matches its presence", Request{Attributes: Modes{"http.status_code": Include}}, []string{"trace-a"}), - Entry("values of one key are any-of", Request{Attributes: Modes{"http.status_code=404": Include, "http.status_code=500": Include}}, []string{"trace-a"}), - Entry("keys are all-of", Request{Attributes: Modes{"http.status_code=500": Include, "absent": Include}}, []string{}), - Entry("an excluded attribute", Request{Attributes: Modes{"http.status_code": Exclude}}, []string{"trace-b"}), - Entry("traces of at least two spans", Request{MinSpans: 2}, []string{"trace-a"}), - ) - It("counts every root operation in the window, with its percentiles, whatever the operation and span filters", func() { - result, err := Search(spans, Request{Operations: Modes{"GET /orders": Include}, MinSpans: 2}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Total).To(BeZero()) - Expect(result.RootOperations).To(Equal([]OperationStats{ - {Operation: "POST /orders", Count: 1, P50Ms: 100, P95Ms: 100}, - {Operation: "GET /orders", Count: 1, SingleSpan: true, P50Ms: 10, P95Ms: 10}, - })) - result, err = Search(spans, Request{Services: Modes{"payments": Exclude}}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.RootOperations).To(HaveExactElements(HaveField("Operation", "GET /orders")), "the other filters still narrow the counts") - }) - It("suggests the root spans' attribute values, most frequent first", func() { - spans[0].Attributes = map[string]any{"http.method": "POST"} - spans[2].Attributes = map[string]any{"http.method": "GET", "payload": map[string]any{"nested": true}} - spans[2].Resource = map[string]any{"service.name": "checkout"} - spans[0].Resource = map[string]any{"service.name": "checkout"} - result, err := Search(spans, Request{}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Attributes).To(Equal([]AttributeCount{ - {Value: "service.name=checkout", Count: 2}, - {Value: "http.method=GET", Count: 1}, - {Value: "http.method=POST", Count: 1}, - })) - }) - It("caps traces after grouping and keeps deterministic newest-first order", func() { - result, err := Search(spans, Request{Limit: 1}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Total).To(Equal(2)) - Expect(result.Traces).To(HaveExactElements(HaveField("TraceID", "trace-b"))) - }) - It("reports missing parents and refuses cycles or conflicting duplicate span IDs", func() { - detail, err := Trace(spans, "trace-a") - Expect(err).NotTo(HaveOccurred()) - Expect(detail.Spans).To(HaveLen(2)) - spans[0].ParentID = "absent" - detail, err = Trace(spans, "trace-a") - Expect(err).NotTo(HaveOccurred()) - Expect(detail.MissingParents).To(Equal([]string{"absent"})) - spans[0].ParentID = "child" - _, err = Trace(spans, "trace-a") - Expect(err).To(MatchError(ContainSubstring("cycle"))) - }) - It("names a rootless trace after its earliest span regardless of input order", func() { - spans[0].ParentID = "absent" - result, err := Search([]Span{spans[1], spans[0]}, Request{}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Traces[0].Operation).To(Equal("POST /orders")) - }) - It("deduplicates identical spans and refuses conflicting or overflowing durations", func() { - result, err := Search(append(spans, spans[0]), Request{}) - Expect(err).NotTo(HaveOccurred()) - Expect(result.Traces[1].SpanCount).To(Equal(2)) - changed := spans[0] - changed.DurationMs++ - _, err = Search(append(spans, changed), Request{}) - Expect(err).To(MatchError(ContainSubstring("conflicting span"))) - spans[0].DurationMs = 1e20 - _, err = Search(spans, Request{}) - Expect(err).To(MatchError(ContainSubstring("invalid span"))) - }) - DescribeTable("refuses invalid filters", func(request Request) { _, err := Search(spans, request); Expect(err).To(HaveOccurred()) }, - Entry("negative duration", Request{MinDuration: "-1ms"}), Entry("duration order", Request{MinDuration: "2s", MaxDuration: "1s"}), Entry("limit", Request{Limit: 1001}), - Entry("status", Request{Statuses: Modes{"maybe": Include}}), Entry("mode", Request{Services: Modes{"checkout": "only"}}), - Entry("attribute key", Request{Attributes: Modes{"=500": Include}}), Entry("span count", Request{MinSpans: -1})) -}) diff --git a/internal/tracequery/service.go b/internal/tracequery/service.go index 9a78086..26485bd 100644 --- a/internal/tracequery/service.go +++ b/internal/tracequery/service.go @@ -2,130 +2,24 @@ package tracequery import ( "context" - "fmt" - "slices" - "time" - - dbcontext "github.com/flanksource/commons-db/context" - "github.com/flanksource/commons-db/models" + shared "github.com/flanksource/commons-db/query/tracequery" ) -const maxSpans = 100000 - +func (s Service) query() shared.Service { + return shared.Service{Connections: s.Connections, Read: s.load} +} func (s Service) Sources() ([]Source, error) { - if s.Connections == nil { - return nil, fmt.Errorf("trace source catalog is not configured") - } - result := []Source{{ID: "records", Name: "Recorded traces", Type: "records"}} - connections, err := s.Connections.ListConnections() - if err != nil { - return nil, err - } - for _, c := range connections { - if c.Type == models.ConnectionTypeOpenTelemetry || c.Type == models.ConnectionTypeOpenSearch { - name := c.Name - if c.Namespace != "" { - name = c.Namespace + "/" + name - } - result = append(result, Source{ID: c.ID.String(), Name: name, Type: c.Type}) - } - } - return result, nil + return (shared.Service{Connections: s.Connections}).Sources() } - func (s Service) Search(ctx context.Context, r Request) (SearchResult, error) { - if err := r.validate(); err != nil { - return SearchResult{}, err - } - var err error - r, err = r.window(time.Now()) - if err != nil { - return SearchResult{}, err - } - spans, err := s.load(ctx, r, nil) - if err != nil { - return SearchResult{}, err - } - ids := []string{} - for _, span := range spans { - if inWindow(span, r) && !slices.Contains(ids, span.TraceID) { - ids = append(ids, span.TraceID) - } - } - if len(ids) > 0 { - full := r - full.From, full.Until = "", "" - spans, err = s.load(ctx, full, ids) - if err != nil { - return SearchResult{}, err - } - } - return Search(spans, r) + return s.query().Search(ctx, r) } - func (s Service) Trace(ctx context.Context, r Request, id string) (Detail, error) { - if id == "" { - return Detail{}, fmt.Errorf("trace ID is required") - } - if err := r.validate(); err != nil { - return Detail{}, err - } - r.TraceID = id - r.From, r.Until = "", "" - spans, err := s.load(ctx, r, []string{id}) - if err != nil { - return Detail{}, err - } - return Trace(spans, id) + return s.query().Trace(ctx, r, id) } - func (s Service) load(ctx context.Context, r Request, ids []string) ([]Span, error) { if r.Source == "records" { return s.recorded(ctx, r, ids) } - if r.Source == "" { - return nil, fmt.Errorf("source is required") - } - if s.Connections == nil { - return nil, fmt.Errorf("trace source catalog is not configured") - } - c, err := s.Connections.ResolveConnection(dbcontext.NewContext(ctx), r.Source) - if err != nil { - return nil, err - } - if c == nil { - return nil, fmt.Errorf("source connection %q not found", r.Source) - } - return s.openSearch(ctx, r, c, ids) -} - -func (r Request) window(now time.Time) (Request, error) { - until := now.UTC() - var err error - if r.Until != "" { - until, err = time.Parse(time.RFC3339Nano, r.Until) - if err != nil { - return r, fmt.Errorf("until: %w", err) - } - } - lookback := r.Lookback - if lookback == "" { - lookback = "1h" - } - d, err := time.ParseDuration(lookback) - if err != nil || d <= 0 { - return r, fmt.Errorf("lookback must be a positive duration") - } - from := until.Add(-d) - if r.From != "" { - from, err = time.Parse(time.RFC3339Nano, r.From) - if err != nil { - return r, fmt.Errorf("from: %w", err) - } - } - if !from.Before(until) { - return r, fmt.Errorf("from must precede until") - } - r.From, r.Until = from.UTC().Format(time.RFC3339Nano), until.UTC().Format(time.RFC3339Nano) - return r, nil + return (shared.Service{Connections: s.Connections}).ReadSpans(ctx, r, ids) } diff --git a/internal/tracequery/types.go b/internal/tracequery/types.go index e413e71..8483d9b 100644 --- a/internal/tracequery/types.go +++ b/internal/tracequery/types.go @@ -1,102 +1,25 @@ package tracequery import ( - "encoding/json" - "errors" - "time" - "github.com/flanksource/commons-db/connection/store" + shared "github.com/flanksource/commons-db/query/tracequery" ) -var ErrTraceNotFound = errors.New("trace not found") - -type DocumentFormat string - -func (DocumentFormat) JSONSchema() map[string]any { - return map[string]any{"type": "string", "enum": []string{"flat", "jaeger"}} -} - -type Span struct { - TraceID string `json:"traceId"` - SpanID string `json:"spanId"` - ParentID string `json:"parentId,omitempty"` - Service string `json:"service"` - Operation string `json:"operation"` - Kind string `json:"kind,omitempty"` - StartedAt time.Time `json:"startedAt"` - DurationMs float64 `json:"durationMs"` - Status string `json:"status"` - Attributes map[string]any `json:"attributes,omitempty"` - Resource map[string]any `json:"resource,omitempty"` - OTLP json.RawMessage `json:"otlp,omitempty"` -} - -type Request struct { - Source string `json:"source" clicky:"title=Source,required"` - Run string `json:"run,omitempty" clicky:"title=Run,desc=Optional recorded run ID"` - Index string `json:"index,omitempty" clicky:"title=Index,desc=OpenSearch index pattern (default otel-traces-*)"` - Format DocumentFormat `json:"format,omitempty" clicky:"title=Document format"` - Services Modes `json:"services,omitempty" clicky:"title=Services,desc=Services a trace's spans run in: each included or excluded"` - Operations Modes `json:"operations,omitempty" clicky:"title=Root operations,desc=A trace's root operation: each included or excluded"` - Statuses Modes `json:"statuses,omitempty" clicky:"title=Statuses,desc=error (a span failed) or ok: each included or excluded"` - Attributes Modes `json:"attributes,omitempty" clicky:"title=Attributes,desc=Span or resource attributes of any span: key, key=value or key=prefix*, each included or excluded"` - MinSpans int `json:"minSpans,omitempty" clicky:"title=Minimum spans,desc=Traces of at least this many spans"` - TraceID string `json:"traceId,omitempty" clicky:"title=Trace ID"` - Lookback string `json:"lookback,omitempty" clicky:"title=Lookback,desc=Duration such as 15m or 24h; used when From is empty"` - From string `json:"from,omitempty" clicky:"title=From,desc=Inclusive RFC3339 timestamp"` - Until string `json:"until,omitempty" clicky:"title=Until,desc=Exclusive RFC3339 timestamp"` - MinDuration string `json:"minDuration,omitempty" clicky:"title=Minimum trace duration,desc=Duration such as 100ms or 2s"` - MaxDuration string `json:"maxDuration,omitempty" clicky:"title=Maximum trace duration,desc=Duration such as 100ms or 2s"` - Limit int `json:"limit,omitempty" clicky:"title=Trace limit,desc=Maximum traces (1 to 1000); spans of a trace stay together"` -} - -type Source struct { - ID string `json:"id"` - Name string `json:"name"` - Type string `json:"type"` -} -type Summary struct { - TraceID string `json:"traceId"` - Operation string `json:"operation"` - Service string `json:"service"` - StartedAt time.Time `json:"startedAt"` - DurationMs float64 `json:"durationMs"` - SpanCount int `json:"spanCount"` - Errors int `json:"errors"` - Services []string `json:"services"` -} -type SearchResult struct { - Traces []Summary `json:"traces"` - Total int `json:"total"` - // Services are those of every trace in the window. - Services []string `json:"services"` - // RootOperations count the traces in the window that pass every filter - // but the operation and span-count ones, by root operation. - RootOperations []OperationStats `json:"rootOperations"` - // Attributes suggest values of those traces' root spans, most frequent first. - Attributes []AttributeCount `json:"attributes"` -} - -// OperationStats are the traces of one root operation. -type OperationStats struct { - Operation string `json:"operation"` - Count int `json:"count"` - // SingleSpan is set when every one of them is a single span. - SingleSpan bool `json:"singleSpan,omitempty"` - P50Ms float64 `json:"p50Ms"` - P95Ms float64 `json:"p95Ms"` -} - -// AttributeCount is how many traces' root spans carry key=value. -type AttributeCount struct { - Value string `json:"value"` - Count int `json:"count"` -} -type Detail struct { - Summary Summary `json:"summary"` - Spans []Span `json:"spans"` - MissingParents []string `json:"missingParents"` -} +type Span = shared.Span +type Request = shared.Request +type DocumentFormat = shared.DocumentFormat +type Source = shared.Source +type Summary = shared.Summary +type SearchResult = shared.SearchResult +type Detail = shared.Detail +type Modes = shared.Modes +type Mode = shared.Mode + +const Include = shared.Include +const Exclude = shared.Exclude +const maxSpans = 100000 + +var ErrTraceNotFound = shared.ErrTraceNotFound type Service struct { DataDir string diff --git a/pkg/credentials/apitoken/token.go b/pkg/credentials/apitoken/token.go index 8789824..3674c7f 100644 --- a/pkg/credentials/apitoken/token.go +++ b/pkg/credentials/apitoken/token.go @@ -45,22 +45,25 @@ const ( // ScopeAPI authorizes the HTTP API. ScopeAPI Scope = "api" ScopeAgent Scope = "agent" + ScopeProxy Scope = "proxy" ) // ParseScope validates a scope selector, naming the alternatives. func ParseScope(value string) (Scope, error) { switch scope := Scope(strings.ToLower(strings.TrimSpace(value))); scope { - case ScopeGit, ScopeAPI, ScopeAgent: + case ScopeGit, ScopeAPI, ScopeAgent, ScopeProxy: return scope, nil case "": - return "", fmt.Errorf("a token scope is required; want one of: %s, %s, %s", ScopeGit, ScopeAPI, ScopeAgent) + return "", fmt.Errorf("a token scope is required; want one of: %s, %s, %s, %s", ScopeGit, ScopeAPI, ScopeAgent, ScopeProxy) default: - return "", fmt.Errorf("invalid token scope %q; want one of: %s, %s, %s", value, ScopeGit, ScopeAPI, ScopeAgent) + return "", fmt.Errorf("invalid token scope %q; want one of: %s, %s, %s, %s", value, ScopeGit, ScopeAPI, ScopeAgent, ScopeProxy) } } // Valid reports whether s names a scope. -func (s Scope) Valid() bool { return s == ScopeGit || s == ScopeAPI || s == ScopeAgent } +func (s Scope) Valid() bool { + return s == ScopeGit || s == ScopeAPI || s == ScopeAgent || s == ScopeProxy +} // nameRe is the shape a token name must take. It is the §3.2 ref-segment shape // deliberately, not by coincidence: a git-scoped token's name becomes an agent diff --git a/pkg/credentials/apitoken/verify.go b/pkg/credentials/apitoken/verify.go index 234ca78..f2d59ca 100644 --- a/pkg/credentials/apitoken/verify.go +++ b/pkg/credentials/apitoken/verify.go @@ -31,6 +31,7 @@ type Record struct { Pool bool PoolAgents []string MaxAgents int + Endpoints []string ExpiresAt *time.Time RevokedAt *time.Time } diff --git a/webapp/src/main.tsx b/webapp/src/main.tsx index 6a1d0f3..9d99db1 100644 --- a/webapp/src/main.tsx +++ b/webapp/src/main.tsx @@ -2,8 +2,8 @@ import { StrictMode } from "react"; import { createRoot } from "react-dom/client"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { DensityProvider, ThemeProvider } from "@flanksource/clicky-ui/hooks"; -import "@flanksource/clicky-ui/styles.css"; import "./styles.css"; +import "@flanksource/clicky-ui/styles.css"; import App from "./App"; const root = document.getElementById("root"); diff --git a/webapp/src/otel/OperationList.tsx b/webapp/src/otel/OperationList.tsx deleted file mode 100644 index c3473d8..0000000 --- a/webapp/src/otel/OperationList.tsx +++ /dev/null @@ -1,44 +0,0 @@ -import type { ReactNode } from "react"; -import { duration, type OperationStats } from "./api"; -import { shortOperation } from "./query"; - -/** The root operations of the window with their counts and p50/p95; choosing one filters to it, "All operations" clears it. */ -export function OperationList({ stats, selected, onSelect, hideSingle }: { - stats: OperationStats[]; - /** The one root operation included, "" for none, undefined for any other selection. */ - selected: string | undefined; - onSelect: (operation: string) => void; - hideSingle: boolean; -}) { - const total = stats.reduce((sum, stat) => sum + stat.count, 0); - const item = (operation: string, label: string, body: ReactNode, dim = false) => ( -
  • - -
  • - ); - return ( - - ); -} diff --git a/webapp/src/otel/OtelPage.test.tsx b/webapp/src/otel/OtelPage.test.tsx index 937bf5a..b50b36b 100644 --- a/webapp/src/otel/OtelPage.test.tsx +++ b/webapp/src/otel/OtelPage.test.tsx @@ -128,7 +128,7 @@ describe("trace search", () => { renderPage(); fireEvent.click(await screen.findByRole("link", { name: /POST \/orders/ })); expect(await screen.findByText("charge")).toBeInTheDocument(); - fireEvent.click(screen.getByRole("button", { name: "Inspect charge" })); + fireEvent.click(screen.getByRole("button", { name: /charge.*40 ms/ })); expect(await screen.findByText("http.status_code")).toBeInTheDocument(); fireEvent.click(screen.getByRole("button", { name: "OpenTelemetry metadata" })); fireEvent.click(screen.getByRole("button", { name: "Expand value" })); diff --git a/webapp/src/otel/OtelPage.tsx b/webapp/src/otel/OtelPage.tsx index 8b471ab..94b7c4b 100644 --- a/webapp/src/otel/OtelPage.tsx +++ b/webapp/src/otel/OtelPage.tsx @@ -1,6 +1,5 @@ -import { useEffect, useState, type FormEvent } from "react"; +import { useEffect, useState } from "react"; import { keepPreviousData, useQuery, useQueryClient } from "@tanstack/react-query"; -import { Button, SearchInput } from "@flanksource/clicky-ui/components"; import { useRouter } from "@flanksource/clicky-ui/rpc"; import { fetchForm, @@ -10,52 +9,22 @@ import { fetchTraces, readSearchValues, searchParams, - type Modes, type SearchValues, type Source, } from "./api"; -import { OperationList } from "./OperationList"; -import { QueryBar } from "./QueryBar"; -import { durationOf, isTraceId, MULTI_SPAN } from "./query"; -import { TraceDetail } from "./TraceDetail"; -import { ResultSummary, ResultTable, Scatter } from "./TraceResults"; - -/** The one root operation included, "" for none, undefined for any other selection. */ -function singleOperation(operations: Modes = {}): string | undefined { - const keys = Object.keys(operations); - if (keys.length === 0) return ""; - return keys.length === 1 && operations[keys[0]!] === "include" ? keys[0] : undefined; -} - -function PendingBanner({ since, onCancel }: { since: number; onCancel: () => void }) { - const [now, setNow] = useState(Date.now()); - useEffect(() => { - const timer = setInterval(() => setNow(Date.now()), 100); - return () => clearInterval(timer); - }, []); - return ( -
    - - Searching… {((now - since) / 1000).toFixed(1)} s - - -
    - ); -} - -/** When the search in flight started, while one is. */ -function useFetchingSince(fetching: boolean): number | undefined { - const [since, setSince] = useState(); - useEffect(() => setSince(fetching ? Date.now() : undefined), [fetching]); - return fetching ? since ?? Date.now() : undefined; -} +import { OtelTraceSearch, OtelTraceDetail as TraceDetail } from "@flanksource/clicky-ui/data"; +import { otelDurationOf as durationOf } from "@flanksource/clicky-ui/data"; function TraceSearch({ sources, traceId, initial }: { sources: Source[]; traceId?: string; initial: SearchValues }) { const { navigate, renderLink } = useRouter(); const client = useQueryClient(); const [value, setValue] = useState(initial); - const [notice, setNotice] = useState(); - const [jumpId, setJumpId] = useState(""); + const [selectedSpan, setSelectedSpan] = useState(() => new URLSearchParams(window.location.search).get("span")); + useEffect(() => { + const restore = () => { setSelectedSpan(new URLSearchParams(window.location.search).get("span")); setValue({ ...initial, ...readSearchValues() }); }; + window.addEventListener("popstate", restore); + return () => window.removeEventListener("popstate", restore); + }, [initial]); const runs = useQuery({ queryKey: ["otel-span-runs"], queryFn: fetchSpanRuns, enabled: !traceId, retry: false }); const search = useQuery({ queryKey: ["otel-search", value], @@ -70,20 +39,13 @@ function TraceSearch({ sources, traceId, initial }: { sources: Source[]; traceId enabled: !!traceId, retry: false, }); - const since = useFetchingSince(search.isFetching); const update = (next: Partial) => { const merged = { ...value, ...next }; setValue(merged); - setNotice(undefined); navigate(`/otel?${searchParams(merged)}`, { replace: true }); }; const href = (id: string) => `/otel/${encodeURIComponent(id)}?${searchParams(value)}`; const open = (id: string) => navigate(href(id)); - const jump = (event: FormEvent) => { - event.preventDefault(); - if (!isTraceId(jumpId)) return setNotice("A trace ID is 16 or 32 hex characters."); - open(jumpId.trim().toLowerCase()); - }; if (traceId) return ( @@ -91,64 +53,10 @@ function TraceSearch({ sources, traceId, initial }: { sources: Source[]; traceId {renderLink({ to: `/otel?${searchParams(value)}`, children: "Back to trace search", className: "text-sm underline" })} {detail.isPending &&

    Loading trace…

    } {detail.error &&

    {detail.error.message}

    } - {detail.data && } + {detail.data && { setSelectedSpan(id); const params = new URLSearchParams(window.location.search); params.set("span", id); navigate(`/otel/${encodeURIComponent(traceId)}?${params}`, { replace: true }); }} />} ); - const result = search.data; - const cancelled = search.isPlaceholderData && !search.isFetching; - return ( -
    -
    -

    Traces

    -
    - - - -
    - - {runs.error &&

    Could not list runs: {runs.error.message}

    } - {notice &&

    {notice}

    } - {search.error && ( -
    -

    {search.error.message}

    - -
    - )} - {cancelled && ( -

    - Search cancelled. These results are from the previous filters. - -

    - )} -
    - {result && ( -
    - update({ - operations: operation ? { [operation]: "include" } : {}, - // A single-span operation has nothing to show while single-span traces are hidden. - ...(result.rootOperations.find(stat => stat.operation === operation)?.singleSpan ? { minSpans: undefined } : {}), - })} - hideSingle={(value.minSpans ?? 0) >= MULTI_SPAN} - /> -
    - )} -
    - {since !== undefined && void client.cancelQueries({ queryKey: ["otel-search", value] })} />} - {!result && search.isPending &&

    Searching traces…

    } - {result && ( -
    - - {result.traces.length > 0 && } - -
    - )} -
    -
    -
    - ); + return void client.cancelQueries({ queryKey: ["otel-search", value] })} onRetry={() => void search.refetch()} />; } export default function OtelPage({ traceId }: { traceId?: string }) { diff --git a/webapp/src/otel/QueryBar.tsx b/webapp/src/otel/QueryBar.tsx deleted file mode 100644 index 5bebf49..0000000 --- a/webapp/src/otel/QueryBar.tsx +++ /dev/null @@ -1,87 +0,0 @@ -import { FilterBar, SegmentedControl, type FilterBarFilter, type FilterBarMultiFilter } from "@flanksource/clicky-ui/components"; -import type { ModeFilter, Modes, SearchResult, SearchValues, Source } from "./api"; -import { durationOf, durationRequest, MULTI_SPAN, rangeOf, shortOperation, windowOf } from "./query"; - -export const RECEIVER_RUN = "receiver"; - -/** The source switch's choice: received spans (the receiver run), recorded spans, or a connection. */ -export function sourceChoice(value: SearchValues): string { - const source = value.source ?? "records"; - return source !== "records" ? source : value.run === RECEIVER_RUN ? "received" : "records"; -} - -function chooseSource(choice: string): SearchValues { - if (choice === "received") return { source: "records", run: RECEIVER_RUN, index: undefined, format: undefined }; - return { source: choice, run: undefined, index: undefined, format: undefined }; -} - -/** Options for a filter, keeping its selected values listed while the result that suggests them loads. */ -function withSelected(options: { value: string; label: string; description?: string }[], selected: Modes | undefined) { - const listed = new Set(options.map(option => option.value)); - return [...options, ...Object.keys(selected ?? {}).filter(value => !listed.has(value)).map(value => ({ value, label: value }))]; -} - -/** One line of trace filters: source, services, root operations, attributes, status, duration, span count and the time window. */ -export function QueryBar({ value, onChange, onError, sources, runs, result }: { - value: SearchValues; - onChange: (next: Partial) => void; - onError: (message: string) => void; - sources: Source[]; - runs: string[]; - result?: SearchResult; -}) { - const choice = sourceChoice(value); - const connection = sources.find(source => source.id === value.source && source.id !== "records"); - const multi = (key: ModeFilter, label: string, options: { value: string; label: string; description?: string }[], extra: Partial = {}): FilterBarMultiFilter => ({ - ...extra, key, kind: "multi", label, value: value[key] ?? {}, onChange: next => onChange({ [key]: next }), options: withSelected(options, value[key]), - }); - const filters: FilterBarFilter[] = [ - multi("services", "Service", (result?.services ?? []).map(service => ({ value: service, label: service }))), - multi("operations", "Root operation", (result?.rootOperations ?? []).map(({ operation }) => ({ - value: operation, label: shortOperation(operation), ...(operation !== shortOperation(operation) ? { description: operation } : {}), - }))), - multi("attributes", "Attributes", (result?.attributes ?? []).map(({ value: expr, count }) => ({ value: expr, label: expr, description: `${count} traces` })), { - allowCustomValue: true, placeholder: "key=value", description: "Any span's attribute: key=value, key=prefix*, or a bare key to match its presence.", - }), - multi("statuses", "Status", [{ value: "ok", label: "OK" }, { value: "error", label: "Error" }]), - { key: "duration", kind: "duration", label: "Duration", value: durationOf(value), onChange: next => onChange(durationRequest(next)), unit: "s" }, - { key: "hide-single", kind: "boolean", label: "Hide single-span traces", value: (value.minSpans ?? 0) >= MULTI_SPAN, onChange: hide => onChange({ minSpans: hide ? MULTI_SPAN : undefined }) }, - ]; - if (choice === "records") filters.push({ - key: "run", kind: "enum", label: "Run", value: value.run ?? "", onChange: run => onChange({ run: run || undefined }), - options: [{ value: "", label: "Every run" }, ...runs.filter(run => run !== RECEIVER_RUN).map(run => ({ value: run }))], - }); - if (connection) filters.push( - { key: "index", kind: "text", label: "Index", value: value.index ?? "", onChange: index => onChange({ index: index || undefined }), placement: "overflow" }, - { key: "format", kind: "enum", label: "Document format", value: value.format ?? "", onChange: format => onChange({ format: format || undefined }), options: [{ value: "", label: "Connection default" }, { value: "flat" }, { value: "jaeger" }], placement: "overflow" }, - ); - const range = rangeOf(value); - return ( - onChange(chooseSource(next))} - options={[ - ...(runs.includes(RECEIVER_RUN) ? [{ id: "received", label: "Received" }] : []), - { id: "records", label: "Recorded" }, - ...sources.filter(source => source.id !== "records").map(source => ({ id: source.id, label: source.name })), - ]} - /> - } - filters={filters} - timeRange={{ - from: range.from, to: range.to, timeEnabled: true, emptyLabel: "Last hour", - onApply: (from, to) => { - try { - onChange(windowOf(from, to, Date.now())); - } catch (error) { - onError(error instanceof Error ? error.message : String(error)); - } - }, - }} - /> - ); -} diff --git a/webapp/src/otel/TraceDetail.tsx b/webapp/src/otel/TraceDetail.tsx deleted file mode 100644 index cfb63e5..0000000 --- a/webapp/src/otel/TraceDetail.tsx +++ /dev/null @@ -1,201 +0,0 @@ -import { useMemo, useState } from "react"; -import { Button, Panel, Section } from "@flanksource/clicky-ui/components"; -import { - CodeBlock, - DataTable, - Properties, - type DataTableColumn, -} from "@flanksource/clicky-ui/data"; -import { duration, type Trace } from "./api"; -import { spanRows, type SpanRow } from "./model"; - -export function TraceDetail({ trace }: { trace: Trace }) { - const [collapsed, setCollapsed] = useState(new Set()); - const [selected, setSelected] = useState( - () => - new URLSearchParams(window.location.search).get("span") ?? - trace.spans[0]?.spanId, - ); - const selectSpan = (id: string) => { - setSelected(id); - const params = new URLSearchParams(window.location.search); - params.set("span", id); - window.history.replaceState( - null, - "", - `${window.location.pathname}?${params}`, - ); - }; - const rows = useMemo( - () => spanRows(trace.spans, collapsed), - [trace.spans, collapsed], - ); - const span = trace.spans.find((span) => span.spanId === selected); - const start = Date.parse(trace.summary.startedAt); - const total = trace.summary.durationMs; - const columns: DataTableColumn[] = [ - { - key: "operation", - label: "Service / operation", - sortable: false, - render: (_, row) => ( -
    - {row.hasChildren ? ( - - ) : ( - - )} - -
    - ), - }, - { - key: "durationMs", - label: "Duration", - sortable: false, - render: (_, row) => duration(row.durationMs), - }, - { key: "status", label: "Status", sortable: false }, - { - key: "timeline", - label: `Timeline · ${duration(total)}`, - sortable: false, - render: (_, row) => { - const left = total - ? Math.max(0, ((Date.parse(row.startedAt) - start) / total) * 100) - : 0; - const width = total ? (row.durationMs / total) * 100 : 0; - return ( - - ); - }, - }, - ]; - return ( -
    - -

    {trace.summary.traceId}

    -

    - {duration(total)} · {trace.spans.length} spans ·{" "} - {trace.summary.services.length} services · {trace.summary.errors}{" "} - errors · {new Date(trace.summary.startedAt).toLocaleString()} -

    -
    - {trace.missingParents.length > 0 && ( -

    - Partial trace: {trace.missingParents.length} parent spans are missing - from this source. -

    - )} -
    - - -
    - row.spanId} - autoFilter={false} - onRowClick={(row) => selectSpan(row.spanId)} - className="min-h-48" - /> - {span && ( - -
    - -

    Span attributes

    - key} - items={Object.entries(span.attributes ?? {}).map( - ([key, value]) => ({ key, value }), - )} - /> -

    Resource attributes

    - key} - items={Object.entries(span.resource ?? {}).map( - ([key, value]) => ({ key, value }), - )} - /> - {span.otlp && ( -
    - -
    - )} -
    -
    - )} -
    - ); -} diff --git a/webapp/src/otel/TraceResults.test.tsx b/webapp/src/otel/TraceResults.test.tsx deleted file mode 100644 index c7be4c5..0000000 --- a/webapp/src/otel/TraceResults.test.tsx +++ /dev/null @@ -1,19 +0,0 @@ -import { expect, it } from "vitest"; -import { ago, niceStep } from "./TraceResults"; - -it.each([ - [4_000, "4s ago"], - [125_000, "2m ago"], - [7_200_000, "2h ago"], - [172_800_000, "2d ago"], -])("reads %d ms as %s", (ms, text) => { - expect(ago(ms)).toBe(text); -}); - -it.each([ - [7_300, 4, 2_000], - [100, 4, 50], - [0.9, 4, 0.5], -])("steps an axis of %d into about %d round steps of %d", (total, ticks, step) => { - expect(niceStep(total, ticks)).toBeCloseTo(step); -}); diff --git a/webapp/src/otel/TraceResults.tsx b/webapp/src/otel/TraceResults.tsx deleted file mode 100644 index c10b4c0..0000000 --- a/webapp/src/otel/TraceResults.tsx +++ /dev/null @@ -1,135 +0,0 @@ -import { Badge, DataTable, type DataTableColumn } from "@flanksource/clicky-ui/data"; -import { duration, type SearchResult, type Summary } from "./api"; -import { shortOperation } from "./query"; - -const startMs = (trace: Summary) => Date.parse(trace.startedAt); -const clock = (ms: number) => new Date(ms).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }); - -/** How long ago, in the largest whole unit up to days. */ -export function ago(ms: number): string { - const units: [number, string][] = [[86_400_000, "d"], [3_600_000, "h"], [60_000, "m"]]; - const [size, unit] = units.find(([size]) => ms >= size) ?? [1000, "s"]; - return `${Math.max(0, Math.round(ms / size))}${unit} ago`; -} - -/** A round axis step that splits total into about ticks steps. */ -export function niceStep(total: number, ticks: number): number { - const raw = total / ticks; - const power = 10 ** Math.floor(Math.log10(raw)); - return [1, 2, 5, 10].map(multiple => multiple * power).find(step => step >= raw)!; -} - -export function ResultSummary({ result }: { result: SearchResult }) { - const shown = result.traces.length; - return ( -

    - {shown} {shown === 1 ? "trace" : "traces"} - {shown < result.total - ? <> · the {shown} newest of {result.total.toLocaleString()}. Narrow the window or operation to see older ones - : <> · all in the window} -

    - ); -} - -/** Each trace by when it started and how long it took, dot size by span count. */ -export function Scatter({ traces, onOpen }: { traces: Summary[]; onOpen: (id: string) => void }) { - const starts = traces.map(startMs); - const t0 = Math.min(...starts); - const span = Math.max(...starts) - t0; - const slowest = Math.max(...traces.map(trace => trace.durationMs)) || 1; - const step = niceStep(slowest, 4); - const top = Math.ceil((slowest * 1.05) / step) * step; - const yTicks = Array.from({ length: Math.round(top / step) + 1 }, (_, i) => i * step); - // Traces that all started together sit mid-axis under one tick. - const xTicks = span === 0 ? [0.5] : [0, 0.25, 0.5, 0.75, 1]; - const x = (ms: number) => (span === 0 ? 0.5 : (ms - t0) / span); - return ( -
    -
    - Duration over time - dot size = span count · click to open -
    -
    - {yTicks.map(y => ( -
    - {y === 0 ? "0" : duration(y)} -
    - ))} - {traces.map(trace => { - const size = 6 + Math.log2(trace.spanCount) * 1.6; - const label = `${shortOperation(trace.operation)}, ${duration(trace.durationMs)}, ${trace.spanCount} spans at ${clock(startMs(trace))}`; - return ( -
    -
    - {xTicks.map((fraction, i) => ( - 1 && i === 0 ? "" : xTicks.length > 1 && i === xTicks.length - 1 ? "-translate-x-full" : "-translate-x-1/2"}`} style={{ left: `${fraction * 100}%` }}> - {clock(t0 + fraction * span)} - - ))} -
    -
    - ); -} - -/** The traces, newest first: what ran, when, how long against the slowest, and its span count. */ -export function ResultTable({ traces, href, onOpen, now }: { traces: Summary[]; href: (id: string) => string; onOpen: (id: string) => void; now: number }) { - const slowest = Math.max(1, ...traces.map(trace => trace.durationMs)); - const columns: DataTableColumn[] = [ - { - key: "operation", - label: "Trace", - grow: true, - minWidth: 320, - render: (_, trace) => ( - - {shortOperation(trace.operation) || trace.traceId} - {trace.traceId.slice(0, 8)} - {trace.services.length > 1 && {trace.services.join(" → ")}} - {trace.errors > 0 && {trace.errors} {trace.errors === 1 ? "error" : "errors"}} - - ), - }, - { - key: "startedAt", - label: "Started", - render: (_, trace) => {clock(startMs(trace))} {ago(now - startMs(trace))}, - }, - { - key: "durationMs", - label: "Duration", - render: (_, trace) => ( - - - - - {duration(trace.durationMs)} - - ), - }, - { key: "spanCount", label: "Spans", align: "right" }, - ]; - return ( -
    - trace.traceId} - autoFilter={false} - getRowHref={trace => href(trace.traceId)} - onRowClick={trace => onOpen(trace.traceId)} - emptyMessage="No traces match. Widen the time range, clear the duration or attribute filters, or show single-span traces." - /> -
    - ); -} diff --git a/webapp/src/otel/api.ts b/webapp/src/otel/api.ts index 6b9cf57..8f08ff9 100644 --- a/webapp/src/otel/api.ts +++ b/webapp/src/otel/api.ts @@ -1,140 +1,11 @@ -import type { JsonSchemaObject } from "@flanksource/clicky-ui/components"; import { fetchJSON } from "@flanksource/clicky-ui/profiles"; +import { otelSearchParams as searchParams } from "@flanksource/clicky-ui/data"; +import type { OtelSearchValues as SearchValues, OtelSearchResult as SearchResult, OtelTrace as Trace, OtelSource as Source, OtelSearchForm as SearchForm } from "@flanksource/clicky-ui/data"; +export { otelSearchParams as searchParams, readOtelSearchValues as readSearchValues } from "@flanksource/clicky-ui/data"; +export type { OtelSearchValues as SearchValues, OtelSearchResult as SearchResult, OtelTrace as Trace, OtelSource as Source, OtelSearchForm as SearchForm } from "@flanksource/clicky-ui/data"; -export type Span = { - traceId: string; - spanId: string; - parentId?: string; - service: string; - operation: string; - kind?: string; - startedAt: string; - durationMs: number; - status: string; - attributes?: Record; - resource?: Record; - otlp?: Record; -}; -export type Summary = { - traceId: string; - service: string; - operation: string; - startedAt: string; - durationMs: number; - spanCount: number; - errors: number; - services: string[]; -}; -export interface Trace { - summary: Summary; - spans: Span[]; - missingParents: string[]; -} -/** The traces of one root operation in the window (tracequery.OperationStats). */ -export interface OperationStats { - operation: string; - count: number; - singleSpan?: boolean; - p50Ms: number; - p95Ms: number; -} -export interface SearchResult { - traces: Summary[]; - total: number; - services: string[]; - /** Every filter but the operation and span-count ones applied, by root operation. */ - rootOperations: OperationStats[]; - /** key=value suggestions from those traces' root spans, most frequent first. */ - attributes: { value: string; count: number }[]; -} -export interface Source { - id: string; - name: string; - type: string; -} -/** A filter's values, each included or excluded (tracequery.Modes). */ -export type Modes = Record; -export const MODE_FILTERS = ["services", "operations", "statuses", "attributes"] as const; -export type ModeFilter = (typeof MODE_FILTERS)[number]; -export type SearchValues = Record & { - source?: string; - run?: string; - index?: string; - format?: string; - services?: Modes; - /** Root operations. */ - operations?: Modes; - statuses?: Modes; - /** key, key=value or key=prefix* expressions. */ - attributes?: Modes; - minSpans?: number; - traceId?: string; - lookback?: string; - from?: string; - until?: string; - minDuration?: string; - maxDuration?: string; - limit?: number; -}; -export interface SearchForm { - schema: JsonSchemaObject; - defaults: SearchValues; -} export const fetchSources = () => fetchJSON("/api/otel/sources"); export const fetchForm = () => fetchJSON("/api/otel/form"); -// fetchSpanRuns are the runs a recorded-trace search can select: command runs -// that captured spans, then standing stores such as the OTLP receiver. -export const fetchSpanRuns = () => - fetchJSON<{ runs: { runId: string }[] }>("/api/traces?kind=spans").then( - ({ runs }) => runs.map((run) => run.runId), - ); - -export function searchParams(value: SearchValues): URLSearchParams { - const params = new URLSearchParams(); - for (const [key, item] of Object.entries(value)) - if ( - item !== undefined && item !== null && item !== "" && - !(typeof item === "object" && Object.keys(item).length === 0) - ) - params.set( - key, - typeof item === "object" ? JSON.stringify(item) : String(item), - ); - return params; -} - -function parseModes(key: string, text: string): Modes { - const value: unknown = JSON.parse(text); - if (!value || typeof value !== "object" || Array.isArray(value) || Object.values(value).some(mode => mode !== "include" && mode !== "exclude")) - throw new Error(`${key} must be a JSON object of values to include or exclude`); - return value as Modes; -} - -export function readSearchValues(): SearchValues { - const params = new URLSearchParams(window.location.search); - const result: SearchValues = {}; - for (const [key, value] of params) { - if (key === "span") continue; - if ((MODE_FILTERS as readonly string[]).includes(key)) result[key] = parseModes(key, value); - else if (key === "limit" || key === "minSpans") { - if (!/^\d+$/.test(value)) throw new Error(`${key} must be a whole number, not ${JSON.stringify(value)}`); - result[key] = Number(value); - } else result[key] = value; - } - return result; -} - -export const fetchTraces = (value: SearchValues, signal?: AbortSignal) => - fetchJSON(`/api/otel?${searchParams(value)}`, signal ? { signal } : undefined); -export const fetchTrace = (value: SearchValues, id: string) => - fetchJSON( - `/api/otel/trace/${encodeURIComponent(id)}?${searchParams({ source: value.source, run: value.run, index: value.index, format: value.format })}`, - ); -export const duration = (ms: number) => - ms >= 1000 - ? `${(ms / 1000).toFixed(2)} s` - : ms >= 10 - ? `${ms.toFixed(0)} ms` - : ms >= 1 - ? `${ms.toFixed(1)} ms` - : `${(ms * 1000).toFixed(0)} µs`; +export const fetchSpanRuns = () => fetchJSON<{ runs: { runId: string }[] }>("/api/traces?kind=spans").then(({ runs }) => runs.map(run => run.runId)); +export const fetchTraces = (value: SearchValues, signal?: AbortSignal) => fetchJSON(`/api/otel?${searchParams(value)}`, signal ? { signal } : undefined); +export const fetchTrace = (value: SearchValues, id: string) => fetchJSON(`/api/otel/trace/${encodeURIComponent(id)}?${searchParams({source:value.source,run:value.run,index:value.index,format:value.format})}`); diff --git a/webapp/src/otel/model.test.tsx b/webapp/src/otel/model.test.tsx deleted file mode 100644 index 03e037a..0000000 --- a/webapp/src/otel/model.test.tsx +++ /dev/null @@ -1,44 +0,0 @@ -import { describe, expect, it } from "vitest"; -import { spanRows } from "./model"; -import type { Span } from "./api"; - -const span = (id: string, parentId = ""): Span => ({ - traceId: "trace", - spanId: id, - parentId, - service: "checkout", - operation: id, - startedAt: "2026-10-29T10:00:00Z", - durationMs: 10, - status: "ok", -}); - -describe("trace waterfall rows", () => { - it("keeps children under their parents and preserves missing-parent roots", () => { - expect( - spanRows( - [span("child", "root"), span("orphan", "absent"), span("root")], - new Set(), - ).map((row) => [row.spanId, row.depth]), - ).toEqual([ - ["orphan", 0], - ["root", 0], - ["child", 1], - ]); - }); - it("collapses descendants without removing their parent", () => { - expect( - spanRows([span("root"), span("child", "root")], new Set(["root"])).map( - (row) => row.spanId, - ), - ).toEqual(["root"]); - }); - it("refuses cycles and duplicate identities", () => { - expect(() => - spanRows([span("root", "child"), span("child", "root")], new Set()), - ).toThrow(/cycle/); - expect(() => spanRows([span("root"), span("root")], new Set())).toThrow( - /duplicate/, - ); - }); -}); diff --git a/webapp/src/otel/model.ts b/webapp/src/otel/model.ts deleted file mode 100644 index 66f9822..0000000 --- a/webapp/src/otel/model.ts +++ /dev/null @@ -1,46 +0,0 @@ -import type { Span } from "./api"; - -export type SpanRow = Span & { depth: number; hasChildren: boolean }; - -export function spanRows(spans: Span[], collapsed: Set): SpanRow[] { - const nodes = new Map(); - for (const span of spans) { - if (nodes.has(span.spanId)) - throw new Error(`duplicate span ${span.spanId}`); - nodes.set(span.spanId, span); - } - const children = new Map(); - for (const span of spans) { - const parent = nodes.has(span.parentId ?? "") ? span.parentId! : ""; - children.set(parent, [...(children.get(parent) ?? []), span]); - } - const order = (a: Span, b: Span) => - Date.parse(a.startedAt) - Date.parse(b.startedAt) || - a.spanId.localeCompare(b.spanId); - for (const siblings of children.values()) siblings.sort(order); - const pending = [...(children.get("") ?? [])] - .reverse() - .map((span) => ({ span, depth: 0, visible: true })); - const rows: SpanRow[] = []; - const seen = new Set(); - while (pending.length) { - const current = pending.pop()!; - if (seen.has(current.span.spanId)) throw new Error("span parent cycle"); - seen.add(current.span.spanId); - const nested = children.get(current.span.spanId) ?? []; - if (current.visible) - rows.push({ - ...current.span, - depth: current.depth, - hasChildren: nested.length > 0, - }); - for (const span of [...nested].reverse()) - pending.push({ - span, - depth: current.depth + 1, - visible: current.visible && !collapsed.has(current.span.spanId), - }); - } - if (seen.size !== spans.length) throw new Error("span parent cycle"); - return rows; -} diff --git a/webapp/src/otel/query.test.tsx b/webapp/src/otel/query.test.tsx deleted file mode 100644 index 31567b6..0000000 --- a/webapp/src/otel/query.test.tsx +++ /dev/null @@ -1,60 +0,0 @@ -import { describe, expect, it } from "vitest"; -import { durationOf, durationRequest, isTraceId, rangeOf, shortOperation, windowOf } from "./query"; - -const now = Date.parse("2026-10-29T10:00:00Z"); - -describe("the time range", () => { - it.each([ - [{ lookback: "1h" }, { from: "now-1h", to: "now" }], - [{}, { from: "", to: "now" }], - [{ from: "2026-10-29T09:00:00Z" }, { from: "2026-10-29T09:00:00Z", to: "now" }], - [{ from: "2026-10-29T09:00:00Z", until: "2026-10-29T09:30:00Z", lookback: "1h" }, { from: "2026-10-29T09:00:00Z", to: "2026-10-29T09:30:00Z" }], - ])("shows the request %j as %j", (request, range) => { - expect(rangeOf(request)).toEqual(range); - }); - - it.each([ - ["now-15m", "now", { lookback: "15m" }], - ["now-7d", "now", { lookback: "168h" }], - ["now-1M", "", { lookback: "720h" }], - ["", "now", { lookback: undefined }], - ["now-2h", "now-1h", { from: "2026-10-29T08:00:00.000Z", until: "2026-10-29T09:00:00.000Z" }], - ["2026-10-29T08:30:00Z", "now", { from: "2026-10-29T08:30:00.000Z", until: undefined }], - ])("requests %s → %s as %j", (from, to, window) => { - expect(windowOf(from, to, now)).toEqual({ lookback: undefined, from: undefined, until: undefined, ...window }); - }); - - it("refuses a time it cannot read", () => { - expect(() => windowOf("yesterday", "now", now)).toThrow(/Could not read the time "yesterday"/); - }); -}); - -describe("the duration range", () => { - it("round-trips bounds through the request", () => { - const control = durationOf({ minDuration: "500ms", maxDuration: "2.5s" }); - expect(control).toEqual({ min: "500", minUnit: "ms", max: "2.5", maxUnit: "s" }); - expect(durationRequest(control)).toEqual({ minDuration: "500ms", maxDuration: "2.5s" }); - }); - - it("reads a bare bound in seconds and drops an empty one", () => { - expect(durationRequest({ min: "3", max: " " })).toEqual({ minDuration: "3s", maxDuration: undefined }); - }); - - it("refuses a request duration the control cannot show", () => { - expect(() => durationOf({ minDuration: "1h30m" })).toThrow(/minDuration/); - }); -}); - -it("shortens a prompt path to the prompt's name under prompts/", () => { - expect(shortOperation("invoke_agent /Users/acme/.captain/prompts/jira/classify.prompt")).toBe("invoke_agent jira/classify.prompt"); - expect(shortOperation("POST /orders")).toBe("POST /orders"); -}); - -it.each([ - ["8d7616992490c496e2ca9b9d9db42c7f", true], - ["8d7616992490c496", true], - ["8d76169924", false], - ["zz7616992490c496e2ca9b9d9db42c7f", false], -])("reads %s as a trace ID: %s", (text, valid) => { - expect(isTraceId(text)).toBe(valid); -}); diff --git a/webapp/src/otel/query.ts b/webapp/src/otel/query.ts deleted file mode 100644 index 7654630..0000000 --- a/webapp/src/otel/query.ts +++ /dev/null @@ -1,68 +0,0 @@ -import type { FilterBarDurationUnit, FilterBarDurationValue } from "@flanksource/clicky-ui/components"; -import type { SearchValues } from "./api"; - -// The pure side of the trace search bar: how its time range and duration -// controls map onto the server's request (lookback, from/until and -// minDuration/maxDuration), and how operations read. - -/** The server's minSpans that "Hide single-span traces" sets. */ -export const MULTI_SPAN = 2; - -const RELATIVE = /^now(?:-(\d+)([smhdwMy]))?$/; -const UNIT_HOURS: Record = { d: 24, w: 168, M: 720, y: 8760 }; -const UNIT_MS: Record = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5, M: 2592e6, y: 31536e6 }; - -/** A relative offset as a Go duration: s, m and h as they are, longer units in hours. */ -function goDuration(count: number, unit: string): string { - return unit in UNIT_HOURS ? `${count * UNIT_HOURS[unit]!}h` : `${count}${unit}`; -} - -/** The time range control's value for a request: its lookback as now-, or its from/until as they are. */ -export function rangeOf(value: SearchValues): { from: string; to: string } { - if (value.from || value.until) return { from: value.from ?? "", to: value.until ?? "now" }; - return { from: value.lookback ? `now-${value.lookback}` : "", to: "now" }; -} - -/** An instant of the range control as RFC3339: now-relative against now, or a date-time the browser reads. */ -function instant(text: string, now: number): string { - const relative = RELATIVE.exec(text); - if (relative) return new Date(now - (relative[1] ? Number(relative[1]) * UNIT_MS[relative[2]!]! : 0)).toISOString(); - const parsed = Date.parse(text); - if (Number.isNaN(parsed)) throw new Error(`Could not read the time ${JSON.stringify(text)}: use now, an offset such as now-1h, or a date-time`); - return new Date(parsed).toISOString(); -} - -/** The request's window for a range: a lookback when it ends now and starts now-relative, otherwise from/until as instants. */ -export function windowOf(from: string, to: string, now: number): Pick { - const start = from.trim(); - const end = to.trim() || "now"; - const relative = RELATIVE.exec(start); - if (end === "now" && (!start || (relative && relative[1]))) return { lookback: relative ? goDuration(Number(relative[1]), relative[2]!) : undefined, from: undefined, until: undefined }; - return { lookback: undefined, from: start ? instant(start, now) : undefined, until: end === "now" ? undefined : instant(end, now) }; -} - -const DURATION = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/; - -function bound(text: string | undefined, edge: "min" | "max"): FilterBarDurationValue { - if (!text) return {}; - const match = DURATION.exec(text); - if (!match) throw new Error(`${edge}Duration must be a number of ms, s, m or h, not ${JSON.stringify(text)}`); - return { [edge]: match[1], [`${edge}Unit`]: match[2] as FilterBarDurationUnit }; -} - -/** The duration control's value for a request's minDuration and maxDuration. */ -export function durationOf(value: SearchValues): FilterBarDurationValue { - return { ...bound(value.minDuration, "min"), ...bound(value.maxDuration, "max") }; -} - -/** The request's minDuration and maxDuration for the duration control, a bare bound in seconds. */ -export function durationRequest(value: FilterBarDurationValue): Pick { - const edge = (amount: string | undefined, unit: FilterBarDurationUnit | undefined) => (amount?.trim() ? `${amount.trim()}${unit ?? "s"}` : undefined); - return { minDuration: edge(value.min, value.minUnit), maxDuration: edge(value.max, value.maxUnit) }; -} - -/** `invoke_agent /abs/path/.captain/prompts/jira/x.prompt` reads `invoke_agent jira/x.prompt`. */ -export const shortOperation = (operation: string) => operation.replace(/ \/\S*\/prompts\//, " "); - -/** A W3C (32 hex) or Jaeger 64-bit (16 hex) trace ID. */ -export const isTraceId = (text: string) => /^[0-9a-f]{16}([0-9a-f]{16})?$/i.test(text.trim()); From f46cfb3661397f3464432409a66ae1808a773441 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Tue, 3 Nov 2026 05:39:47 +0200 Subject: [PATCH 02/89] dependency(ci): bump flanksource/deps action to v1.0.50 in CI and release workflows --- .github/workflows/ci.yml | 2 +- .github/workflows/release.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4f9bec0..28630b2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -36,7 +36,7 @@ jobs: with: node-version-file: .node-version cache: pnpm - - uses: flanksource/deps@v1.0.49 + - uses: flanksource/deps@v1.0.50 with: tools: | task diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a2d3cdb..91101e2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -39,7 +39,7 @@ jobs: with: node-version-file: .node-version cache: pnpm - - uses: flanksource/deps@v1.0.49 + - uses: flanksource/deps@v1.0.50 with: tools: | task From 61a1df21bdebe18872e5002be3e9600dddad4d01 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Tue, 3 Nov 2026 05:39:52 +0200 Subject: [PATCH 03/89] feat: add wire protocol decoders and token-scoped proxy endpoint auth Adds passive metadata decoders for AWS, Git, and SFTP wire traffic, which keep signed requests and file or pack contents unmodified. Also adds per-endpoint proxy authorization that checks token scope, endpoint allow-lists, expiry, and revocation on every request, and accepts Basic or Bearer credentials. --- internal/protocol/awswire/decode.go | 119 +++++++++++++++ internal/protocol/awswire/decode_test.go | 57 ++++++++ internal/protocol/gitwire/decoder.go | 161 +++++++++++++++++++++ internal/protocol/gitwire/decoder_test.go | 67 +++++++++ internal/protocol/sftpwire/decoder.go | 156 ++++++++++++++++++++ internal/protocol/sftpwire/decoder_test.go | 40 +++++ internal/tracequery/suite_test.go | 9 ++ pkg/proxy/endpoint/auth.go | 80 ++++++++++ pkg/proxy/endpoint/auth_test.go | 75 ++++++++++ 9 files changed, 764 insertions(+) create mode 100644 internal/protocol/awswire/decode.go create mode 100644 internal/protocol/awswire/decode_test.go create mode 100644 internal/protocol/gitwire/decoder.go create mode 100644 internal/protocol/gitwire/decoder_test.go create mode 100644 internal/protocol/sftpwire/decoder.go create mode 100644 internal/protocol/sftpwire/decoder_test.go create mode 100644 internal/tracequery/suite_test.go create mode 100644 pkg/proxy/endpoint/auth.go create mode 100644 pkg/proxy/endpoint/auth_test.go diff --git a/internal/protocol/awswire/decode.go b/internal/protocol/awswire/decode.go new file mode 100644 index 0000000..e38403e --- /dev/null +++ b/internal/protocol/awswire/decode.go @@ -0,0 +1,119 @@ +package awswire + +import ( + "bytes" + "encoding/json" + "encoding/xml" + "fmt" + "io" + "mime" + "net/http" + "net/url" + "strings" +) + +type Metadata struct { + Service string `json:"service,omitempty"` + Region string `json:"region,omitempty"` + Operation string `json:"operation,omitempty"` + RequestID string `json:"requestId,omitempty"` + ErrorCode string `json:"errorCode,omitempty"` +} + +func Decode(req *http.Request, response *http.Response, requestBody, responseBody []byte) (Metadata, error) { + if req == nil || req.URL == nil { + return Metadata{}, fmt.Errorf("AWS metadata requires a request URL") + } + m := Metadata{} + query, err := url.ParseQuery(req.URL.RawQuery) + if err != nil { + return m, fmt.Errorf("AWS request query: %w", err) + } + credential := query.Get("X-Amz-Credential") + if authorization := req.Header.Get("Authorization"); strings.HasPrefix(authorization, "AWS4-") { + _, rest, found := strings.Cut(authorization, "Credential=") + if !found { + return m, fmt.Errorf("AWS authorization has no credential scope") + } + credential, _, _ = strings.Cut(rest, ",") + } + if credential != "" { + parts := strings.Split(strings.TrimSpace(credential), "/") + if len(parts) != 5 || parts[0] == "" || len(parts[1]) != 8 || parts[2] == "" || parts[3] == "" || parts[4] != "aws4_request" { + return m, fmt.Errorf("invalid AWS credential scope") + } + m.Region, m.Service = parts[2], parts[3] + } + m.Operation = query.Get("Action") + if target := req.Header.Get("X-Amz-Target"); target != "" { + _, operation, ok := strings.Cut(target, ".") + if !ok || operation == "" { + return m, fmt.Errorf("invalid AWS operation target") + } + m.Operation = operation + } + mediaType, _, _ := mime.ParseMediaType(req.Header.Get("Content-Type")) + if mediaType == "application/x-www-form-urlencoded" && len(requestBody) > 0 { + form, err := url.ParseQuery(string(requestBody)) + if err != nil { + return m, fmt.Errorf("AWS query payload: %w", err) + } + m.Operation = form.Get("Action") + } + if response == nil { + return m, nil + } + m.RequestID = response.Header.Get("X-Amzn-Requestid") + if m.RequestID == "" { + m.RequestID = response.Header.Get("X-Amz-Request-Id") + } + if response.StatusCode >= 400 && len(responseBody) > 0 { + if err := m.decodeError(responseBody); err != nil { + return m, err + } + } + return m, nil +} + +func (m *Metadata) decodeError(body []byte) error { + body = bytes.TrimSpace(body) + if len(body) == 0 { + return nil + } + if body[0] == '{' { + var fields struct { + Type string `json:"__type"` + Code string `json:"code"` + } + if err := json.Unmarshal(body, &fields); err != nil { + return fmt.Errorf("AWS JSON error: %w", err) + } + m.ErrorCode = fields.Code + if m.ErrorCode == "" { + _, m.ErrorCode, _ = strings.Cut(fields.Type, "#") + if m.ErrorCode == "" { + m.ErrorCode = fields.Type + } + } + return nil + } + if body[0] != '<' { + return nil + } + d := xml.NewDecoder(bytes.NewReader(body)) + for { + token, err := d.Token() + if err == io.EOF { + return nil + } + if err != nil { + return fmt.Errorf("AWS XML error: %w", err) + } + start, ok := token.(xml.StartElement) + if ok && start.Name.Local == "Code" { + if err := d.DecodeElement(&m.ErrorCode, &start); err != nil { + return fmt.Errorf("AWS XML error code: %w", err) + } + } + } +} diff --git a/internal/protocol/awswire/decode_test.go b/internal/protocol/awswire/decode_test.go new file mode 100644 index 0000000..7c997a4 --- /dev/null +++ b/internal/protocol/awswire/decode_test.go @@ -0,0 +1,57 @@ +package awswire + +import ( + "net/http" + "testing" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestAWS(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "AWS metadata") } + +var _ = Describe("AWS metadata", func() { + It("reads signing scope and JSON operation without modifying signed requests", func() { + req, err := http.NewRequest("POST", "https://service.example.com/path%2Fkey?x=1", nil) + Expect(err).NotTo(HaveOccurred()) + req.Header.Set("Authorization", "AWS4-HMAC-SHA256 Credential=client/20261102/eu-west-1/dynamodb/aws4_request, SignedHeaders=host, Signature=secret") + req.Header.Set("X-Amz-Target", "DynamoDB_20120810.GetItem") + before := req.Clone(req.Context()) + got, err := Decode(req, nil, nil, nil) + Expect(err).NotTo(HaveOccurred()) + Expect(got).To(Equal(Metadata{Service: "dynamodb", Region: "eu-west-1", Operation: "GetItem"})) + Expect(req).To(Equal(before)) + }) + It("reads presigned query scope and query operations", func() { + req, err := http.NewRequest("GET", "https://service.example.com/?X-Amz-Credential=client%2F20261102%2Fus-east-1%2Fsts%2Faws4_request&Action=GetCallerIdentity", nil) + Expect(err).NotTo(HaveOccurred()) + got, err := Decode(req, nil, nil, nil) + Expect(err).NotTo(HaveOccurred()) + Expect(got).To(Equal(Metadata{Service: "sts", Region: "us-east-1", Operation: "GetCallerIdentity"})) + }) + It("reads form operations and XML errors", func() { + req, err := http.NewRequest("POST", "https://service.example.com/", nil) + Expect(err).NotTo(HaveOccurred()) + req.Header.Set("Content-Type", "application/x-www-form-urlencoded; charset=utf-8") + resp := &http.Response{StatusCode: 403, Header: http.Header{"X-Amzn-Requestid": []string{"request-1"}}} + got, err := Decode(req, resp, []byte("Action=DescribeInstances&Version=2016-11-15"), []byte("Denied")) + Expect(err).NotTo(HaveOccurred()) + Expect(got).To(Equal(Metadata{Operation: "DescribeInstances", RequestID: "request-1", ErrorCode: "Denied"})) + }) + It("does not invent REST operation names", func() { + req, err := http.NewRequest("GET", "https://bucket.s3.us-east-1.amazonaws.com/object", nil) + Expect(err).NotTo(HaveOccurred()) + got, err := Decode(req, nil, nil, nil) + Expect(err).NotTo(HaveOccurred()) + Expect(got.Operation).To(BeEmpty()) + }) + It("reports malformed signing scopes and structured payloads", func() { + req, err := http.NewRequest("GET", "https://service.example.com/?X-Amz-Credential=broken", nil) + Expect(err).NotTo(HaveOccurred()) + _, err = Decode(req, nil, nil, nil) + Expect(err).To(HaveOccurred()) + req.URL.RawQuery = "" + _, err = Decode(req, &http.Response{StatusCode: 400, Header: http.Header{"Content-Type": []string{"application/json"}}}, nil, []byte("{")) + Expect(err).To(HaveOccurred()) + }) +}) diff --git a/internal/protocol/gitwire/decoder.go b/internal/protocol/gitwire/decoder.go new file mode 100644 index 0000000..777adc9 --- /dev/null +++ b/internal/protocol/gitwire/decoder.go @@ -0,0 +1,161 @@ +package gitwire + +import ( + "errors" + "fmt" + "strconv" + "strings" +) + +var ErrIncomplete = errors.New("incomplete git packet") + +type Event struct { + Kind string `json:"kind"` + Text string `json:"text,omitempty"` + Bytes int `json:"bytes,omitempty"` +} + +type Decoder struct { + Emit func(Event) + buf []byte + pack bool + err error +} + +func (d *Decoder) Write(p []byte) (int, error) { + if d.err != nil { + return 0, d.err + } + for consumed := 0; consumed < len(p); { + if d.pack { + d.emit(Event{Kind: "pack", Bytes: len(p) - consumed}) + return len(p), nil + } + need := 4 + if len(d.buf) >= 4 { + n, err := strconv.ParseUint(string(d.buf[:4]), 16, 16) + if err != nil || n < 4 || n > 65520 { + d.err = fmt.Errorf("invalid git packet length %q", d.buf[:4]) + return consumed, d.err + } + need = int(n) + } + take := min(need-len(d.buf), len(p)-consumed) + d.buf = append(d.buf, p[consumed:consumed+take]...) + consumed += take + if len(d.buf) < need { + continue + } + if need == 4 { + switch string(d.buf) { + case "PACK": + d.pack = true + d.emit(Event{Kind: "pack", Bytes: 4}) + d.buf = nil + case "0000": + d.emit(Event{Kind: "flush"}) + d.buf = nil + case "0001": + d.emit(Event{Kind: "delimiter"}) + d.buf = nil + case "0002": + d.emit(Event{Kind: "response-end"}) + d.buf = nil + default: + n, err := strconv.ParseUint(string(d.buf), 16, 16) + if err != nil || n < 4 || n > 65520 { + d.err = fmt.Errorf("invalid git packet length %q", d.buf) + return consumed, d.err + } + if n == 4 { + d.emit(Event{Kind: "data"}) + d.buf = nil + } + } + continue + } + d.decode(d.buf[4:]) + d.buf = nil + } + return len(p), nil +} + +func (d *Decoder) Close() error { + if d.err != nil { + return d.err + } + if len(d.buf) != 0 { + return ErrIncomplete + } + return nil +} + +func (d *Decoder) emit(e Event) { + if d.Emit != nil { + d.Emit(e) + } +} + +func (d *Decoder) decode(p []byte) { + if len(p) == 0 { + d.emit(Event{Kind: "data"}) + return + } + if p[0] >= 1 && p[0] <= 3 { + if p[0] == 1 { + d.emit(Event{Kind: "pack", Bytes: len(p) - 1}) + return + } + kind := "progress" + if p[0] == 3 { + kind = "error" + } + d.emit(Event{Kind: kind, Text: strings.TrimSuffix(string(p[1:]), "\n")}) + return + } + text := strings.TrimSuffix(string(p), "\n") + line, caps, hasCaps := strings.Cut(text, "\x00") + kind := "data" + switch { + case strings.HasPrefix(line, "version "): + kind, line = "version", strings.TrimPrefix(line, "version ") + case strings.HasPrefix(line, "command="): + kind, line = "command", strings.TrimPrefix(line, "command=") + case strings.HasPrefix(line, "ERR "): + kind, line = "error", strings.TrimPrefix(line, "ERR ") + case strings.HasPrefix(line, "want "): + kind = "want" + case strings.HasPrefix(line, "have "): + kind = "have" + case strings.HasPrefix(line, "ACK ") || line == "NAK": + kind = "ack" + case strings.HasPrefix(line, "shallow ") || strings.HasPrefix(line, "unshallow "): + kind = "shallow" + case strings.HasPrefix(line, "ok ") || strings.HasPrefix(line, "ng ") || strings.HasPrefix(line, "unpack "): + kind = "status" + default: + fields := strings.Fields(line) + if len(fields) >= 2 && objectID(fields[0]) { + kind = "ref" + if objectID(fields[1]) { + kind = "update" + } + } + } + d.emit(Event{Kind: kind, Text: line}) + if hasCaps { + d.emit(Event{Kind: "capabilities", Text: caps}) + } +} + +func objectID(s string) bool { + if len(s) != 40 && len(s) != 64 { + return false + } + for _, c := range s { + if !(c >= '0' && c <= '9' || c >= 'a' && c <= 'f') { + return false + } + } + return true +} diff --git a/internal/protocol/gitwire/decoder_test.go b/internal/protocol/gitwire/decoder_test.go new file mode 100644 index 0000000..8fcf714 --- /dev/null +++ b/internal/protocol/gitwire/decoder_test.go @@ -0,0 +1,67 @@ +package gitwire + +import ( + "fmt" + "testing" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestDecoder(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Git wire decoder") } + +func packet(payload string) string { return fmt.Sprintf("%04x%s", len(payload)+4, payload) } + +var _ = Describe("Git packet decoding", func() { + It("decodes fragmented v2 packets and controls", func() { + var events []Event + d := Decoder{Emit: func(e Event) { events = append(events, e) }} + wire := packet("version 2\n") + packet("command=ls-refs\n") + "00010000" + for _, b := range []byte(wire) { + _, err := d.Write([]byte{b}) + Expect(err).NotTo(HaveOccurred()) + } + Expect(d.Close()).To(Succeed()) + Expect(events).To(Equal([]Event{{Kind: "version", Text: "2"}, {Kind: "command", Text: "ls-refs"}, {Kind: "delimiter"}, {Kind: "flush"}})) + }) + It("keeps pack payloads opaque while retaining progress and errors", func() { + var events []Event + d := Decoder{Emit: func(e Event) { events = append(events, e) }} + _, err := d.Write([]byte(packet("\x01PACK-private-object") + packet("\x02counting objects\n") + packet("\x03rejected\n"))) + Expect(err).NotTo(HaveOccurred()) + Expect(events).To(Equal([]Event{{Kind: "pack", Bytes: 19}, {Kind: "progress", Text: "counting objects"}, {Kind: "error", Text: "rejected"}})) + }) + It("decodes ref capabilities and push updates", func() { + var events []Event + d := Decoder{Emit: func(e Event) { events = append(events, e) }} + oid := "0123456789012345678901234567890123456789" + _, err := d.Write([]byte(packet(oid+" refs/heads/main\x00side-band-64k\n") + packet(oid+" "+oid+" refs/heads/main\n"))) + Expect(err).NotTo(HaveOccurred()) + Expect(events).To(Equal([]Event{{Kind: "ref", Text: oid + " refs/heads/main"}, {Kind: "capabilities", Text: "side-band-64k"}, {Kind: "update", Text: oid + " " + oid + " refs/heads/main"}})) + }) + It("rejects malformed and incomplete frames", func() { + d := Decoder{} + _, err := d.Write([]byte("0003")) + Expect(err).To(HaveOccurred()) + d = Decoder{} + _, err = d.Write([]byte("0008ab")) + Expect(err).NotTo(HaveOccurred()) + Expect(d.Close()).To(MatchError(ErrIncomplete)) + }) + It("counts unframed pack bytes without interpreting objects", func() { + var events []Event + d := Decoder{Emit: func(e Event) { events = append(events, e) }} + _, err := d.Write([]byte("PACKopaque")) + Expect(err).NotTo(HaveOccurred()) + _, err = d.Write([]byte("more")) + Expect(err).NotTo(HaveOccurred()) + Expect(d.Close()).To(Succeed()) + total := 0 + for _, event := range events { + Expect(event.Kind).To(Equal("pack")) + Expect(event.Text).To(BeEmpty()) + total += event.Bytes + } + Expect(total).To(Equal(14)) + }) +}) diff --git a/internal/protocol/sftpwire/decoder.go b/internal/protocol/sftpwire/decoder.go new file mode 100644 index 0000000..4320cdf --- /dev/null +++ b/internal/protocol/sftpwire/decoder.go @@ -0,0 +1,156 @@ +package sftpwire + +import ( + "encoding/binary" + "fmt" + "sync" +) + +type Event struct { + RequestID uint32 `json:"requestId"` + Operation string `json:"operation"` + Path string `json:"path,omitempty"` + Offset uint64 `json:"offset,omitempty"` + Bytes uint32 `json:"bytes,omitempty"` + Status *uint32 `json:"status,omitempty"` +} + +type Decoder struct { + Emit func(Event) + mu sync.Mutex + pending map[uint32]pending + handles map[string]string +} + +type pending struct { + event Event + handle string +} + +var operations = map[byte]string{3: "open", 4: "close", 5: "read", 6: "write", 7: "lstat", 8: "fstat", 9: "setstat", 10: "fsetstat", 11: "opendir", 12: "readdir", 13: "remove", 14: "mkdir", 15: "rmdir", 16: "realpath", 17: "stat", 18: "rename", 19: "readlink", 20: "symlink"} + +func (d *Decoder) Request(packet []byte) error { + d.mu.Lock() + defer d.mu.Unlock() + if len(packet) < 5 { + return fmt.Errorf("incomplete SFTP request") + } + if packet[0] == 1 { + if binary.BigEndian.Uint32(packet[1:]) != 3 { + return fmt.Errorf("SFTP decoder supports version 3") + } + return nil + } + id := binary.BigEndian.Uint32(packet[1:5]) + payload := packet[5:] + if d.pending == nil { + d.pending = map[uint32]pending{} + d.handles = map[string]string{} + } + if _, exists := d.pending[id]; exists { + return fmt.Errorf("duplicate SFTP request %d", id) + } + if len(d.pending) >= 4096 { + return fmt.Errorf("SFTP outstanding request limit exceeded") + } + value, err := takeString(&payload) + if err != nil { + return err + } + p := pending{event: Event{RequestID: id, Operation: operations[packet[0]], Path: value}} + switch packet[0] { + case 4, 5, 6, 8, 10, 12: + p.handle = value + path, ok := d.handles[value] + if !ok { + return fmt.Errorf("unknown SFTP handle") + } + p.event.Path = path + if packet[0] == 5 || packet[0] == 6 { + if len(payload) < 12 { + return fmt.Errorf("incomplete SFTP transfer request") + } + p.event.Offset = binary.BigEndian.Uint64(payload) + p.event.Bytes = binary.BigEndian.Uint32(payload[8:]) + if packet[0] == 6 && uint64(p.event.Bytes) != uint64(len(payload)-12) { + return fmt.Errorf("invalid SFTP write length") + } + } + case 200: + p.event.Operation = "extension:" + value + p.event.Path = "" + default: + if p.event.Operation == "" { + return fmt.Errorf("unsupported SFTP request type %d", packet[0]) + } + } + d.pending[id] = p + return nil +} + +func (d *Decoder) Response(packet []byte) error { + d.mu.Lock() + defer d.mu.Unlock() + if len(packet) < 5 { + return fmt.Errorf("incomplete SFTP response") + } + if packet[0] == 2 { + if binary.BigEndian.Uint32(packet[1:]) != 3 { + return fmt.Errorf("SFTP decoder supports version 3") + } + return nil + } + id := binary.BigEndian.Uint32(packet[1:5]) + payload := packet[5:] + p, ok := d.pending[id] + if !ok { + return fmt.Errorf("unmatched SFTP response %d", id) + } + switch packet[0] { + case 101: + if len(payload) < 4 { + return fmt.Errorf("incomplete SFTP status") + } + status := binary.BigEndian.Uint32(payload) + p.event.Status = &status + if status == 0 && p.event.Operation == "close" { + delete(d.handles, p.handle) + } + case 102: + handle, err := takeString(&payload) + if err != nil { + return err + } + if len(d.handles) >= 4096 { + return fmt.Errorf("SFTP open handle limit exceeded") + } + d.handles[handle] = p.event.Path + case 103: + if len(payload) < 4 || uint64(binary.BigEndian.Uint32(payload)) != uint64(len(payload)-4) { + return fmt.Errorf("invalid SFTP data length") + } + p.event.Bytes = binary.BigEndian.Uint32(payload) + case 104, 105, 201: + default: + return fmt.Errorf("unsupported SFTP response type %d", packet[0]) + } + delete(d.pending, id) + if d.Emit != nil { + d.Emit(p.event) + } + return nil +} + +func takeString(payload *[]byte) (string, error) { + if len(*payload) < 4 { + return "", fmt.Errorf("incomplete SFTP string length") + } + n := uint64(binary.BigEndian.Uint32(*payload)) + rest := (*payload)[4:] + if n > uint64(len(rest)) { + return "", fmt.Errorf("incomplete SFTP string") + } + value := string(rest[:int(n)]) + *payload = rest[int(n):] + return value, nil +} diff --git a/internal/protocol/sftpwire/decoder_test.go b/internal/protocol/sftpwire/decoder_test.go new file mode 100644 index 0000000..3390798 --- /dev/null +++ b/internal/protocol/sftpwire/decoder_test.go @@ -0,0 +1,40 @@ +package sftpwire + +import ( + "encoding/binary" + "testing" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestSFTP(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "SFTP operations") } +func u32(n uint32) []byte { return binary.BigEndian.AppendUint32(nil, n) } +func text(s string) []byte { return append(u32(uint32(len(s))), s...) } +func message(kind byte, id uint32, payload []byte) []byte { + return append(append([]byte{kind}, u32(id)...), payload...) +} + +var _ = Describe("SFTP decoding", func() { + It("correlates out-of-order replies and keeps file contents opaque", func() { + var events []Event + d := Decoder{Emit: func(e Event) { events = append(events, e) }} + open := append(text("/data/report.txt"), u32(1)...) + open = append(open, u32(0)...) + Expect(d.Request(message(3, 7, open))).To(Succeed()) + Expect(d.Response(message(102, 7, text("handle-1")))).To(Succeed()) + read := append(text("handle-1"), binary.BigEndian.AppendUint64(nil, 128)...) + read = append(read, u32(4)...) + Expect(d.Request(message(5, 8, read))).To(Succeed()) + Expect(d.Request(message(17, 9, text("/data/report.txt")))).To(Succeed()) + Expect(d.Response(message(101, 9, append(append(u32(2), text("missing")...), text("")...)))).To(Succeed()) + Expect(d.Response(message(103, 8, text("data")))).To(Succeed()) + status := uint32(2) + Expect(events).To(Equal([]Event{{RequestID: 7, Operation: "open", Path: "/data/report.txt"}, {RequestID: 9, Operation: "stat", Path: "/data/report.txt", Status: &status}, {RequestID: 8, Operation: "read", Path: "/data/report.txt", Offset: 128, Bytes: 4}})) + }) + It("rejects malformed and unmatched responses", func() { + d := Decoder{} + Expect(d.Request([]byte{3})).NotTo(Succeed()) + Expect(d.Response(message(101, 99, u32(0)))).NotTo(Succeed()) + }) +}) diff --git a/internal/tracequery/suite_test.go b/internal/tracequery/suite_test.go new file mode 100644 index 0000000..f85a685 --- /dev/null +++ b/internal/tracequery/suite_test.go @@ -0,0 +1,9 @@ +package tracequery + +import ( + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "testing" +) + +func TestTraceQuery(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Recorded trace query") } diff --git a/pkg/proxy/endpoint/auth.go b/pkg/proxy/endpoint/auth.go new file mode 100644 index 0000000..049c7b3 --- /dev/null +++ b/pkg/proxy/endpoint/auth.go @@ -0,0 +1,80 @@ +package endpoint + +import ( + "context" + "encoding/base64" + "fmt" + "slices" + "strings" + + "github.com/flanksource/telltale/pkg/credentials/apitoken" +) + +type Auth struct { + Mode string `json:"mode,omitempty"` +} + +func (a Auth) Validate() error { + if a.Mode != "" && a.Mode != "passthrough" && a.Mode != "token" { + return fmt.Errorf("auth.mode must be passthrough or token") + } + return nil +} + +type Policy struct { + Name string `json:"name"` + Connection string `json:"connection,omitempty"` + Auth Auth `json:"auth"` +} + +func (p Policy) Validate() error { + if err := p.Auth.Validate(); err != nil { + return err + } + if p.Name == "" { + return fmt.Errorf("endpoint name is required") + } + if p.Auth.Mode == "token" && (!strings.HasPrefix(p.Connection, "connection://") || strings.TrimPrefix(p.Connection, "connection://") == "") { + return fmt.Errorf("token endpoint requires a connection:// backend") + } + return nil +} + +func (p Policy) Authorize(ctx context.Context, raw string, verifier *apitoken.Verifier) (string, error) { + if err := p.Validate(); err != nil { + return "", err + } + if p.Auth.Mode != "token" { + return "", nil + } + if verifier == nil { + return "", fmt.Errorf("token endpoint has no verifier") + } + record, err := verifier.VerifyScope(ctx, raw, apitoken.ScopeProxy) + if err != nil { + return "", err + } + if !slices.Contains(record.Endpoints, p.Name) { + return "", apitoken.ErrScope + } + return record.ID, nil +} + +func HTTPToken(header string) (string, error) { + if value, ok := apitoken.BearerFromHeader(header); ok { + return value, nil + } + scheme, value, ok := strings.Cut(strings.TrimSpace(header), " ") + if !ok || !strings.EqualFold(scheme, "Basic") { + return "", apitoken.ErrMalformed + } + decoded, err := base64.StdEncoding.DecodeString(strings.TrimSpace(value)) + if err != nil { + return "", apitoken.ErrMalformed + } + user, password, ok := strings.Cut(string(decoded), ":") + if !ok || user != "telltale" || password == "" { + return "", apitoken.ErrMalformed + } + return password, nil +} diff --git a/pkg/proxy/endpoint/auth_test.go b/pkg/proxy/endpoint/auth_test.go new file mode 100644 index 0000000..09ca98a --- /dev/null +++ b/pkg/proxy/endpoint/auth_test.go @@ -0,0 +1,75 @@ +package endpoint + +import ( + "context" + "encoding/base64" + "testing" + "time" + + "github.com/flanksource/telltale/pkg/credentials/apitoken" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestEndpoint(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Endpoint authentication") } + +var _ = Describe("endpoint authentication", func() { + It("isolates endpoints and checks revocation despite cached verification", func() { + minted, err := apitoken.Mint() + Expect(err).NotTo(HaveOccurred()) + expires := time.Now().Add(time.Hour) + record := apitoken.Record{ID: minted.ID, SecretHash: minted.Hash, Scope: apitoken.ScopeProxy, Endpoints: []string{"deploy"}, ExpiresAt: &expires} + verifier := apitoken.NewVerifier(func(_ context.Context, id string) (apitoken.Record, error) { + if id != record.ID { + return apitoken.Record{}, apitoken.ErrUnknown + } + return record, nil + }) + endpoint := Policy{Name: "deploy", Connection: "connection://deployment", Auth: Auth{Mode: "token"}} + id, err := endpoint.Authorize(context.Background(), minted.Secret.Value(), verifier) + Expect(err).NotTo(HaveOccurred()) + Expect(id).To(Equal(minted.ID)) + endpoint.Name = "other" + _, err = endpoint.Authorize(context.Background(), minted.Secret.Value(), verifier) + Expect(err).To(MatchError(apitoken.ErrScope)) + endpoint.Name = "deploy" + now := time.Now() + record.RevokedAt = &now + _, err = endpoint.Authorize(context.Background(), minted.Secret.Value(), verifier) + Expect(err).To(MatchError(apitoken.ErrRevoked)) + }) + It("never downgrades token authentication and rejects expiry and wrong scopes", func() { + minted, err := apitoken.Mint() + Expect(err).NotTo(HaveOccurred()) + expires := time.Now().Add(-time.Second) + record := apitoken.Record{ID: minted.ID, SecretHash: minted.Hash, Scope: apitoken.ScopeProxy, Endpoints: []string{"deploy"}, ExpiresAt: &expires} + verifier := apitoken.NewVerifier(func(context.Context, string) (apitoken.Record, error) { return record, nil }) + p := Policy{Name: "deploy", Connection: "connection://deployment", Auth: Auth{Mode: "token"}} + _, err = p.Authorize(context.Background(), "", verifier) + Expect(err).To(HaveOccurred()) + _, err = p.Authorize(context.Background(), minted.Secret.Value(), verifier) + Expect(err).To(MatchError(apitoken.ErrExpired)) + record.ExpiresAt = nil + record.Scope = apitoken.ScopeAPI + _, err = p.Authorize(context.Background(), minted.Secret.Value(), verifier) + Expect(err).To(MatchError(ContainSubstring(apitoken.ErrScope.Error()))) + }) + It("allows independent passthrough endpoints without a token verifier", func() { + p := Policy{Name: "public"} + _, err := p.Authorize(context.Background(), "", nil) + Expect(err).NotTo(HaveOccurred()) + p.Auth.Mode = "typo" + Expect(p.Validate()).NotTo(Succeed()) + p.Auth.Mode = "token" + Expect(p.Validate()).NotTo(Succeed()) + }) + It("accepts native proxy Basic and Bearer credentials", func() { + for _, header := range []string{"Bearer consumer-token", "Basic " + base64.StdEncoding.EncodeToString([]byte("telltale:consumer-token"))} { + got, err := HTTPToken(header) + Expect(err).NotTo(HaveOccurred()) + Expect(got).To(Equal("consumer-token")) + } + _, err := HTTPToken("Basic invalid") + Expect(err).To(MatchError(apitoken.ErrMalformed)) + }) +}) From a8be9878c4bb91b35c1a907cc1274d105a287fde Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:04:49 +0200 Subject: [PATCH 04/89] docs(docs): add generated trace kind reference site Add generated documentation for every trace kind. A KindReference component renders each kind's flags, parameter schema, record and result columns, and example output from docs/_data/kinds.json, which is generated from the Go catalog and checked during the docs build. Adds per-kind MDX pages, a Rspress site configuration, getting-started and replay guides, and a Vitest suite for the component. Links to examples and the README now point at GitHub so they resolve outside the source tree. Process capture documentation describes the unified process, process_facets, and process_metrics tables. --- docs/_components/KindReference.test.tsx | 30 + docs/_components/KindReference.tsx | 122 + docs/_components/kind-reference.css | 6 + docs/_data/kinds.json | 6464 +++++++++++++++++++++++ docs/getting-started.md | 50 + docs/index.md | 15 + docs/otlp-receiver.md | 2 +- docs/package-lock.json | 3622 +++++++++++++ docs/package.json | 15 + docs/replay.md | 19 + docs/rspress.config.ts | 67 + docs/rules.md | 2 +- docs/sqlserver-jvm.md | 2 +- docs/traces/exec.mdx | 12 + docs/traces/goprof.mdx | 12 + docs/traces/http.mdx | 12 + docs/traces/index.md | 26 + docs/traces/jvm_jfr.mdx | 12 + docs/traces/llm.mdx | 12 + docs/traces/logs.mdx | 12 + docs/traces/process.mdx | 35 + docs/traces/prometheus.mdx | 12 + docs/traces/query.mdx | 12 + docs/traces/spans.mdx | 12 + docs/traces/sql.mdx | 12 + docs/traces/sql_deadlock.mdx | 12 + docs/traces/sql_plancache.mdx | 12 + docs/traces/sql_xevent.mdx | 12 + docs/traces/stacks.mdx | 12 + docs/traces/terminal.mdx | 12 + docs/vitest.config.ts | 3 + 31 files changed, 10657 insertions(+), 3 deletions(-) create mode 100644 docs/_components/KindReference.test.tsx create mode 100644 docs/_components/KindReference.tsx create mode 100644 docs/_components/kind-reference.css create mode 100644 docs/_data/kinds.json create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/package-lock.json create mode 100644 docs/package.json create mode 100644 docs/replay.md create mode 100644 docs/rspress.config.ts create mode 100644 docs/traces/exec.mdx create mode 100644 docs/traces/goprof.mdx create mode 100644 docs/traces/http.mdx create mode 100644 docs/traces/index.md create mode 100644 docs/traces/jvm_jfr.mdx create mode 100644 docs/traces/llm.mdx create mode 100644 docs/traces/logs.mdx create mode 100644 docs/traces/process.mdx create mode 100644 docs/traces/prometheus.mdx create mode 100644 docs/traces/query.mdx create mode 100644 docs/traces/spans.mdx create mode 100644 docs/traces/sql.mdx create mode 100644 docs/traces/sql_deadlock.mdx create mode 100644 docs/traces/sql_plancache.mdx create mode 100644 docs/traces/sql_xevent.mdx create mode 100644 docs/traces/stacks.mdx create mode 100644 docs/traces/terminal.mdx create mode 100644 docs/vitest.config.ts diff --git a/docs/_components/KindReference.test.tsx b/docs/_components/KindReference.test.tsx new file mode 100644 index 0000000..2a18be9 --- /dev/null +++ b/docs/_components/KindReference.test.tsx @@ -0,0 +1,30 @@ +import { renderToStaticMarkup } from 'react-dom/server'; +import { describe, expect, it } from 'vitest'; +import { KindReference } from './KindReference'; + +describe('trace kind enum choices', () => { + it('renders the unified process identity and both named result schemas', () => { + const html = renderToStaticMarkup(); + expect(html).toContain('process_facets'); + expect(html).toContain('process_metrics'); + expect(html).toContain('rssBytes'); + expect(html).toContain('server'); + }); + + it('lists defaults first in bold without repeating options in details', () => { + const html = renderToStaticMarkup(); + expect(html).not.toContain('Allowed values'); + expect(html).not.toContain('(one of connect, mitm)'); + expect(html).toContain('--modeconnect | mitm'); + expect(html).toContain('modeconnect | mitm'); + expect(html).toContain('--bodiesstring'); + const profile = renderToStaticMarkup(); + expect(profile).toContain('heap | cpu | allocs | mutex | block | goroutine'); + }); + + it('marks required flags and parameters with an accessible asterisk', () => { + const html = renderToStaticMarkup(); + expect(html).toContain('--connection*'); + expect(html).toContain('connection*'); + }); +}); diff --git a/docs/_components/KindReference.tsx b/docs/_components/KindReference.tsx new file mode 100644 index 0000000..17195fa --- /dev/null +++ b/docs/_components/KindReference.tsx @@ -0,0 +1,122 @@ +import { Fragment, useState } from 'react'; +import catalog from '../_data/kinds.json'; +import './kind-reference.css'; + +type Schema = { + type?: string; + description?: string; + properties?: Record; + required?: string[]; + enum?: unknown[]; + default?: unknown; + items?: Schema; + additionalProperties?: unknown; +}; +type Column = { name: string; type: string; label?: string; description?: string }; +type Argument = { name: string; type: string; description: string; default: string; required: boolean }; +type Kind = { name: string; params: Schema; columns: Column[]; flags: Argument[]; results?: { name: string; columns: Column[] }[] }; + +const examples: Record> = { + exec: { name: 'git', pid: 1234, durationMs: 35, exitCode: 0, stdoutTail: 'main\n' }, + goprof: { takenAt: '2026-01-01T10:00:00Z', pid: 1234, profile: 'heap', sampleType: 'inuse_space', value: 1048576, unit: 'bytes' }, + http: { startedAt: '2026-01-01T10:00:00Z', method: 'GET', host: 'example.com', url: 'https://example.com/', status: 200, durationMs: 34 }, + jvm_jfr: { timestamp: '2026-01-01T10:00:00Z', event: 'cpu', thread: 'main', frame: 'example.Service.run', samples: 3 }, + llm: { phase: 'completed', model: 'example-model', backend: 'example', durationMs: 1200, cost: 0.001 }, + logs: { firstObserved: '2026-01-01T10:00:00Z', count: 1, severity: 'INFO', message: 'Server started', source: 'application' }, + process: { key: '1234@1767261600', pid: 1234, ppid: 1200, name: 'server', command: './server', startedAt: '2026-01-01T10:00:00Z', cwd: '/work/checkout', tags: { owner: 'example' } }, + prometheus: { takenAt: '2026-01-01T10:00:00Z', endpoint: 'http://localhost:8080/metrics', health: 'up', durationMs: 12, samples: 45 }, + query: { time: '2026-01-01T10:00:00Z', profile: 'pod-cpu-by-pod', provider: 'prometheus', row: { pod: 'api-0', value: 0.2 } }, + spans: { traceId: '0123456789abcdef0123456789abcdef', spanId: '0123456789abcdef', service: 'checkout', operation: 'GET /orders', durationMs: 34, status: 'ok' }, + sql: { startedAt: '2026-01-01T10:00:00Z', connection: 'proxy', op: 'SELECT', sql: 'SELECT id FROM orders', durationMs: 8, rows: 2 }, + sql_deadlock: { timestamp: '2026-01-01T10:00:00Z', database: 'orders', victims: 1, participants: 2, victimStatement: 'UPDATE orders SET status = 1' }, + sql_plancache: { sampledAt: '2026-01-01T10:00:00Z', database: 'orders', executions: 5, cpuMs: 25, logicalReads: 100, sql: 'SELECT id FROM orders' }, + sql_xevent: { timestamp: '2026-01-01T10:00:00Z', name: 'sql_batch_completed', database: 'orders', durationMs: 12, sql: 'SELECT id FROM orders' }, + stacks: { takenAt: '2026-01-01T10:00:00Z', pid: 1234, format: 'goroutine', goroutineId: 1, state: 'running' }, + terminal: { at: '2026-01-01T10:00:00Z', offset: 0, kind: 'output', data: 'Build complete\n', width: 120, height: 40 }, +}; + +function fields(schema: Schema, prefix = ''): Array<{ path: string; schema: Schema; required: boolean }> { + return Object.entries(schema.properties ?? {}).flatMap(([name, value]) => { + const path = prefix ? `${prefix}.${name}` : name; + if (value.properties && Object.keys(value.properties).length) return fields(value, path); + return [{ path, schema: value, required: (schema.required ?? []).includes(name) }]; + }); +} + +function valueType(schema: Schema): string { + if (schema.type === 'array') return `${schema.items?.type ?? 'object'}[]`; + return schema.type ?? (schema.additionalProperties ? 'object' : 'unknown'); +} + +function EnumOptions({ values, defaultValue }: { values: unknown[]; defaultValue?: unknown }) { + const isDefault = (value: unknown) => defaultValue !== undefined && JSON.stringify(value) === JSON.stringify(defaultValue); + const ordered = [...values.filter(isDefault), ...values.filter((value) => !isDefault(value))]; + return <>{ordered.map((value, index) => {index > 0 && ' | '}{isDefault(value) ? {String(value)} : String(value)})}; +} + +function tabsFor(kind: string) { + const record = examples[kind]; + if (!record) throw new Error(`Missing output example for ${kind}`); + return record; +} + +export function KindReference({ kind }: { kind: string }) { + const entry = (catalog as Kind[]).find((item) => item.name === kind); + if (!entry) throw new Error(`Unknown trace kind: ${kind}`); + const params = fields(entry.params); + return <> +

    Arguments

    +

    Options for telltale run {kind}, including common run controls. Enum defaults appear first in bold; * marks required fields. Global formatting and logging options are listed in --help.

    +
    + {entry.flags.map((flag) => { + const match = flag.description.match(/\s*\(one of ([^)]+)\)$/); + const options = match?.[1].split(',').map((value) => value.trim()); + const description = flag.description.replace(/\s*\(one of ([^)]+)\)$/, '').replace(/\s*\(supported seams: \[[^\]]+\]\)$/, ''); + return ; + })} +
    FlagTypeDetails
    --{flag.name}{flag.required && *}{options ? : flag.type}{description || '—'}{flag.default !== '' && !options?.includes(flag.default) && <> Default: {flag.default}.}
    +
    + Capture parameter schema +

    These JSON parameter paths are used when configuring captures and can differ from CLI flag names.

    +
    + {params.map(({ path, schema, required }) => )} +
    ParameterTypeDetails
    {path}{required && *}{schema.enum ? : valueType(schema)}{schema.description?.replace(/\s*\(supported seams: \[[^\]]+\]\)$/, '') || '—'}{schema.default !== undefined && !schema.enum?.some((value) => JSON.stringify(value) === JSON.stringify(schema.default)) && <> Default: {JSON.stringify(schema.default)}.}
    +
    +

    Record schema

    +

    Columns exposed by the kind's record query profile. Fields may be absent or empty depending on the capture.

    +
    + {entry.columns.map((column) => )} +
    FieldTypeDescription
    {column.name}{column.type}{column.description || column.label || '—'}
    + {entry.results?.map((result) =>
    +

    {kind}_{result.name}

    +

    Read with telltale records {kind} --run <run-id> --result {result.name}.

    +
    + {result.columns.map((column) => )} +
    FieldTypeDescription
    {column.name}{column.type}{column.description || column.label || '—'}
    +
    )} + + ; +} + +export function OutputExamples({ kind }: { kind: string }) { + const [tab, setTab] = useState<'JSON' | 'ANSI' | 'Web'>('JSON'); + const record = tabsFor(kind); + const entries = Object.entries(record); + return
    +

    Example output

    +

    Illustrative values and selected fields. The ANSI and Web tabs show simplified layouts; actual presentation depends on the capture and formatting options.

    +
    + {(['JSON', 'ANSI', 'Web'] as const).map((name) => )} +
    +
    + {tab === 'JSON' &&
    {JSON.stringify(record, null, 2)}
    } + {tab === 'ANSI' &&
    {entries.map(([key, value]) => `${key.padEnd(16)} ${typeof value === 'object' ? JSON.stringify(value) : String(value)}`).join('\n')}
    } + {tab === 'Web' &&
    {entries.map(([key, value]) => )}
    FieldValue
    {key}{typeof value === 'object' ? JSON.stringify(value) : String(value)}
    } +
    +
    ; +} diff --git a/docs/_components/kind-reference.css b/docs/_components/kind-reference.css new file mode 100644 index 0000000..24ec6c3 --- /dev/null +++ b/docs/_components/kind-reference.css @@ -0,0 +1,6 @@ +.kind-table { overflow-x: auto; } +.kind-required { color: #c42b1c; font-weight: 700; margin-left: 0.2rem; } +.kind-output [role='tablist'] { display: flex; gap: 0.25rem; border-bottom: 1px solid var(--rp-c-divider); } +.kind-output [role='tab'] { padding: 0.5rem 1rem; border-bottom: 2px solid transparent; cursor: pointer; } +.kind-output [role='tab'][aria-selected='true'] { color: var(--rp-c-brand); border-color: var(--rp-c-brand); } +.kind-output [role='tab']:focus-visible { outline: 2px solid var(--rp-c-brand); outline-offset: -2px; } diff --git a/docs/_data/kinds.json b/docs/_data/kinds.json new file mode 100644 index 0000000..7153fc0 --- /dev/null +++ b/docs/_data/kinds.json @@ -0,0 +1,6464 @@ +[ + { + "name": "exec", + "title": "Executions", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Executable name glob" + }, + "tailBytes": { + "type": "integer", + "format": "int32", + "description": "Maximum bytes of each output tail", + "default": 4096 + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self agent])", + "enum": [ + "self", + "agent" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self", + "agent" + ] + } + } + }, + "columns": [ + { + "name": "truncated", + "label": "Truncated", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "name", + "type": "string" + }, + { + "name": "args", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "dir", + "type": "string" + }, + { + "name": "envKeys", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "pid", + "type": "number", + "format": "integer" + }, + { + "name": "startedAt", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "durationMs", + "type": "number" + }, + { + "name": "exitCode", + "type": "number", + "format": "integer" + }, + { + "name": "error", + "type": "string" + }, + { + "name": "stdoutTail", + "type": "string" + }, + { + "name": "stderrTail", + "type": "string" + }, + { + "name": "resource", + "type": "json" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "name", + "type": "string", + "description": "Executable name glob", + "default": "", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self agent]) (one of self, agent)", + "default": "self", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tail-bytes", + "type": "int", + "description": "Maximum bytes of each output tail", + "default": "4096", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "goprof", + "title": "Go profiles", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [process agent self])", + "enum": [ + "process", + "agent", + "self" + ], + "default": "process" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "process", + "agent", + "self" + ] + } + } + }, + "columns": [ + { + "name": "checkpointId", + "type": "string", + "filter": { + "kind": "exact" + }, + "hidden": true + }, + { + "name": "takenAt", + "label": "Taken", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "reason", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "source", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "key", + "type": "string", + "filter": { + "kind": "exact" + }, + "hidden": true + }, + { + "name": "pid", + "label": "PID", + "type": "number", + "format": "integer", + "filter": { + "kind": "terms" + } + }, + { + "name": "profile", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "sampleType", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "unit", + "type": "string" + }, + { + "name": "value", + "type": "number", + "format": "integer" + }, + { + "name": "frames", + "type": "json", + "hidden": true + }, + { + "name": "stackHash", + "type": "string", + "filter": { + "kind": "exact" + }, + "hidden": true + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + }, + { + "name": "pprof", + "ext": "pb.gz", + "mime": "application/octet-stream" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "every", + "type": "duration", + "description": "Read the checkpointed captures this often, e.g. 10s", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "profile", + "type": "string", + "description": "Go profile read at each checkpoint (one of cpu, heap, allocs, mutex, block, goroutine)", + "default": "heap", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [process agent self]) (one of process, agent, self)", + "default": "process", + "required": false + }, + { + "name": "seconds", + "type": "int", + "description": "Duration of a CPU profile window in seconds", + "default": "0", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "source", + "type": "string", + "description": "Process profile source (one of pprof, gops, file)", + "default": "gops", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "http", + "title": "HTTP proxy traffic", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "bodies": { + "type": "string", + "title": "Bodies", + "description": "How much of each body to keep such as 64KiB (at most 4MiB; 0 keeps none)", + "default": "256KiB" + }, + "dedupWindow": { + "type": "string", + "title": "Dedup window", + "description": "Store identical exchanges only once within this duration" + }, + "export": { + "type": "object", + "title": "Export", + "description": "Variable names the proxy and its CA are exported under", + "properties": { + "ca": { + "type": "string", + "title": "CA variable", + "description": "Variable the mitm CA file is exported under instead of SSL_CERT_FILE and the other trust variables" + }, + "noProxy": { + "type": "string", + "title": "No-proxy variable", + "description": "Variable the bypass list is exported under instead of NO_PROXY" + }, + "proxy": { + "type": "string", + "title": "Proxy variable", + "description": "Variable the proxy URL is exported under instead of HTTP(S)_PROXY" + } + } + }, + "features": { + "type": "array", + "title": "Features", + "description": "HTTP features to observe", + "default": [ + "telltale" + ], + "items": { + "type": "string" + } + }, + "hosts": { + "type": "array", + "title": "Hosts", + "description": "Host globs without a port to record and decrypt; empty records every host", + "items": { + "type": "string" + } + }, + "listen": { + "type": "string", + "title": "Listen", + "description": "host:port the proxy listens on such as 127.0.0.1:18080; empty takes a free loopback port" + }, + "mode": { + "default": "connect", + "description": "connect records HTTPS tunnels by host; mitm decrypts and records each exchange", + "enum": [ + "connect", + "mitm" + ], + "title": "Mode", + "type": "string" + }, + "noProxy": { + "type": "array", + "title": "No proxy", + "description": "host:port addresses the command reaches directly", + "items": { + "type": "string" + } + }, + "paths": { + "type": "array", + "title": "Paths", + "description": "URL path globs to record; empty records every path", + "items": { + "type": "string" + } + }, + "redact": { + "type": "array", + "title": "Redact headers", + "description": "Headers to blank beside the credential headers that are always blanked", + "items": { + "type": "string" + } + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self agent proxy])", + "enum": [ + "self", + "agent", + "proxy" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self", + "agent", + "proxy" + ] + }, + "upstreamCA": { + "type": "string", + "title": "Upstream CA file", + "description": "PEM file of authorities the proxy trusts beside the system roots under mitm" + } + } + }, + "columns": [ + { + "name": "truncated", + "label": "Truncated", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "startedDateTime", + "type": "string" + }, + { + "name": "time", + "type": "number" + }, + { + "name": "request", + "type": "json" + }, + { + "name": "response", + "type": "json" + }, + { + "name": "cache", + "type": "json" + }, + { + "name": "timings", + "type": "json" + }, + { + "name": "_id", + "type": "string" + }, + { + "name": "_pending", + "type": "boolean" + }, + { + "name": "_error", + "type": "string" + }, + { + "name": "startedAt", + "label": "Started", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "feature", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "method", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "host", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "url", + "label": "URL", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "status", + "type": "number", + "format": "integer", + "filter": { + "kind": "terms" + } + }, + { + "name": "durationMs", + "label": "Duration", + "type": "duration", + "unit": "ms" + }, + { + "name": "resource", + "type": "json" + }, + { + "name": "error", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "serverIPAddress", + "label": "Server IP", + "type": "string" + }, + { + "name": "tunnelled", + "type": "boolean" + }, + { + "name": "bytesIn", + "label": "Bytes in", + "type": "number", + "format": "integer" + }, + { + "name": "bytesOut", + "label": "Bytes out", + "type": "number", + "format": "integer" + }, + { + "name": "encoding", + "type": "string", + "hidden": true + }, + { + "name": "comment", + "type": "string", + "filter": { + "kind": "text" + } + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + }, + { + "name": "har", + "ext": "har", + "mime": "application/json" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "bodies", + "type": "string", + "description": "How much of each body to keep such as 64KiB (at most 4MiB; 0 keeps none)", + "default": "256KiB", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "dedup-window", + "type": "string", + "description": "Store identical exchanges only once within this duration", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "export-ca", + "type": "string", + "description": "Variable the mitm CA file is exported under instead of SSL_CERT_FILE and the other trust variables", + "default": "", + "required": false + }, + { + "name": "export-no-proxy", + "type": "string", + "description": "Variable the bypass list is exported under instead of NO_PROXY", + "default": "", + "required": false + }, + { + "name": "export-proxy", + "type": "string", + "description": "Variable the proxy URL is exported under instead of HTTP(S)_PROXY", + "default": "", + "required": false + }, + { + "name": "features", + "type": "stringSlice", + "description": "HTTP features to observe", + "default": "[telltale]", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "hosts", + "type": "stringSlice", + "description": "Host globs without a port to record and decrypt; empty records every host", + "default": "[]", + "required": false + }, + { + "name": "listen", + "type": "string", + "description": "host:port the proxy listens on such as 127.0.0.1:18080; empty takes a free loopback port", + "default": "", + "required": false + }, + { + "name": "mode", + "type": "string", + "description": "connect records HTTPS tunnels by host; mitm decrypts and records each exchange (one of connect, mitm)", + "default": "connect", + "required": false + }, + { + "name": "no-proxy", + "type": "stringSlice", + "description": "host:port addresses the command reaches directly", + "default": "[]", + "required": false + }, + { + "name": "paths", + "type": "stringSlice", + "description": "URL path globs to record; empty records every path", + "default": "[]", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "redact", + "type": "stringSlice", + "description": "Headers to blank beside the credential headers that are always blanked", + "default": "[]", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self agent proxy]) (one of self, agent, proxy)", + "default": "self", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "upstream-ca", + "type": "string", + "description": "PEM file of authorities the proxy trusts beside the system roots under mitm", + "default": "", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "jvm_jfr", + "title": "JFR profile samples", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "asyncProfiler": { + "type": "string", + "title": "Async-profiler executable", + "description": "Local asprof executable for process captures" + }, + "engine": { + "default": "jfr", + "enum": [ + "jfr", + "async-profiler" + ], + "title": "Engine", + "type": "string" + }, + "event": { + "enum": [ + "cpu", + "wall", + "alloc", + "lock" + ], + "title": "Async-profiler event", + "type": "string" + }, + "interval": { + "type": "string", + "title": "Sampling interval" + }, + "maxStackDepth": { + "type": "integer", + "title": "Maximum stack depth", + "format": "int32", + "description": "Keep this many leaf frames; zero keeps all recorded frames" + }, + "settings": { + "type": "string", + "title": "JFR settings" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [process agent])", + "enum": [ + "process", + "agent" + ], + "default": "process" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "process", + "agent" + ] + }, + "threads": { + "type": "boolean", + "title": "Split by thread", + "description": "Retain thread identities in decoded samples" + } + } + }, + "columns": [ + { + "name": "resource", + "type": "json" + }, + { + "name": "truncated", + "label": "Truncated", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "timestamp", + "label": "At", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "from", + "type": "datetime", + "hidden": true + }, + { + "name": "event", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "thread", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "frame", + "label": "Top frame", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "stack", + "type": "string", + "filter": { + "kind": "text" + }, + "hidden": true + }, + { + "name": "samples", + "type": "number", + "format": "integer" + }, + { + "name": "value", + "type": "number", + "format": "integer" + }, + { + "name": "unit", + "type": "string" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "async-profiler", + "type": "string", + "description": "Local asprof executable for process captures", + "default": "", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "engine", + "type": "string", + "description": "Engine (one of jfr, async-profiler)", + "default": "jfr", + "required": false + }, + { + "name": "event", + "type": "string", + "description": "Async-profiler event (one of cpu, wall, alloc, lock)", + "default": "", + "required": false + }, + { + "name": "every", + "type": "duration", + "description": "Read the checkpointed captures this often, e.g. 10s", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "interval", + "type": "string", + "description": "Sampling interval", + "default": "", + "required": false + }, + { + "name": "max-stack-depth", + "type": "int", + "description": "Keep this many leaf frames; zero keeps all recorded frames", + "default": "0", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [process agent]) (one of process, agent)", + "default": "process", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "settings", + "type": "string", + "description": "JFR settings", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "threads", + "type": "bool", + "description": "Retain thread identities in decoded samples", + "default": "false", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "llm", + "title": "LLM calls", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "includePrompts": { + "type": "boolean", + "description": "Include prompts" + }, + "includeResponses": { + "type": "boolean", + "description": "Include responses" + }, + "models": { + "type": "string", + "description": "Model glob" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self agent])", + "enum": [ + "self", + "agent" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self", + "agent" + ] + } + } + }, + "columns": [ + { + "name": "truncated", + "label": "Truncated", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "phase", + "type": "string" + }, + { + "name": "model", + "type": "string" + }, + { + "name": "backend", + "type": "string" + }, + { + "name": "iter", + "type": "number", + "format": "integer" + }, + { + "name": "prompt", + "type": "string" + }, + { + "name": "tools", + "type": "json" + }, + { + "name": "response", + "type": "string" + }, + { + "name": "usage", + "type": "json" + }, + { + "name": "cost", + "type": "number" + }, + { + "name": "durationMs", + "type": "number" + }, + { + "name": "error", + "type": "string" + }, + { + "name": "resource", + "type": "json" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "include-prompts", + "type": "bool", + "description": "Include prompts", + "default": "false", + "required": false + }, + { + "name": "include-responses", + "type": "bool", + "description": "Include responses", + "default": "false", + "required": false + }, + { + "name": "models", + "type": "string", + "description": "Model glob", + "default": "", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self agent]) (one of self, agent)", + "default": "self", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "logs", + "title": "Logs", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "backend": { + "type": "string" + }, + "connection": { + "type": "string" + }, + "container": { + "type": "string" + }, + "levels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "match": { + "type": "string" + }, + "minLevel": { + "type": "string" + }, + "namespace": { + "type": "string" + }, + "options": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "Dynamic response value" + } + }, + "podSelector": { + "type": "string" + }, + "query": { + "type": "string" + }, + "source": { + "type": "string" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self agent host])", + "enum": [ + "self", + "agent", + "host" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self", + "agent", + "host" + ] + }, + "timeField": { + "type": "string" + } + } + }, + "columns": [ + { + "name": "id", + "type": "string" + }, + { + "name": "firstObserved", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "lastObserved", + "type": "datetime" + }, + { + "name": "count", + "type": "number", + "format": "integer" + }, + { + "name": "message", + "type": "string" + }, + { + "name": "hash", + "type": "string" + }, + { + "name": "severity", + "type": "string" + }, + { + "name": "source", + "type": "string" + }, + { + "name": "host", + "type": "string" + }, + { + "name": "labels", + "type": "json" + }, + { + "name": "logger", + "type": "string" + }, + { + "name": "traceId", + "type": "string" + }, + { + "name": "resource", + "type": "json" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "backend", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "connection", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "container", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "levels", + "type": "stringSlice", + "description": " (key=value pairs)", + "default": "[]", + "required": false + }, + { + "name": "match", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "min-level", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "namespace", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "options", + "type": "string", + "description": " (JSON object)", + "default": "", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "pod-selector", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "query", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self agent host]) (one of self, agent, host)", + "default": "self", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "source", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "time-field", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "process", + "title": "Processes", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "catalog": { + "type": "string" + }, + "environment": { + "type": "object", + "properties": { + "keys": { + "type": "array", + "title": "Keys", + "description": "Environment variables to read onto each process", + "items": { + "type": "string" + } + }, + "prefixes": { + "type": "array", + "title": "Prefixes", + "description": "Prefixes of the environment variables to read onto each process", + "items": { + "type": "string" + } + } + }, + "nullable": true + }, + "facets": { + "type": "array", + "items": { + "type": "string" + } + }, + "interval": { + "type": "string", + "title": "Interval", + "description": "How often the tree is sampled such as 1s (at least 250ms)" + }, + "net": { + "type": "boolean" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [process host])", + "enum": [ + "process", + "host" + ], + "default": "process" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "process", + "host" + ] + } + } + }, + "columns": [ + { + "name": "key", + "type": "string" + }, + { + "name": "parentKey", + "type": "string" + }, + { + "name": "pid", + "type": "number", + "format": "integer" + }, + { + "name": "ppid", + "type": "number", + "format": "integer" + }, + { + "name": "name", + "type": "string" + }, + { + "name": "command", + "type": "string" + }, + { + "name": "cwd", + "type": "string" + }, + { + "name": "startedAt", + "type": "datetime" + }, + { + "name": "firstObservedAt", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "exitedAt", + "type": "datetime" + }, + { + "name": "environment", + "type": "json" + }, + { + "name": "tags", + "type": "json" + }, + { + "name": "environmentError", + "type": "string" + }, + { + "name": "groups", + "type": "json" + }, + { + "name": "stackTransports", + "type": "json" + } + ], + "results": [ + { + "name": "facets", + "columns": [ + { + "name": "process", + "type": "string" + }, + { + "name": "observedAt", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "tick", + "type": "number", + "format": "integer" + }, + { + "name": "facet", + "type": "string" + }, + { + "name": "entity", + "type": "string" + }, + { + "name": "operation", + "type": "string" + }, + { + "name": "directionSource", + "type": "string" + }, + { + "name": "reason", + "type": "string" + }, + { + "name": "resource", + "type": "json" + } + ] + }, + { + "name": "metrics", + "columns": [ + { + "name": "entity", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "observedAt", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "tick", + "type": "number", + "format": "integer" + }, + { + "name": "cpuPercent", + "type": "number", + "unit": "percent" + }, + { + "name": "rssBytes", + "type": "number", + "format": "integer", + "unit": "bytes" + }, + { + "name": "memoryPercent", + "type": "number", + "unit": "percent" + }, + { + "name": "diskReadBytes", + "type": "number", + "format": "integer", + "unit": "bytes" + }, + { + "name": "diskWriteBytes", + "type": "number", + "format": "integer", + "unit": "bytes" + }, + { + "name": "openFiles", + "type": "number", + "format": "integer" + }, + { + "name": "receivingSockets", + "type": "number", + "format": "integer" + }, + { + "name": "connectionsIn", + "type": "number", + "format": "integer" + }, + { + "name": "connectionsOut", + "type": "number", + "format": "integer" + }, + { + "name": "connectionsUnknown", + "type": "number", + "format": "integer" + }, + { + "name": "diskReadBps", + "type": "number", + "unit": "Bps" + }, + { + "name": "diskWriteBps", + "type": "number", + "unit": "Bps" + }, + { + "name": "netRxBps", + "type": "number", + "unit": "Bps" + }, + { + "name": "netTxBps", + "type": "number", + "unit": "Bps" + }, + { + "name": "swapBytes", + "type": "number", + "format": "integer", + "unit": "bytes" + }, + { + "name": "compressedBytes", + "type": "number", + "format": "integer", + "unit": "bytes" + } + ] + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "catalog", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "environment-keys", + "type": "stringSlice", + "description": "Environment variables to read onto each process", + "default": "[]", + "required": false + }, + { + "name": "environment-prefixes", + "type": "stringSlice", + "description": "Prefixes of the environment variables to read onto each process", + "default": "[]", + "required": false + }, + { + "name": "facets", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "interval", + "type": "string", + "description": "How often the tree is sampled such as 1s (at least 250ms)", + "default": "", + "required": false + }, + { + "name": "net", + "type": "bool", + "description": "", + "default": "false", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [process host]) (one of process, host)", + "default": "process", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + } + ] + }, + { + "name": "prometheus", + "title": "Prometheus scrapes", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "endpoints": { + "type": "array", + "title": "Endpoints", + "description": "Prometheus metrics URLs to scrape such as http://localhost:8080/metrics", + "items": { + "type": "string" + } + }, + "interval": { + "type": "string", + "title": "Interval", + "description": "How often each endpoint is scraped such as 15s (at least 1s)", + "default": "15s" + }, + "labels": { + "type": "object", + "title": "Labels", + "description": "Extra labels every scraped sample is stored with such as env=dev", + "additionalProperties": { + "type": "string" + } + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [host])", + "enum": [ + "host" + ], + "default": "host" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "host" + ] + }, + "timeout": { + "type": "string", + "title": "Timeout", + "description": "How long one scrape may take such as 5s (at most the interval; default the shorter of 10s and the interval)" + } + } + }, + "columns": [ + { + "name": "takenAt", + "label": "Scraped", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "endpoint", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "health", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "durationMs", + "label": "Duration", + "type": "duration", + "unit": "ms" + }, + { + "name": "samples", + "type": "number", + "format": "integer" + }, + { + "name": "error", + "type": "string" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "endpoints", + "type": "stringSlice", + "description": "Prometheus metrics URLs to scrape such as http://localhost:8080/metrics", + "default": "[]", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "interval", + "type": "string", + "description": "How often each endpoint is scraped such as 15s (at least 1s)", + "default": "15s", + "required": false + }, + { + "name": "labels", + "type": "stringSlice", + "description": "Extra labels every scraped sample is stored with such as env=dev (key=value pairs)", + "default": "[]", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [host]) (one of host)", + "default": "host", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "timeout", + "type": "string", + "description": "How long one scrape may take such as 5s (at most the interval; default the shorter of 10s and the interval)", + "default": "", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + } + ] + }, + { + "name": "query", + "title": "Query profile reads", + "capabilities": { + "historical": true, + "follow": true + }, + "params": { + "type": "object", + "properties": { + "every": { + "description": "Re-read the rows written since the last read at this interval; e.g. 15s", + "title": "Every", + "type": "string", + "x-clicky-order": 5 + }, + "from": { + "description": "Start of the window; a time or date math such as now-1h", + "title": "From", + "type": "string", + "x-clicky-order": 3 + }, + "limit": { + "description": "Most rows one read keeps; 0 keeps all", + "format": "int32", + "title": "Limit", + "type": "integer", + "x-clicky-order": 7 + }, + "params": { + "additionalProperties": { + "type": "object", + "description": "Dynamic response value" + }, + "description": "The profile's params by name", + "title": "Params", + "type": "object", + "x-clicky-order": 2 + }, + "profile": { + "description": "Saved query profile to read", + "title": "Profile", + "type": "string", + "x-clicky-order": 0 + }, + "provider": { + "type": "object", + "title": "Provider", + "format": "json", + "description": "A provider read in place: its type and connection or query and that provider's typed options", + "properties": { + "bigquery": { + "type": "object", + "properties": { + "mapping": { + "type": "object", + "properties": { + "host": { + "type": "array", + "items": { + "type": "string" + } + }, + "id": { + "type": "array", + "items": { + "type": "string" + } + }, + "ignore": { + "type": "array", + "items": { + "type": "string" + } + }, + "message": { + "type": "array", + "items": { + "type": "string" + } + }, + "severity": { + "type": "array", + "items": { + "type": "string" + } + }, + "source": { + "type": "array", + "items": { + "type": "string" + } + }, + "timestamp": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": true + }, + "project": { + "type": "string" + } + }, + "nullable": true + }, + "cloudwatchmetrics": { + "type": "object", + "properties": { + "concurrency": { + "type": "integer", + "format": "int32" + }, + "dimensions": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "endpoint": { + "type": "string" + }, + "language": { + "type": "string" + }, + "metrics": { + "type": "array", + "items": { + "type": "object", + "properties": { + "dimensions": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "name": { + "type": "string" + }, + "namespace": { + "type": "string" + }, + "statistic": { + "type": "string" + }, + "unit": { + "type": "string" + } + }, + "required": [ + "name", + "namespace" + ] + } + }, + "namespace": { + "type": "string" + }, + "range": { + "type": "object", + "properties": { + "end": { + "type": "string" + }, + "start": { + "type": "string" + }, + "step": { + "type": "string" + } + }, + "required": [ + "start", + "end", + "step" + ], + "nullable": true + }, + "region": { + "type": "string" + }, + "statistic": { + "type": "string" + }, + "unit": { + "type": "string" + } + }, + "nullable": true + }, + "connection": { + "type": "string", + "title": "Connection" + }, + "http": { + "type": "object", + "properties": { + "body": { + "type": "string" + }, + "jsonpath": { + "type": "string" + }, + "method": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "nullable": true + }, + "jaeger": { + "type": "object", + "properties": { + "end": { + "type": "string" + }, + "limit": { + "type": "string" + }, + "lookback": { + "type": "string" + }, + "maxDuration": { + "type": "string" + }, + "minDuration": { + "type": "string" + }, + "operation": { + "type": "string" + }, + "service": { + "type": "string" + }, + "start": { + "type": "string" + }, + "tags": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "nullable": true + }, + "opensearch": { + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "index": { + "type": "string" + }, + "limit": { + "type": "string" + }, + "pagingMode": { + "type": "string" + }, + "pagingThreshold": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "search": { + "type": "object", + "properties": { + "aggregations": { + "type": "object", + "additionalProperties": {} + }, + "fields": { + "type": "array", + "items": { + "type": "string" + } + }, + "from": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "query": { + "type": "object", + "properties": { + "analyzer": { + "type": "string" + }, + "boost": { + "type": "number", + "format": "double", + "nullable": true + }, + "caseInsensitive": { + "type": "boolean", + "nullable": true + }, + "conditions": { + "type": "array", + "items": { + "type": "object", + "description": "Recursive reference to esdsl.Condition" + } + }, + "escape": { + "type": "boolean", + "nullable": true + }, + "field": { + "type": "string" + }, + "fields": { + "type": "array", + "items": { + "type": "string" + } + }, + "format": { + "type": "string" + }, + "fuzziness": { + "type": "string" + }, + "gt": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "gte": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "lt": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "lte": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "matchOperator": { + "type": "string" + }, + "minimumShouldMatch": { + "type": "string" + }, + "multiMatchType": { + "type": "string" + }, + "occur": { + "type": "string" + }, + "op": { + "type": "string" + }, + "optional": { + "type": "boolean" + }, + "path": { + "type": "string" + }, + "scoreMode": { + "type": "string" + }, + "slop": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "timeZone": { + "type": "string" + }, + "value": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "values": { + "type": "array", + "items": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ] + } + }, + "when": { + "type": "string" + } + }, + "required": [ + "op" + ], + "nullable": true + }, + "size": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "sort": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "missing": { + "type": "string" + }, + "mode": { + "type": "string" + }, + "order": { + "type": "string" + }, + "unmappedType": { + "type": "string" + } + }, + "required": [ + "field" + ] + } + }, + "source": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "nullable": true + }, + "excludes": { + "type": "array", + "items": { + "type": "string" + } + }, + "includes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": true + }, + "storedFields": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeField": { + "type": "string" + }, + "timeFieldFormat": { + "type": "string" + }, + "trackTotalHits": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "nullable": true + }, + "threshold": { + "type": "integer", + "format": "int32", + "nullable": true + } + }, + "nullable": true + } + }, + "nullable": true + }, + "tailLag": { + "type": "string" + }, + "tailPoll": { + "type": "string" + } + }, + "nullable": true + }, + "opentelemetry": { + "type": "object", + "properties": { + "dateField": { + "type": "string" + }, + "format": { + "type": "string" + }, + "index": { + "type": "string" + }, + "limit": { + "type": "integer", + "format": "int32" + }, + "pagingMode": { + "type": "string" + }, + "pagingThreshold": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "search": { + "type": "object", + "properties": { + "aggregations": { + "type": "object", + "additionalProperties": {} + }, + "fields": { + "type": "array", + "items": { + "type": "string" + } + }, + "from": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "query": { + "type": "object", + "properties": { + "analyzer": { + "type": "string" + }, + "boost": { + "type": "number", + "format": "double", + "nullable": true + }, + "caseInsensitive": { + "type": "boolean", + "nullable": true + }, + "conditions": { + "type": "array", + "items": { + "type": "object", + "description": "Recursive reference to esdsl.Condition" + } + }, + "escape": { + "type": "boolean", + "nullable": true + }, + "field": { + "type": "string" + }, + "fields": { + "type": "array", + "items": { + "type": "string" + } + }, + "format": { + "type": "string" + }, + "fuzziness": { + "type": "string" + }, + "gt": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "gte": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "lt": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "lte": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "matchOperator": { + "type": "string" + }, + "minimumShouldMatch": { + "type": "string" + }, + "multiMatchType": { + "type": "string" + }, + "occur": { + "type": "string" + }, + "op": { + "type": "string" + }, + "optional": { + "type": "boolean" + }, + "path": { + "type": "string" + }, + "scoreMode": { + "type": "string" + }, + "slop": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "timeZone": { + "type": "string" + }, + "value": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "values": { + "type": "array", + "items": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ] + } + }, + "when": { + "type": "string" + } + }, + "required": [ + "op" + ], + "nullable": true + }, + "size": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "sort": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "missing": { + "type": "string" + }, + "mode": { + "type": "string" + }, + "order": { + "type": "string" + }, + "unmappedType": { + "type": "string" + } + }, + "required": [ + "field" + ] + } + }, + "source": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "nullable": true + }, + "excludes": { + "type": "array", + "items": { + "type": "string" + } + }, + "includes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": true + }, + "storedFields": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeField": { + "type": "string" + }, + "timeFieldFormat": { + "type": "string" + }, + "trackTotalHits": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "nullable": true + }, + "threshold": { + "type": "integer", + "format": "int32", + "nullable": true + } + }, + "nullable": true + } + }, + "nullable": true + }, + "selectFields": { + "type": "array", + "items": { + "type": "string" + } + }, + "sourceExcludes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": true + }, + "postgrest": { + "type": "object", + "properties": { + "jsonpath": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "nullable": true + }, + "prometheus": { + "type": "object", + "properties": { + "language": { + "type": "string" + }, + "range": { + "type": "object", + "properties": { + "end": { + "type": "string" + }, + "start": { + "type": "string" + }, + "step": { + "type": "string" + } + }, + "required": [ + "start", + "end", + "step" + ], + "nullable": true + }, + "selectLabels": { + "type": "array", + "items": { + "type": "string" + } + }, + "url": { + "type": "string" + } + }, + "nullable": true + }, + "query": { + "type": "string", + "title": "Query" + }, + "sql": { + "type": "object", + "properties": { + "database": { + "type": "string" + }, + "partitions": { + "type": "object", + "properties": { + "concurrency": { + "type": "integer", + "format": "int32" + }, + "files": { + "type": "array", + "items": { + "type": "string" + } + }, + "glob": { + "type": "string" + }, + "immutable": { + "type": "boolean" + }, + "labels": { + "type": "string" + } + }, + "nullable": true + }, + "type": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "nullable": true + }, + "type": { + "type": "string", + "title": "Type" + } + }, + "required": [ + "type" + ], + "nullable": true + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [host])", + "enum": [ + "host" + ], + "default": "host" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "host" + ] + }, + "to": { + "description": "End of the window; empty is now", + "title": "To", + "type": "string", + "x-clicky-order": 4 + }, + "untilStopped": { + "description": "Read once when the capture stops; up to that moment", + "title": "Until stopped", + "type": "boolean", + "x-clicky-order": 6 + } + } + }, + "columns": [ + { + "name": "time", + "label": "Time", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "profile", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "provider", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "row", + "type": "json", + "hidden": true + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "every", + "type": "string", + "description": "Re-read the rows written since the last read at this interval; e.g. 15s", + "default": "", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "from", + "type": "string", + "description": "Start of the window; a time or date math such as now-1h", + "default": "", + "required": false + }, + { + "name": "limit", + "type": "int", + "description": "Most rows one read keeps; 0 keeps all", + "default": "0", + "required": false + }, + { + "name": "params", + "type": "string", + "description": "The profile's params by name (JSON object)", + "default": "", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "profile", + "type": "string", + "description": "Saved query profile to read", + "default": "", + "required": false + }, + { + "name": "provider", + "type": "string", + "description": "A provider read in place: its type and connection or query and that provider's typed options (JSON object)", + "default": "", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [host]) (one of host)", + "default": "host", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "to", + "type": "string", + "description": "End of the window; empty is now", + "default": "", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "until-stopped", + "type": "bool", + "description": "Read once when the capture stops; up to that moment", + "default": "false", + "required": false + } + ] + }, + { + "name": "spans", + "title": "Spans", + "capabilities": { + "live": true, + "historical": true, + "follow": true + }, + "params": { + "type": "object", + "properties": { + "opensearch": { + "type": "object", + "title": "OpenSearch", + "description": "Index to read spans from on the host seam", + "properties": { + "connection": { + "type": "string", + "title": "Connection" + }, + "dateField": { + "type": "string", + "title": "Date field" + }, + "followIndex": { + "type": "boolean", + "title": "Follow index" + }, + "format": { + "type": "string", + "title": "Format" + }, + "from": { + "type": "string", + "title": "From" + }, + "index": { + "type": "string", + "title": "Index" + }, + "lag": { + "type": "string", + "title": "Lag" + }, + "poll": { + "type": "string", + "title": "Poll" + }, + "search": { + "type": "object", + "title": "Structured search", + "format": "json", + "properties": { + "aggregations": { + "type": "object", + "additionalProperties": {} + }, + "fields": { + "type": "array", + "items": { + "type": "string" + } + }, + "from": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "query": { + "type": "object", + "properties": { + "analyzer": { + "type": "string" + }, + "boost": { + "type": "number", + "format": "double", + "nullable": true + }, + "caseInsensitive": { + "type": "boolean", + "nullable": true + }, + "conditions": { + "type": "array", + "items": { + "type": "object", + "description": "Recursive reference to esdsl.Condition" + } + }, + "escape": { + "type": "boolean", + "nullable": true + }, + "field": { + "type": "string" + }, + "fields": { + "type": "array", + "items": { + "type": "string" + } + }, + "format": { + "type": "string" + }, + "fuzziness": { + "type": "string" + }, + "gt": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "gte": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "lt": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "lte": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "matchOperator": { + "type": "string" + }, + "minimumShouldMatch": { + "type": "string" + }, + "multiMatchType": { + "type": "string" + }, + "occur": { + "type": "string" + }, + "op": { + "type": "string" + }, + "optional": { + "type": "boolean" + }, + "path": { + "type": "string" + }, + "scoreMode": { + "type": "string" + }, + "slop": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "timeZone": { + "type": "string" + }, + "value": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ], + "nullable": true + }, + "values": { + "type": "array", + "items": { + "type": "object", + "properties": { + "Literal": { + "type": "object", + "description": "Dynamic response value" + }, + "Param": { + "type": "string" + } + }, + "required": [ + "Param" + ] + } + }, + "when": { + "type": "string" + } + }, + "required": [ + "op" + ], + "nullable": true + }, + "size": { + "type": "integer", + "format": "int32", + "nullable": true + }, + "sort": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "missing": { + "type": "string" + }, + "mode": { + "type": "string" + }, + "order": { + "type": "string" + }, + "unmappedType": { + "type": "string" + } + }, + "required": [ + "field" + ] + } + }, + "source": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "nullable": true + }, + "excludes": { + "type": "array", + "items": { + "type": "string" + } + }, + "includes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "nullable": true + }, + "storedFields": { + "type": "array", + "items": { + "type": "string" + } + }, + "timeField": { + "type": "string" + }, + "timeFieldFormat": { + "type": "string" + }, + "trackTotalHits": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "nullable": true + }, + "threshold": { + "type": "integer", + "format": "int32", + "nullable": true + } + }, + "nullable": true + } + }, + "nullable": true + }, + "to": { + "type": "string", + "title": "To" + } + }, + "required": [ + "connection" + ], + "nullable": true + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self agent host])", + "enum": [ + "self", + "agent", + "host" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self", + "agent", + "host" + ] + } + } + }, + "columns": [ + { + "name": "key", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "traceId", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "spanId", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "parentId", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "service", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "operation", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "kind", + "type": "string" + }, + { + "name": "startedAt", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "durationMs", + "type": "number" + }, + { + "name": "status", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "attributes", + "type": "json", + "hidden": true + }, + { + "name": "resource", + "type": "json", + "hidden": true + }, + { + "name": "source", + "type": "json", + "hidden": true + }, + { + "name": "native", + "type": "string", + "filter": { + "disabled": true + }, + "hidden": true + }, + { + "name": "digest", + "type": "string", + "filter": { + "disabled": true + }, + "hidden": true + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "opensearch-connection", + "type": "string", + "description": "Connection", + "default": "", + "required": false + }, + { + "name": "opensearch-date-field", + "type": "string", + "description": "Date field", + "default": "", + "required": false + }, + { + "name": "opensearch-follow-index", + "type": "bool", + "description": "Follow index", + "default": "false", + "required": false + }, + { + "name": "opensearch-format", + "type": "string", + "description": "Format", + "default": "", + "required": false + }, + { + "name": "opensearch-from", + "type": "string", + "description": "From", + "default": "", + "required": false + }, + { + "name": "opensearch-index", + "type": "string", + "description": "Index", + "default": "", + "required": false + }, + { + "name": "opensearch-lag", + "type": "string", + "description": "Lag", + "default": "", + "required": false + }, + { + "name": "opensearch-poll", + "type": "string", + "description": "Poll", + "default": "", + "required": false + }, + { + "name": "opensearch-search", + "type": "string", + "description": "Structured search (JSON object)", + "default": "", + "required": false + }, + { + "name": "opensearch-to", + "type": "string", + "description": "To", + "default": "", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self agent host]) (one of self, agent, host)", + "default": "self", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "sql", + "title": "SQL statements", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "connection": { + "type": "string", + "title": "Connection label", + "description": "Label the statements are recorded under", + "default": "proxy" + }, + "connections": { + "type": "array", + "title": "Connections", + "description": "Connections to observe", + "default": [ + "self" + ], + "items": { + "type": "string" + } + }, + "dsn": { + "type": "string", + "title": "Upstream DSN", + "description": "The postgres:// URL to proxy with $VAR references expanded; empty reads GAVEL_DB_DSN then DATABASE_URL" + }, + "env": { + "type": "string", + "title": "DSN variable", + "description": "Variable the command reads its DSN from; the upstream is read from it and the proxied DSN exported under it" + }, + "export": { + "type": "array", + "title": "Export", + "description": "The only variables the proxied DSN is exported under instead of GAVEL_DB_DSN DATABASE_URL and the PG* variables", + "items": { + "type": "string" + } + }, + "listen": { + "type": "string", + "title": "Listen", + "description": "host:port the proxy listens on such as 127.0.0.1:15432; empty takes a free loopback port" + }, + "maxStatements": { + "type": "integer", + "title": "Maximum statements", + "format": "int32", + "description": "Most statements one capture stores before it is marked truncated", + "default": 20000 + }, + "minDuration": { + "type": "string", + "title": "Minimum duration", + "description": "Record statements that ran at least this long" + }, + "params": { + "type": "boolean", + "title": "Capture bind values", + "description": "Keep bind parameter values which carry row data and may hold secrets" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self agent proxy])", + "enum": [ + "self", + "agent", + "proxy" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self", + "agent", + "proxy" + ] + } + } + }, + "columns": [ + { + "name": "truncated", + "label": "Truncated", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "startedAt", + "label": "Started", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "connection", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "driver", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "op", + "label": "Op", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "tables", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "sql", + "label": "SQL", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "repeatKey", + "type": "string", + "filter": { + "kind": "exact" + }, + "hidden": true + }, + { + "name": "args", + "type": "json", + "hidden": true + }, + { + "name": "durationMs", + "label": "Duration", + "type": "duration", + "unit": "ms" + }, + { + "name": "rows", + "type": "number", + "format": "integer" + }, + { + "name": "error", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "resource", + "type": "json" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "connection", + "type": "string", + "description": "Label the statements are recorded under", + "default": "proxy", + "required": false + }, + { + "name": "connections", + "type": "stringSlice", + "description": "Connections to observe", + "default": "[self]", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "dsn", + "type": "string", + "description": "The postgres:// URL to proxy with $VAR references expanded; empty reads GAVEL_DB_DSN then DATABASE_URL", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "env", + "type": "string", + "description": "Variable the command reads its DSN from; the upstream is read from it and the proxied DSN exported under it", + "default": "", + "required": false + }, + { + "name": "export", + "type": "stringSlice", + "description": "The only variables the proxied DSN is exported under instead of GAVEL_DB_DSN DATABASE_URL and the PG* variables", + "default": "[]", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "listen", + "type": "string", + "description": "host:port the proxy listens on such as 127.0.0.1:15432; empty takes a free loopback port", + "default": "", + "required": false + }, + { + "name": "max-statements", + "type": "int", + "description": "Most statements one capture stores before it is marked truncated", + "default": "20000", + "required": false + }, + { + "name": "min-duration", + "type": "string", + "description": "Record statements that ran at least this long", + "default": "", + "required": false + }, + { + "name": "params", + "type": "bool", + "description": "Keep bind parameter values which carry row data and may hold secrets", + "default": "false", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self agent proxy]) (one of self, agent, proxy)", + "default": "self", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "sql_deadlock", + "title": "SQL Server deadlocks", + "capabilities": { + "historical": true, + "follow": true + }, + "params": { + "type": "object", + "properties": { + "connection": { + "type": "string", + "title": "Connection" + }, + "databases": { + "type": "array", + "title": "Databases", + "description": "Participant database patterns; empty selects the connected database", + "items": { + "type": "string" + } + }, + "from": { + "type": "string", + "title": "From", + "description": "Historical window start in RFC3339; empty follows from now" + }, + "poll": { + "type": "string", + "title": "Poll", + "description": "Follow poll interval", + "default": "30s" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [connection])", + "enum": [ + "connection" + ], + "default": "connection" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "connection" + ] + }, + "to": { + "type": "string", + "title": "To", + "description": "Historical window end in RFC3339; empty uses server time" + } + }, + "required": [ + "connection" + ] + }, + "columns": [ + { + "name": "id", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "timestamp", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "database", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "databases", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "shape", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "signature", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "objects", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "indexes", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "lockTypes", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "hosts", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "apps", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "victims", + "type": "number", + "format": "integer", + "filter": { + "kind": "range" + } + }, + { + "name": "participants", + "type": "number", + "format": "integer", + "filter": { + "kind": "range" + } + }, + { + "name": "victimHost", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "victimApp", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "victimStatement", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "statementTruncated", + "type": "boolean", + "filter": { + "kind": "boolean" + } + }, + { + "name": "statements", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "processes", + "type": "json" + }, + { + "name": "resources", + "type": "json" + }, + { + "name": "xml", + "type": "string", + "filter": { + "disabled": true + } + }, + { + "name": "decodeError", + "type": "string", + "filter": { + "kind": "text" + } + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "connection", + "type": "string", + "description": "Connection", + "default": "", + "required": true + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "databases", + "type": "stringSlice", + "description": "Participant database patterns; empty selects the connected database", + "default": "[]", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "from", + "type": "string", + "description": "Historical window start in RFC3339; empty follows from now", + "default": "", + "required": false + }, + { + "name": "poll", + "type": "string", + "description": "Follow poll interval", + "default": "30s", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [connection]) (one of connection)", + "default": "connection", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "to", + "type": "string", + "description": "Historical window end in RFC3339; empty uses server time", + "default": "", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + } + ] + }, + { + "name": "sql_plancache", + "title": "SQL Server plan cache samples", + "capabilities": { + "follow": true + }, + "params": { + "type": "object", + "properties": { + "connection": { + "type": "string", + "title": "Connection", + "description": "SQL Server connection reference" + }, + "databases": { + "type": "array", + "title": "Databases", + "description": "Database patterns with * wildcards and ! exclusions; empty selects the connected database", + "items": { + "type": "string" + } + }, + "minExecutions": { + "type": "integer", + "title": "Minimum executions", + "format": "int32", + "description": "Minimum interval executions to record" + }, + "poll": { + "type": "string", + "title": "Poll", + "description": "Poll interval such as 30s", + "default": "30s" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [connection])", + "enum": [ + "connection" + ], + "default": "connection" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "connection" + ] + }, + "text": { + "type": "array", + "title": "Statement text", + "description": "SQL text patterns with * wildcards and ! exclusions; bare values match substrings", + "items": { + "type": "string" + } + }, + "top": { + "type": "integer", + "title": "Top", + "format": "int32", + "description": "Maximum cost samples per poll ranked by interval CPU; defaults to 200", + "default": 200 + } + }, + "required": [ + "connection" + ] + }, + "columns": [ + { + "name": "sampledAt", + "label": "Sampled", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "intervalMs", + "label": "Interval", + "type": "duration", + "unit": "ms" + }, + { + "name": "planHandle", + "label": "Plan handle", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "queryHash", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "queryPlanHash", + "type": "string", + "filter": { + "kind": "exact" + } + }, + { + "name": "database", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "object", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "objType", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "executions", + "type": "number", + "format": "integer" + }, + { + "name": "cpuMs", + "label": "CPU", + "type": "duration", + "unit": "ms" + }, + { + "name": "elapsedMs", + "label": "Elapsed", + "type": "duration", + "unit": "ms" + }, + { + "name": "logicalReads", + "type": "number", + "format": "integer" + }, + { + "name": "physicalReads", + "type": "number", + "format": "integer" + }, + { + "name": "writes", + "type": "number", + "format": "integer" + }, + { + "name": "rows", + "type": "number", + "format": "integer" + }, + { + "name": "avgElapsedMs", + "label": "Average elapsed", + "type": "duration", + "unit": "ms" + }, + { + "name": "avgCpuMs", + "label": "Average CPU", + "type": "duration", + "unit": "ms" + }, + { + "name": "totalExecutions", + "type": "number", + "format": "integer" + }, + { + "name": "totalCpuMs", + "label": "Total CPU", + "type": "duration", + "unit": "ms" + }, + { + "name": "totalElapsedMs", + "label": "Total elapsed", + "type": "duration", + "unit": "ms" + }, + { + "name": "useCounts", + "type": "number", + "format": "integer" + }, + { + "name": "sizeBytes", + "type": "bytes" + }, + { + "name": "creationTime", + "type": "datetime" + }, + { + "name": "recompiled", + "type": "boolean", + "filter": { + "kind": "terms" + } + }, + { + "name": "evicted", + "type": "boolean", + "filter": { + "kind": "terms" + } + }, + { + "name": "sql", + "label": "SQL", + "type": "string", + "filter": { + "kind": "text" + } + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "connection", + "type": "string", + "description": "SQL Server connection reference", + "default": "", + "required": true + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "databases", + "type": "stringSlice", + "description": "Database patterns with * wildcards and ! exclusions; empty selects the connected database", + "default": "[]", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "every", + "type": "duration", + "description": "Read the checkpointed captures this often, e.g. 10s", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "min-executions", + "type": "int", + "description": "Minimum interval executions to record", + "default": "0", + "required": false + }, + { + "name": "poll", + "type": "string", + "description": "Poll interval such as 30s", + "default": "30s", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [connection]) (one of connection)", + "default": "connection", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "text", + "type": "stringSlice", + "description": "SQL text patterns with * wildcards and ! exclusions; bare values match substrings", + "default": "[]", + "required": false + }, + { + "name": "top", + "type": "int", + "description": "Maximum cost samples per poll ranked by interval CPU; defaults to 200", + "default": "200", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + } + ] + }, + { + "name": "sql_xevent", + "title": "SQL Server events", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "apps": { + "type": "array", + "items": { + "type": "string" + } + }, + "connection": { + "type": "string", + "title": "Connection" + }, + "databases": { + "type": "array", + "items": { + "type": "string" + } + }, + "events": { + "type": "array", + "items": { + "type": "string" + } + }, + "hosts": { + "type": "array", + "items": { + "type": "string" + } + }, + "maxEvents": { + "type": "integer", + "format": "int32" + }, + "maxMemoryKb": { + "type": "integer", + "format": "int32" + }, + "minDuration": { + "type": "string" + }, + "poll": { + "type": "string" + }, + "session": { + "enum": [ + "system_health" + ], + "title": "Existing session", + "type": "string" + }, + "sessionName": { + "type": "string" + }, + "tables": { + "type": "array", + "items": { + "type": "string" + } + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [connection])", + "enum": [ + "connection" + ], + "default": "connection" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "connection" + ] + }, + "types": { + "type": "array", + "items": { + "type": "string" + } + }, + "users": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "connection" + ] + }, + "columns": [ + { + "name": "name", + "label": "Event", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "statementType", + "label": "Type", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "timestamp", + "label": "Time", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "durationMs", + "label": "Duration", + "type": "duration", + "unit": "ms" + }, + { + "name": "cpuMs", + "label": "CPU", + "type": "duration", + "unit": "ms" + }, + { + "name": "logicalReads", + "label": "Logical reads", + "type": "number", + "format": "integer" + }, + { + "name": "physicalReads", + "label": "Physical reads", + "type": "number", + "format": "integer" + }, + { + "name": "writes", + "type": "number", + "format": "integer" + }, + { + "name": "rowCount", + "label": "Rows", + "type": "number", + "format": "integer" + }, + { + "name": "database", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "clientApp", + "label": "App", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "clientHost", + "label": "Host", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "username", + "label": "User", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "sessionId", + "label": "Session", + "type": "number", + "format": "integer", + "filter": { + "kind": "exact" + } + }, + { + "name": "sql", + "label": "SQL", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "rawStatement", + "type": "string", + "hidden": true + }, + { + "name": "tables", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "errorNumber", + "label": "Error", + "type": "number", + "format": "integer" + }, + { + "name": "errorMessage", + "label": "Error message", + "type": "string", + "filter": { + "kind": "text" + } + }, + { + "name": "objectName", + "label": "Object", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "objectType", + "label": "Object type", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "paramsUnavailable", + "label": "Params unavailable", + "type": "boolean" + }, + { + "name": "additionalFields", + "type": "json", + "hidden": true + }, + { + "name": "deadlock", + "type": "json", + "hidden": true + }, + { + "name": "activityId", + "type": "string", + "hidden": true + }, + { + "name": "activitySeq", + "type": "number", + "format": "integer", + "hidden": true + }, + { + "name": "children", + "type": "json", + "hidden": true + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + } + ], + "flags": [ + { + "name": "apps", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "connection", + "type": "string", + "description": "Connection", + "default": "", + "required": true + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "databases", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "events", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "hosts", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "max-events", + "type": "int", + "description": "", + "default": "0", + "required": false + }, + { + "name": "max-memory-kb", + "type": "int", + "description": "", + "default": "0", + "required": false + }, + { + "name": "min-duration", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "poll", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [connection]) (one of connection)", + "default": "connection", + "required": false + }, + { + "name": "session", + "type": "string", + "description": "Existing session (one of system_health)", + "default": "", + "required": false + }, + { + "name": "session-name", + "type": "string", + "description": "", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tables", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "types", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "users", + "type": "stringSlice", + "description": "", + "default": "[]", + "required": false + } + ] + }, + { + "name": "stacks", + "title": "Stack dumps", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [process agent self])", + "enum": [ + "process", + "agent", + "self" + ], + "default": "process" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "process", + "agent", + "self" + ] + } + } + }, + "columns": [ + { + "name": "truncated", + "label": "Truncated", + "type": "json", + "filter": { + "kind": "terms", + "array": true + } + }, + { + "name": "checkpointId", + "type": "string", + "filter": { + "kind": "exact" + }, + "hidden": true + }, + { + "name": "takenAt", + "label": "Taken", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "reason", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "transport", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "key", + "type": "string", + "filter": { + "kind": "exact" + }, + "hidden": true + }, + { + "name": "pid", + "label": "PID", + "type": "number", + "format": "integer", + "filter": { + "kind": "terms" + } + }, + { + "name": "format", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "goroutineId", + "label": "Goroutine", + "type": "number", + "format": "integer" + }, + { + "name": "state", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "waitMinutes", + "label": "Waiting (min)", + "type": "number", + "format": "integer" + }, + { + "name": "lockedToThread", + "type": "boolean" + }, + { + "name": "frames", + "type": "json", + "hidden": true + }, + { + "name": "createdBy", + "type": "json", + "hidden": true + }, + { + "name": "raw", + "type": "string", + "filter": { + "kind": "none" + }, + "hidden": true + }, + { + "name": "error", + "type": "string" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + }, + { + "name": "text", + "ext": "txt", + "mime": "text/plain" + } + ], + "flags": [ + { + "name": "agent", + "type": "string", + "description": "Agent ID to observe", + "default": "", + "required": false + }, + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "every", + "type": "duration", + "description": "Read the checkpointed captures this often, e.g. 10s", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [process agent self]) (one of process, agent, self)", + "default": "process", + "required": false + }, + { + "name": "selector", + "type": "string", + "description": "Agent resource attributes to match", + "default": "", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "wait", + "type": "bool", + "description": "Wait for a matching agent to connect", + "default": "false", + "required": false + } + ] + }, + { + "name": "terminal", + "title": "Terminal", + "capabilities": { + "live": true + }, + "params": { + "type": "object", + "properties": { + "command": { + "type": "array", + "title": "Command", + "description": "Command line named in the cast's header", + "items": { + "type": "string" + } + }, + "height": { + "type": "integer", + "title": "Height", + "format": "int32", + "description": "Terminal height in cells", + "default": 40 + }, + "maxBytes": { + "type": "string", + "title": "Max bytes", + "description": "Most output recorded as events such as 4MiB", + "default": "4MiB" + }, + "snapshotInterval": { + "type": "string", + "title": "Snapshot interval", + "description": "How often the settled screen is recorded such as 100ms", + "default": "100ms" + }, + "target": { + "properties": { + "agent": { + "type": "string", + "title": "Agent", + "description": "Agent ID to observe" + }, + "allowMutation": { + "type": "boolean", + "title": "Allow mutation", + "description": "Allow probes to change runtime settings" + }, + "pid": { + "type": "integer", + "title": "PID", + "format": "int32", + "description": "Process to observe" + }, + "seam": { + "type": "string", + "title": "Seam", + "description": "How the capture is armed (supported seams: [self])", + "enum": [ + "self" + ], + "default": "self" + }, + "selector": { + "type": "object", + "title": "Selector", + "description": "Agent resource attributes to match", + "additionalProperties": { + "type": "string" + } + }, + "wait": { + "type": "boolean", + "title": "Wait for agents", + "description": "Wait for a matching agent to connect" + } + }, + "type": "object", + "x-telltale-seams": [ + "self" + ] + }, + "width": { + "type": "integer", + "title": "Width", + "format": "int32", + "description": "Terminal width in cells", + "default": 120 + } + } + }, + "columns": [ + { + "name": "at", + "label": "At", + "type": "datetime", + "kind": "timestamp" + }, + { + "name": "offset", + "label": "Offset", + "type": "number" + }, + { + "name": "kind", + "type": "string", + "filter": { + "kind": "terms" + } + }, + { + "name": "data", + "type": "string", + "filter": { + "kind": "none" + }, + "hidden": true + }, + { + "name": "width", + "type": "number", + "format": "integer" + }, + { + "name": "height", + "type": "number", + "format": "integer" + }, + { + "name": "exitCode", + "type": "number", + "format": "integer" + }, + { + "name": "truncated", + "type": "boolean" + }, + { + "name": "command", + "type": "string" + } + ], + "exportFormats": [ + { + "name": "ndjson", + "ext": "ndjson", + "mime": "application/x-ndjson" + }, + { + "name": "cast", + "ext": "cast", + "mime": "application/x-asciicast" + } + ], + "flags": [ + { + "name": "allow-mutation", + "type": "bool", + "description": "Allow probes to change runtime settings", + "default": "false", + "required": false + }, + { + "name": "command", + "type": "stringSlice", + "description": "Command line named in the cast's header", + "default": "[]", + "required": false + }, + { + "name": "data-dir", + "type": "string", + "description": "Directory holding telltale's trace data (default: $XDG_CACHE_HOME/telltale or the OS cache dir)", + "default": "", + "required": false + }, + { + "name": "duration", + "type": "duration", + "description": "Stop the run after this long, e.g. 30s (0 runs until the command exits or Ctrl+C)", + "default": "0s", + "required": false + }, + { + "name": "follow", + "type": "bool", + "description": "Print every armed capture's records while recording", + "default": "false", + "required": false + }, + { + "name": "height", + "type": "int", + "description": "Terminal height in cells", + "default": "40", + "required": false + }, + { + "name": "max-bytes", + "type": "string", + "description": "Most output recorded as events such as 4MiB", + "default": "4MiB", + "required": false + }, + { + "name": "pid", + "type": "int", + "description": "Process to observe", + "default": "0", + "required": false + }, + { + "name": "seam", + "type": "string", + "description": "How the capture is armed (supported seams: [self]) (one of self)", + "default": "self", + "required": false + }, + { + "name": "snapshot-interval", + "type": "string", + "description": "How often the settled screen is recorded such as 100ms", + "default": "100ms", + "required": false + }, + { + "name": "sort", + "type": "string", + "description": "Record order: seq or timestamp", + "default": "seq", + "required": false + }, + { + "name": "tui", + "type": "bool", + "description": "Follow records in an interactive terminal", + "default": "false", + "required": false + }, + { + "name": "ui", + "type": "bool", + "description": "Open this run's traces in a local web viewer; keep serving until Ctrl+C", + "default": "false", + "required": false + }, + { + "name": "width", + "type": "int", + "description": "Terminal width in cells", + "default": "120", + "required": false + } + ] + } +] diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..1cb9332 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,50 @@ +# Quick start + +Telltale combines a CLI and an HTTP server with a browser workspace. This guide builds it from a source checkout and records a command. + +## Build and start the server + +Install Go 1.27.1, Node 24, pnpm 11.22.0, a JDK (17 or 21 recommended), [Task](https://taskfile.dev/installation/), Gavel, and actionlint. Then run from the repository root: + +```sh +make setup +make build +.bin/telltale serve +``` + +Open `http://localhost:8080`. The server also exposes `/health` and `/api/openapi.json`. Use `--host` and `--port` to change the listener. + +## Record a command + +In another terminal, run: + +```sh +.bin/telltale trace run -- curl -sS https://example.com +.bin/telltale trace list +``` + +The default capture uses the HTTP proxy seam, and Telltale also records the process tree. Open the web workspace to inspect the run. Add `--follow --format ndjson` to print captured records as they arrive, or run `.bin/telltale trace run --help` for the available capture kinds and parameters. + +Run `.bin/telltale explain` to list trace kinds, or `.bin/telltale explain http` to inspect a kind's parameters and record schema. Add `--json` for structured output. + +Runs are stored under `traces/` in the data directory. Set `--data-dir` to choose it; by default Telltale uses `$XDG_CACHE_HOME/telltale` or the operating system cache directory. + +## Next steps + +- Learn how to [navigate the web workspace](/web-ui). +- [Receive OpenTelemetry traces](/otlp-receiver) from an instrumented application. +- [Preview resource monitoring rules](/rules) before enabling hooks. +- Consult the [README](https://github.com/flanksource/telltale#readme) for trace definitions, connections, process grouping, and development commands. + +## Work on this documentation + +From the repository root, install the documentation site's locked dependencies and start its development server: + +```sh +npm --prefix docs ci +npm --prefix docs run dev +``` + +Run `npm --prefix docs run build` to generate the static site in `docs/doc_build`. Preview the build with `npm --prefix docs run preview`. + +The trace-kind argument and record schemas are generated from Telltale's registered catalog. After changing a kind, run `npm --prefix docs run generate:catalog` and commit the updated snapshot. The documentation build checks that the snapshot is current. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..74920da --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +# Telltale + +Telltale records traces and process activity for commands, running processes, and hosts. Explore captures from the terminal or the web workspace, receive OpenTelemetry traces, and monitor resource usage across process groups. + +[Get started](/getting-started) + +## Explore the guides + +- [Web workspace](/web-ui): start captures, inspect records, manage connections, and explore traces. +- [OpenTelemetry receiver](/otlp-receiver): receive traces over OTLP and inspect them in Telltale. +- [Resource monitoring rules](/rules): preview CEL-based rules and configure hooks for process groups. +- [SQL Server and JVM captures](/sqlserver-jvm): collect SQL Server events and JVM profiles. +- [Trace kinds](/traces/): choose a capture and see its target, options, and examples. + +For the full command and configuration reference, see the [repository README](https://github.com/flanksource/telltale#readme). The CLI also provides `telltale --help` and help for each subcommand. diff --git a/docs/otlp-receiver.md b/docs/otlp-receiver.md index d1d7604..0f323b9 100644 --- a/docs/otlp-receiver.md +++ b/docs/otlp-receiver.md @@ -50,7 +50,7 @@ From this source checkout, `go run ./examples/otel` exports a two-span demonstra ## Forward from an OpenTelemetry Collector -The runnable [Collector configuration](../examples/otel-collector.yaml) listens on ports 14317 and 14318 and forwards traces to Telltale over HTTP/protobuf. With Telltale already listening on 4318: +The runnable [Collector configuration](https://github.com/flanksource/telltale/blob/main/examples/otel-collector.yaml) listens on ports 14317 and 14318 and forwards traces to Telltale over HTTP/protobuf. With Telltale already listening on 4318: ```bash otelcol-contrib --config examples/otel-collector.yaml diff --git a/docs/package-lock.json b/docs/package-lock.json new file mode 100644 index 0000000..bfd0f3f --- /dev/null +++ b/docs/package-lock.json @@ -0,0 +1,3622 @@ +{ + "name": "@flanksource/telltale-docs", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@flanksource/telltale-docs", + "devDependencies": { + "@rspress/core": "2.1.0" + } + }, + "node_modules/@emnapi/core": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.3.tgz", + "integrity": "sha512-zLpS5asjEb7lq8jYLq37N6XKaE41DIexlY1rF/z4/tIl3wo13Sqm28fRyfIsKZD+NZ8mM5RoKkpW/rBcuoSZSg==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/wasi-threads": "1.2.3", + "tslib": "^2.4.0" + } + }, + "node_modules/@emnapi/runtime": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", + "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@emnapi/wasi-threads": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.3.tgz", + "integrity": "sha512-ELEBe8PsLvvJ6QMr0zLt8ffvOHW/dc1m3CEzNMg7aJUv3bMaoDtw2TXyDAwkYBuroxxuHEwhRTLJSe5sya547g==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@mdx-js/mdx": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-3.1.1.tgz", + "integrity": "sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdx": "^2.0.0", + "acorn": "^8.0.0", + "collapse-white-space": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "estree-util-scope": "^1.0.0", + "estree-walker": "^3.0.0", + "hast-util-to-jsx-runtime": "^2.0.0", + "markdown-extensions": "^2.0.0", + "recma-build-jsx": "^1.0.0", + "recma-jsx": "^1.0.0", + "recma-stringify": "^1.0.0", + "rehype-recma": "^1.0.0", + "remark-mdx": "^3.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.0.0", + "source-map": "^0.7.0", + "unified": "^11.0.0", + "unist-util-position-from-estree": "^2.0.0", + "unist-util-stringify-position": "^4.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/@mdx-js/react": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.1.tgz", + "integrity": "sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdx": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "@types/react": ">=16", + "react": ">=16" + } + }, + "node_modules/@napi-rs/wasm-runtime": { + "version": "1.1.6", + "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.6.tgz", + "integrity": "sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@tybys/wasm-util": "^0.10.3" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/Brooooooklyn" + }, + "peerDependencies": { + "@emnapi/core": "^1.7.1", + "@emnapi/runtime": "^1.7.1" + } + }, + "node_modules/@rsbuild/core": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rsbuild/core/-/core-2.3.1.tgz", + "integrity": "sha512-dv5tL7djb8ex5z4sqnDmUbd5PnGNr/CXuFfiMD4RkUsF1JEZZkGH8lc+QW4fqYQIHM7RTvcMUakgvwVU/O9WMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@rspack/core": "~2.3.1", + "@swc/helpers": "^0.5.23" + }, + "bin": { + "rsbuild": "bin/rsbuild.js" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "peerDependencies": { + "core-js": ">= 3.0.0" + }, + "peerDependenciesMeta": { + "core-js": { + "optional": true + } + } + }, + "node_modules/@rsbuild/plugin-react": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/@rsbuild/plugin-react/-/plugin-react-2.1.1.tgz", + "integrity": "sha512-tLtUedsRtTLS6M4VtwzI6aakFLOFdgl9Sh1ZNBWvxb0Te3EnHrppaE7UiYEmDUXQDJ50gfr6yyirtxY5N6moyg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@rspack/plugin-react-refresh": "^2.0.2", + "react-refresh": "^0.19.0" + }, + "peerDependencies": { + "@rsbuild/core": "^2.0.0" + }, + "peerDependenciesMeta": { + "@rsbuild/core": { + "optional": true + } + } + }, + "node_modules/@rspack/binding": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding/-/binding-2.3.1.tgz", + "integrity": "sha512-pfCJGBFNK2tnNnoDP6ZoTbOjxbKr1U2eGFDJ8bIuZQai4FBNhWQlKFmNup+X5K935XYRulZBomIBAL6GL6W2YQ==", + "dev": true, + "license": "MIT", + "optionalDependencies": { + "@rspack/binding-darwin-arm64": "2.3.1", + "@rspack/binding-darwin-x64": "2.3.1", + "@rspack/binding-linux-arm64-gnu": "2.3.1", + "@rspack/binding-linux-arm64-musl": "2.3.1", + "@rspack/binding-linux-ppc64-gnu": "2.3.1", + "@rspack/binding-linux-riscv64-gnu": "2.3.1", + "@rspack/binding-linux-riscv64-musl": "2.3.1", + "@rspack/binding-linux-s390x-gnu": "2.3.1", + "@rspack/binding-linux-x64-gnu": "2.3.1", + "@rspack/binding-linux-x64-musl": "2.3.1", + "@rspack/binding-wasm32-wasi": "2.3.1", + "@rspack/binding-win32-arm64-msvc": "2.3.1", + "@rspack/binding-win32-ia32-msvc": "2.3.1", + "@rspack/binding-win32-x64-msvc": "2.3.1" + } + }, + "node_modules/@rspack/binding-darwin-arm64": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-darwin-arm64/-/binding-darwin-arm64-2.3.1.tgz", + "integrity": "sha512-koLyL2r8PUcLD0StjuZ/n5XM6GJ0C8dzJN0IuIV9d7nQcibJxwjjSAWEPGVz6bm8WuzypvuVKNoa1+GGAHeMQA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rspack/binding-darwin-x64": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-darwin-x64/-/binding-darwin-x64-2.3.1.tgz", + "integrity": "sha512-YK39JLiu1YC6+3BMxkP7e848pHD7e2T/0OSNogDi7whfiZNg95wa9Ncd7I5ppAf0nhmV+FNew/sCBIFp5h67Jw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rspack/binding-linux-arm64-gnu": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-2.3.1.tgz", + "integrity": "sha512-Q+RCA/KM2tn6m6R5U4lktXDs5cCRm3SyleQk86iqqUFX7wKzVRUvr5BTsreg6K9of3gpYmQ6+g1PGT5cwo0rLA==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-arm64-musl": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-arm64-musl/-/binding-linux-arm64-musl-2.3.1.tgz", + "integrity": "sha512-He+muVDON1fohGtdYamh3zHVwf6/E6fZu/+iEAkxjclE0P94bsCfYVcZW/a4/l1tJ2zvLZtB4jD7Qr6r4vG/WA==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-ppc64-gnu": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-2.3.1.tgz", + "integrity": "sha512-blIZUgyPt4FcSHkZL6sJ2xbzc7ACgDeU49An4mXLSebwdgnlhTzxeSFnh2VeJDlGza8CUaZYB/zS/6oZ2kCDcw==", + "cpu": [ + "ppc64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-riscv64-gnu": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-2.3.1.tgz", + "integrity": "sha512-3FtW2DUFmXxhBORUA3zSc+ot4d6R/1/U6z/48TDN4jeIYDUG9VqYBF6LUohX4vBY6IP0DCyXb2N9WayD/9QXoA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-riscv64-musl": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-2.3.1.tgz", + "integrity": "sha512-+5qNgdNdXzp/K8f8BjgJ3m7tcbBKPENN7WPDfBcSHvWb5GF4+o/pbrX26c0+LEugo0bYUOAoitBNd94AwcNvpA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-s390x-gnu": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-2.3.1.tgz", + "integrity": "sha512-yNcg/y1+MV0wZ984CVU4d1HAYYwMcDPXoQO0xynU+K5YuBxPWALHOxuRRCKCcykBdL1GIEshAIewEFrsW/cmJg==", + "cpu": [ + "s390x" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-x64-gnu": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-2.3.1.tgz", + "integrity": "sha512-ffclKBuH8wwimOBd6xGUxrBfVKKY5Ow4E7OFdHZeg4xffm2O8auGszmOgvFu1eoDoOYHaVJn+cEV6UD0KwZk8A==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-linux-x64-musl": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-linux-x64-musl/-/binding-linux-x64-musl-2.3.1.tgz", + "integrity": "sha512-qcDwwuyxR7TMtrW+r5Y9RIW25boXd1Ip/9jz04jhdq/OiU/Am7rCP2X90CH8sWdzovIF9UNmsGjY4KklR0F2Mg==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rspack/binding-wasm32-wasi": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-wasm32-wasi/-/binding-wasm32-wasi-2.3.1.tgz", + "integrity": "sha512-3dr6zjFaCK3A920ftCriSJkiRhEfhHtat7LtBdj6g0mcV5Rt+iealmli0vjeAvD0UdpE1u8EKWlfw82JLgFLSQ==", + "cpu": [ + "wasm32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@emnapi/core": "1.11.3", + "@emnapi/runtime": "1.11.3", + "@napi-rs/wasm-runtime": "1.1.6" + } + }, + "node_modules/@rspack/binding-win32-arm64-msvc": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-2.3.1.tgz", + "integrity": "sha512-AZbuLPylt1xvWssN93AsirbYs3WgfcrA8tMsqHmVJIHahLu9E+JPKZ3Gmsw6IYEZk3EfnV3ujQzeQ1/VfF0Vsw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rspack/binding-win32-ia32-msvc": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-2.3.1.tgz", + "integrity": "sha512-R5NVU68TePZcgRdYUzrQX9YFNxmcyXZEPwaPv40AAgsqNyacG3iRaYVmV79jt3rWYfa0QJaqvRLUchDe2SZ6zQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rspack/binding-win32-x64-msvc": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/binding-win32-x64-msvc/-/binding-win32-x64-msvc-2.3.1.tgz", + "integrity": "sha512-5T9DYjNPQpLbrNXjCssGd2B6xMQPlc3LxVOKHGUA1O0GV+88vBkTXAcryJ+Fo+yVEMPCzp4VvwBMGAVDpCjcSA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rspack/core": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/@rspack/core/-/core-2.3.1.tgz", + "integrity": "sha512-9BWfaiEJLgLK9U53Q4WVruBZ19Mu/XWHXHEu0UFla4lUtH8Z+/ET2m044tiqbtyIgqQyG58fMrxHeVIAiXMXHg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@rspack/binding": "2.3.1" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "peerDependencies": { + "@module-federation/runtime-tools": "^0.24.1 || ^2.0.0", + "@swc/helpers": "^0.5.23" + }, + "peerDependenciesMeta": { + "@module-federation/runtime-tools": { + "optional": true + }, + "@swc/helpers": { + "optional": true + } + } + }, + "node_modules/@rspack/plugin-react-refresh": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/@rspack/plugin-react-refresh/-/plugin-react-refresh-2.0.2.tgz", + "integrity": "sha512-dGNZiCxQxgAUI9sah7gd8u+O7OJZRCmqtEJNDOd8xW5RqcieC86F7p5qcShyw6onH5pKf57evpr2VjGbaFGkZg==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "@rspack/core": "^2.0.0", + "react-refresh": ">=0.10.0 <1.0.0" + }, + "peerDependenciesMeta": { + "@rspack/core": { + "optional": true + } + } + }, + "node_modules/@rspress/core": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@rspress/core/-/core-2.1.0.tgz", + "integrity": "sha512-xw5iGhzLn4O8vGUj8+y7AiVo51Pd1l1GkIBF9q5btfXTYR0xkGY984rxMFOYI43etvlRRkMM2du+IwiyqUnPGA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@mdx-js/mdx": "^3.1.1", + "@mdx-js/react": "^3.1.1", + "@rsbuild/core": "^2.2.14", + "@rsbuild/plugin-react": "~2.1.1", + "@rspress/shared": "2.1.0", + "@shikijs/rehype": "^4.2.0", + "@types/mdast": "^4.0.4", + "@types/react": "^19.3.0", + "@unhead/react": "^2.1.17", + "body-scroll-lock": "4.0.0-beta.0", + "clsx": "2.1.1", + "copy-to-clipboard": "^3.3.3", + "flexsearch": "0.8.212", + "hast-util-heading-rank": "^3.0.0", + "hast-util-to-jsx-runtime": "^2.3.7", + "mdast-util-mdx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.1", + "medium-zoom": "1.1.2", + "nprogress": "^0.2.0", + "react": "^19.3.1", + "react-dom": "^19.3.1", + "react-lazy-with-preload": "^2.2.1", + "react-render-to-markdown": "19.1.0", + "react-router-dom": "^7.18.5", + "rehype-external-links": "^3.0.0", + "rehype-raw": "^7.0.0", + "remark-cjk-friendly": "^2.3.3", + "remark-cjk-friendly-gfm-strikethrough": "^2.3.2", + "remark-gfm": "^4.0.1", + "remark-mdx": "^3.1.1", + "remark-parse": "^11.0.0", + "remark-stringify": "^11.0.0", + "scroll-into-view-if-needed": "^3.1.0", + "shiki": "^4.2.0", + "unified": "^11.0.5", + "unist-util-visit": "^5.1.0", + "unist-util-visit-children": "^3.0.0", + "vfile": "^6.0.3" + }, + "bin": { + "rspress": "bin/rspress.js" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + } + }, + "node_modules/@rspress/shared": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@rspress/shared/-/shared-2.1.0.tgz", + "integrity": "sha512-D2wnLO4aV1eFxNbUqQaLY4QfZZktegM+lCIDbQ9H2wxNQHKde39U1hpRdZKIA4aCuPYf/RSb6EdmJiZOkoZaWw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@rsbuild/core": "^2.2.14", + "@shikijs/rehype": "^4.2.0", + "@types/react": "^19.3.0", + "mdast-util-mdx-jsx": "^3.2.0", + "unified": "^11.0.5" + } + }, + "node_modules/@shikijs/core": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-4.6.0.tgz", + "integrity": "sha512-bfd4OKgvoyXYiYmMRuleA656P4V7M/Du9lcTl38Ngm6KszMj7bq4J1IGZwSYR4c95Tv5UQALtYNWUwaI9UT3xw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/primitive": "4.6.0", + "@shikijs/types": "4.6.0", + "@shikijs/vscode-textmate": "^10.1.0", + "@types/hast": "^3.0.5", + "hast-util-to-html": "^9.0.6" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-4.6.0.tgz", + "integrity": "sha512-K0oqxFoL+kEMdz89mHLFO15Tsbv3kFZ6WR1cXZKMvLSc+oqaM00A6pyga1qSeXB22dP0tTiSApRcGBaKWsEccg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.6.0", + "@shikijs/vscode-textmate": "^10.1.0", + "oniguruma-to-es": "^4.3.6" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-4.6.0.tgz", + "integrity": "sha512-aggd6Q7SuJOXNnsUbfG2XesxBJKBMAw/PDTUo9PyRjMaaJJ2dNrI+q0C+25ARXAK9yLHAlwxc9oRT2u68YKZ7w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.6.0", + "@shikijs/vscode-textmate": "^10.1.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/langs": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-4.6.0.tgz", + "integrity": "sha512-1yMEX3oCVV54LUq/ovfpRkDQoYDkcvjSWFFa/YLUDMiSoRzMi2uxLJYbv41ahT8Lu9lFMaa7hecd3Q39trqUyg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.6.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/primitive": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/primitive/-/primitive-4.6.0.tgz", + "integrity": "sha512-c54+TQEo9ToqgfL/AU8FpjnV09+GA9Oa7M5ROkkXteZfp5XzpAJGXjjvZQFQioJOwm/w/6Z3lIzQstAkl8coag==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.6.0", + "@shikijs/vscode-textmate": "^10.1.0", + "@types/hast": "^3.0.5" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/rehype": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/rehype/-/rehype-4.6.0.tgz", + "integrity": "sha512-qv3mGfYJuy+TW6UUyC2QrYSEmTxJNGXZ/NmCEsyH0NHfJIOYGvpWm0kNu6P2Ec14jmGwwTfVLMta/FZtY+MrJQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.6.0", + "@types/hast": "^3.0.5", + "hast-util-to-string": "^3.0.1", + "shiki": "4.6.0", + "unified": "^11.0.5", + "unist-util-visit": "^5.2.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/themes": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-4.6.0.tgz", + "integrity": "sha512-qHAVAs80RiGD+IRuH9G+JPDOEc9A/kHsng4EzCUCwB9bLzW6Z0y9WETh2YyCcADJBmfrIaJ1Jp7KBNP6FHkgtQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "4.6.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/types": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-4.6.0.tgz", + "integrity": "sha512-+ENG1adsKt/X7cRYw1Nl7BEpBmPOjmQ7bR/eGmHuMlT8gtOFf3KEi5l31DJYyAWhW6Y6bjP1plU7FmaxWGENFw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.1.0", + "@types/hast": "^3.0.5" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.1.0.tgz", + "integrity": "sha512-cVBuhDQjBZaNMTwBquYfPydrUP+E3hE6oYGasx8h6ZrODIM7/r+gxLDXdd66oszbrggZHEntdE6j+5gYIVyMWQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@swc/helpers": { + "version": "0.5.24", + "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.24.tgz", + "integrity": "sha512-6tcXo4kA8HgGO7AVmawB57RYi/piBPYVHVcO6dXjX+SZw8GoHmi262sp4v2Ha2kNP9Cx84qei27yT+fjS1lxgg==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/@tybys/wasm-util": { + "version": "0.10.4", + "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.4.tgz", + "integrity": "sha512-W3c4gRigFS0T/Ma4qIYF3GDAc5AQdHb1yL5znJT1Zv1YaD9Kitx656wBjvr19qbiosmZT8lWDM5BEMynUqX65A==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@types/debug": { + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz", + "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, + "node_modules/@types/estree": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.10.tgz", + "integrity": "sha512-lTyOMnOcmRBzdCv6/4zUZCrEhV0xrqQiUZBZtVcbmLHBXKLnN8q89v/wKRF/Q0HbwVsqbIG3o5HDoFl9sduM+g==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/estree-jsx": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz", + "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "*" + } + }, + "node_modules/@types/hast": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.5.tgz", + "integrity": "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/mdx": { + "version": "2.0.14", + "resolved": "https://registry.npmjs.org/@types/mdx/-/mdx-2.0.14.tgz", + "integrity": "sha512-T48PeuJtvLosNTPVhfnIp3i/n3a4g4Bad7YCq5k64D4u7NwDrAotikQ+5+sjtUvBmxCMlbo3dVL+C2dP0rWHzg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/react": { + "version": "19.3.0", + "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz", + "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==", + "dev": true, + "license": "MIT", + "dependencies": { + "csstype": "^3.2.2" + } + }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/@ungap/structured-clone": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.4.0.tgz", + "integrity": "sha512-1mEZtMKPM09vDmQt5y7YvmN2+DFTP7Tg0EWXdic8/C6VRnpb33e4ghisCIE3WZjsE2N8mf+QV1Zqh7ZFYLWInQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/@unhead/react": { + "version": "2.1.17", + "resolved": "https://registry.npmjs.org/@unhead/react/-/react-2.1.17.tgz", + "integrity": "sha512-KmcYksDjlLozL0fxUjIDwH/0k6+Lg2HWHLUPlkRW8Gl08hdB1AbLB5iU9QxFvkaT8p0Q4dFEqZWnz3g6RMeiRA==", + "dev": true, + "license": "MIT", + "dependencies": { + "unhead": "2.1.17" + }, + "funding": { + "url": "https://github.com/sponsors/harlan-zw" + }, + "peerDependencies": { + "react": ">=18.3.1" + } + }, + "node_modules/acorn": { + "version": "8.19.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz", + "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==", + "dev": true, + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/acorn-jsx": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz", + "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/astring": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz", + "integrity": "sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==", + "dev": true, + "license": "MIT", + "bin": { + "astring": "bin/astring" + } + }, + "node_modules/bail": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz", + "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/body-scroll-lock": { + "version": "4.0.0-beta.0", + "resolved": "https://registry.npmjs.org/body-scroll-lock/-/body-scroll-lock-4.0.0-beta.0.tgz", + "integrity": "sha512-a7tP5+0Mw3YlUJcGAKUqIBkYYGlYxk2fnCasq/FUph1hadxlTRjF+gAcZksxANnaMnALjxEddmSi/H3OR8ugcQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/clsx": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz", + "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/collapse-white-space": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/collapse-white-space/-/collapse-white-space-2.1.0.tgz", + "integrity": "sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/compute-scroll-into-view": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/compute-scroll-into-view/-/compute-scroll-into-view-3.1.1.tgz", + "integrity": "sha512-VRhuHOLoKYOy4UbilLbUzbYg93XLjv2PncJC50EuTWPA3gaja1UjBsUP/D/9/juV3vQFr6XBEzn9KCAHdUvOHw==", + "dev": true, + "license": "MIT" + }, + "node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/copy-to-clipboard": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/copy-to-clipboard/-/copy-to-clipboard-3.3.3.tgz", + "integrity": "sha512-2KV8NhB5JqC3ky0r9PMCAZKbUHSwtEo4CwCs0KXgruG43gX5PMqDEBbVU4OUzw2MuAWUfsuFmWvEKG5QRfSnJA==", + "dev": true, + "license": "MIT", + "dependencies": { + "toggle-selection": "^1.0.6" + } + }, + "node_modules/csstype": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz", + "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decode-named-character-reference": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "dev": true, + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/entities": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-9.0.0.tgz", + "integrity": "sha512-oJFNDJg3kTPwAD1cNn2+WmUq4wFoo09npc3Ydf1D7ED4smRiWrsKnaLxykrTWgyGEcusc87P5dxlAleol9kpkg==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=20.19.0" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/esast-util-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/esast-util-from-estree/-/esast-util-from-estree-2.0.0.tgz", + "integrity": "sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/esast-util-from-js": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/esast-util-from-js/-/esast-util-from-js-2.0.1.tgz", + "integrity": "sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "acorn": "^8.0.0", + "esast-util-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/escape-string-regexp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", + "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/estree-util-attach-comments": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-attach-comments/-/estree-util-attach-comments-3.0.0.tgz", + "integrity": "sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-build-jsx": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/estree-util-build-jsx/-/estree-util-build-jsx-3.0.1.tgz", + "integrity": "sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "estree-walker": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-is-identifier-name": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz", + "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-scope": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/estree-util-scope/-/estree-util-scope-1.0.1.tgz", + "integrity": "sha512-B0np3dcdxqILX5e9nEi5/Fr4K7gL4oYFVPV1zRa2e9wRCbQoZZNWOZFYyoInvXUPJXBXjss+QXlWLJChDEHDkA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-to-js": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-to-js/-/estree-util-to-js-2.0.0.tgz", + "integrity": "sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "astring": "^1.8.0", + "source-map": "^0.7.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-util-visit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-visit/-/estree-util-visit-2.0.0.tgz", + "integrity": "sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/estree-walker": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz", + "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0" + } + }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "dev": true, + "license": "MIT" + }, + "node_modules/flexsearch": { + "version": "0.8.212", + "resolved": "https://registry.npmjs.org/flexsearch/-/flexsearch-0.8.212.tgz", + "integrity": "sha512-wSyJr1GUWoOOIISRu+X2IXiOcVfg9qqBRyCPRUdLMIGJqPzMo+jMRlvE83t14v1j0dRMEaBbER/adQjp6Du2pw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/ts-thomas" + }, + { + "type": "paypal", + "url": "https://www.paypal.com/donate/?hosted_button_id=GEVR88FC9BWRW" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/flexsearch" + }, + { + "type": "patreon", + "url": "https://patreon.com/user?u=96245532" + }, + { + "type": "liberapay", + "url": "https://liberapay.com/ts-thomas" + } + ], + "license": "Apache-2.0" + }, + "node_modules/get-east-asian-width": { + "version": "1.7.0", + "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.7.0.tgz", + "integrity": "sha512-XjH1AECxf0giL2V1aU8vKyRR2ppRUb5c0EvT7zuJTokQ74bNo52zOtghqdWIqrhUD79fo3x0WfKZdOqxF6LG1Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/hast-util-from-parse5": { + "version": "8.0.4", + "resolved": "https://registry.npmjs.org/hast-util-from-parse5/-/hast-util-from-parse5-8.0.4.tgz", + "integrity": "sha512-Yq7XlXor0Cpb71sI2E0zpv8QxQ5a6rfhDEETk4bcgrFX2SvJAY2PHocWwFtL6U9qyfiyByW3wZ6sZEfP2kW81g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "devlop": "^1.0.0", + "hastscript": "^9.0.0", + "property-information": "^7.0.0", + "vfile": "^6.0.0", + "vfile-location": "^5.0.0", + "web-namespaces": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-heading-rank": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-heading-rank/-/hast-util-heading-rank-3.0.0.tgz", + "integrity": "sha512-EJKb8oMUXVHcWZTDepnr+WNbfnXKFNf9duMesmr4S8SXTJBJ9M4Yok08pu9vxdJwdlGRhVumk9mEhkEvKGifwA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-is-element": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-3.0.0.tgz", + "integrity": "sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-parse-selector": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-4.0.0.tgz", + "integrity": "sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-raw": { + "version": "9.2.0", + "resolved": "https://registry.npmjs.org/hast-util-raw/-/hast-util-raw-9.2.0.tgz", + "integrity": "sha512-1zVq3M9AlZiBZ4mlMPnLtkK2rdd+I8VhmFLNLb//XJm6xA2AVH2tz19EHy25RgRWut6z6FpTARAs7P8rnmRJUQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "@ungap/structured-clone": "^1.0.0", + "hast-util-from-parse5": "^8.0.0", + "hast-util-to-parse5": "^8.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "parse5": "^8.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0", + "web-namespaces": "^2.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-estree": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/hast-util-to-estree/-/hast-util-to-estree-3.1.3.tgz", + "integrity": "sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-attach-comments": "^3.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-js": "^1.0.0", + "unist-util-position": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-html": { + "version": "9.0.6", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.6.tgz", + "integrity": "sha512-1SZUxCN3TtJAE7e2BQN2MBHsoZ1gnmi9GoCP5Di59CSWptIezSAW09yDZyVbanb78V9eCwrKqdQsjtfVTxYHWA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-jsx-runtime": { + "version": "2.3.7", + "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.7.tgz", + "integrity": "sha512-F7DNV2NMcTxA4GqPVHnXzX+mpoPHAIY9rJAVH3CZ1FdBZOcBUEjUuvMkMpHVs/sicEtznh9tMGj5WUR9S4E2rg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "hast-util-whitespace": "^3.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "style-to-object": "^2.0.0", + "unist-util-position": "^5.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-parse5": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/hast-util-to-parse5/-/hast-util-to-parse5-8.0.1.tgz", + "integrity": "sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "devlop": "^1.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "web-namespaces": "^2.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-string": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz", + "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hastscript": { + "version": "9.0.3", + "resolved": "https://registry.npmjs.org/hastscript/-/hastscript-9.0.3.tgz", + "integrity": "sha512-1ALZXSmCGmW3h8AMz4R4+QKSKFi7sNgXLVwmwB8FYVtl1CwQ3WDkSAEY/d5tp1g/vbQgq2s1WlHgfO3jbw1TsA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-parse-selector": "^4.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hookable": { + "version": "6.1.2", + "resolved": "https://registry.npmjs.org/hookable/-/hookable-6.1.2.tgz", + "integrity": "sha512-+abwxtiEA52GCVIsQqut3S/uKTbUwYIp4Pe/vv+6py5XiXBCqMZHg6pA6Y5qhgLSEys0/cYuPbO0z1QFj5ZCmg==", + "dev": true, + "license": "MIT" + }, + "node_modules/html-void-elements": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz", + "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/inline-style-parser": { + "version": "0.2.9", + "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.9.tgz", + "integrity": "sha512-IttN8BqKLxzUrnTqHI+/hwAJQItBAUjdoHERCDv+oOuX48VP6bzW8+QjOXSfoevzq3YrYAwX1uLHp8TqO9yIeg==", + "dev": true, + "license": "MIT" + }, + "node_modules/is-absolute-url": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/is-absolute-url/-/is-absolute-url-4.0.1.tgz", + "integrity": "sha512-/51/TKE88Lmm7Gc4/8btclNXWS+g50wXhYJq8HWIBAGUBnoAdRu1aXeh364t/O7wXDAcTJDP8PNuNKWUDWie+A==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-plain-obj": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz", + "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/longest-streak": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz", + "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/markdown-extensions": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/markdown-extensions/-/markdown-extensions-2.0.0.tgz", + "integrity": "sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdown-table": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.1.0.tgz", + "integrity": "sha512-xpeSCdM+B+6P3ncfgaB7FoDbtJ30xAe6Z18TGT7AgXJsHqCElCICZovQqdRMm7kHgpTyYv36EupqewoFFSB8vw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/mdast-util-find-and-replace": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.4.tgz", + "integrity": "sha512-z4B5c6jrnJ1ltOQemhWYPBSAo6y42Z8Gt2yEgfgNTMcLSU59B8bfj8Z8AnAlJrBGLnqkdAUZ7jdDEqQw3KuipQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "escape-string-regexp": "^5.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-from-markdown": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.1.0.tgz", + "integrity": "sha512-KRLgmPaP2H1ul2bpoJkOS+9pAcDAAj9Nu1mqLnh8NLeJG5tlvj42TH80PIGBpROWlRXLk0lDrWNuZCFy/tsB4A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark": "^4.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz", + "integrity": "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-gfm-autolink-literal": "^2.0.0", + "mdast-util-gfm-footnote": "^2.0.0", + "mdast-util-gfm-strikethrough": "^2.0.0", + "mdast-util-gfm-table": "^2.0.0", + "mdast-util-gfm-task-list-item": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-autolink-literal": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.1.0.tgz", + "integrity": "sha512-Jx6QSK8wDo558Bcf7q+1pe0v81g2PVs09Hlvu9xJHmCFRF3sAPW7vXFVIAwBncs3sde92WbsVqNxwdqViA2XnQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "ccount": "^2.0.0", + "devlop": "^1.0.0", + "mdast-util-find-and-replace": "^3.0.0", + "micromark-util-character": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-strikethrough": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.1.tgz", + "integrity": "sha512-OuJHqvr455pwu2OaOrir7dbzqs4jlWKOtlu9L6GjcIjjQwNyw02VntQsr/Ek6/A13vgnXfUhBekWRUP1OkNivw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-table": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.1.tgz", + "integrity": "sha512-fiIjPrAy4kz68/eFbPHhsiWDGHhqUSVoU1XsfLM5DsEPXw7MxgiVVyulUggFRckVWeT1KXQXkg5vm3kv4oMSOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "markdown-table": "^3.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "mdast-util-to-string": "^4.0.0", + "unist-util-visit": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-gfm-task-list-item": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.1.tgz", + "integrity": "sha512-jXVO1hvB2hs82g1esi7I9nIJDqiijbQLIyH2jDUb5s7jIAZMr/79h0VHSq7XHKTqpLARRm+DDNjduB7S9+6XZA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-mdx/-/mdast-util-mdx-3.0.0.tgz", + "integrity": "sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-mdx-expression": "^2.0.0", + "mdast-util-mdx-jsx": "^3.0.0", + "mdast-util-mdxjs-esm": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-expression": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz", + "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdx-jsx": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.1.tgz", + "integrity": "sha512-oXp1GIa+E9IwIs3a106+tr3Bz2MlTTBvlXjOZMoIat11kk7vjqgmBnksB9WHmWv+gZh7k3IUgpAHlwHB7DH4GQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "devlop": "^1.1.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0", + "parse-entities": "^4.0.0", + "stringify-entities": "^4.0.0", + "unist-util-stringify-position": "^4.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-mdxjs-esm": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz", + "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "mdast-util-from-markdown": "^2.0.0", + "mdast-util-to-markdown": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-phrasing": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz", + "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.1", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.1.tgz", + "integrity": "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.2.3.tgz", + "integrity": "sha512-dImdB6VZRMRac1SwAW6o1c0ESk/7pFFAMCMuKM+9v7LpTSthMM5nzXpqKw4Mjo66aXVKhNkyrP4bMB9MurPyWg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "longest-streak": "^3.0.0", + "mdast-util-phrasing": "^4.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "unist-util-visit": "^5.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-markdown-cjk-friendly": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown-cjk-friendly/-/mdast-util-to-markdown-cjk-friendly-1.0.2.tgz", + "integrity": "sha512-1HCuZwTxQX3WfaNFk8PDb/VW8Ulvzn+nHD+W79Q9k5NXUSkGXH9Zv3eMJ4VI7GjZIz4Ff7WbruEFgMUaPmRJ8g==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-to-markdown": "^2.1.3", + "micromark-extension-cjk-friendly-util": "3.0.1", + "micromark-util-character": "^2.1.1", + "micromark-util-classify-character": "^2.0.1", + "micromark-util-html-tag-name": "^2.0.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/mdast": "*" + }, + "peerDependenciesMeta": { + "@types/mdast": { + "optional": true + } + } + }, + "node_modules/mdast-util-to-markdown-cjk-friendly-gfm-strikethrough": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/mdast-util-to-markdown-cjk-friendly-gfm-strikethrough/-/mdast-util-to-markdown-cjk-friendly-gfm-strikethrough-1.0.2.tgz", + "integrity": "sha512-aidUweNq42Mok1p6KTJG7m0Ds0+njX3Sp6shhh3/VhwIkyWdn2SqEzkeiwJsK+Ksz0pL6vZUHrVFgFtyX9NMYg==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-gfm-strikethrough": "^2.0.1", + "mdast-util-to-markdown": "^2.1.3", + "mdast-util-to-markdown-cjk-friendly": "1.0.2" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/mdast": "*" + }, + "peerDependenciesMeta": { + "@types/mdast": { + "optional": true + } + } + }, + "node_modules/mdast-util-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/medium-zoom": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/medium-zoom/-/medium-zoom-1.1.2.tgz", + "integrity": "sha512-0wTqeCQ4NGzjPghi7i2lMI6RyGj9N60fGvzY9HiNcxDTcvOw7S+ri7K3xVkrIZ+2uzUg4w/KSVMDdZXYMtHkdw==", + "dev": true, + "license": "MIT", + "workspaces": [ + "website", + "examples/*" + ] + }, + "node_modules/micromark": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.3.tgz", + "integrity": "sha512-oGYfQzHSG5dOMovQcJ3fyTmZlWAWpi0XA0sJwJs+i6OT88o1+Jtw/8z0CmdowSLxGhhFK89rQ/oXph/wN02PNw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-edit-map": "^1.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.4.tgz", + "integrity": "sha512-wxEeE8v8XVvOrxn1TZj74qYhAtTQsSqufHVS3uNVyT1MupXxhyaHk8/9xDNPh9BmL77QNDgWTkZ3RsYHB2ry7w==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.1.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-edit-map": "^1.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.3" + } + }, + "node_modules/micromark-extension-cjk-friendly": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-extension-cjk-friendly/-/micromark-extension-cjk-friendly-2.0.2.tgz", + "integrity": "sha512-/BqZNCkDWg3Hj9zEEcRitZ5uMF3X78qmBFuP17oAjnVDZ0+H1GHiDKMJZDpJsXasCHEn/kzl6QHozUiWgCHtPQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.1.0", + "micromark-extension-cjk-friendly-util": "3.0.1", + "micromark-util-chunked": "^2.0.1", + "micromark-util-resolve-all": "^2.0.1", + "micromark-util-symbol": "^2.0.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "micromark": "^4.0.0", + "micromark-util-types": "^2.0.0" + }, + "peerDependenciesMeta": { + "micromark-util-types": { + "optional": true + } + } + }, + "node_modules/micromark-extension-cjk-friendly-gfm-strikethrough": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-extension-cjk-friendly-gfm-strikethrough/-/micromark-extension-cjk-friendly-gfm-strikethrough-2.0.1.tgz", + "integrity": "sha512-wVC0zwjJNqQeX+bb07YTPu/CvSAyCTafyYb7sMhX1r62/Lw5M/df3JyYaANyp8g15c1ypJRFSsookTqA1IDsUg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.1.0", + "get-east-asian-width": "^1.4.0", + "micromark-extension-cjk-friendly-util": "3.0.1", + "micromark-util-character": "^2.1.1", + "micromark-util-chunked": "^2.0.1", + "micromark-util-resolve-all": "^2.0.1", + "micromark-util-symbol": "^2.0.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "micromark": "^4.0.0", + "micromark-util-types": "^2.0.0" + }, + "peerDependenciesMeta": { + "micromark-util-types": { + "optional": true + } + } + }, + "node_modules/micromark-extension-cjk-friendly-util": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/micromark-extension-cjk-friendly-util/-/micromark-extension-cjk-friendly-util-3.0.1.tgz", + "integrity": "sha512-GcbXqTTHOsiZHyF753oIddP/J2eH8j9zpyQPhkof6B2JNxfEJabnQqxbCgzJNuNes0Y2jTNJ3LiYPSXr6eJA8w==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-east-asian-width": "^1.4.0", + "micromark-util-character": "^2.1.1", + "micromark-util-symbol": "^2.0.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependenciesMeta": { + "micromark-util-types": { + "optional": true + } + } + }, + "node_modules/micromark-extension-gfm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz", + "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark-extension-gfm-autolink-literal": "^2.0.0", + "micromark-extension-gfm-footnote": "^2.0.0", + "micromark-extension-gfm-strikethrough": "^2.0.0", + "micromark-extension-gfm-table": "^2.0.0", + "micromark-extension-gfm-tagfilter": "^2.0.0", + "micromark-extension-gfm-task-list-item": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-autolink-literal": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz", + "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-strikethrough": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz", + "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-table": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.2.tgz", + "integrity": "sha512-pRzm4kDTu0MjlmBkxmS9yYhw60nncfcEwu9NNdPFSQEFXS95ZKyIIyTSHu/o3ReBUrLKYEq+7YaXCRn/bPB4MA==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-tagfilter": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz", + "integrity": "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-task-list-item": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz", + "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdx-expression": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-expression/-/micromark-extension-mdx-expression-3.0.1.tgz", + "integrity": "sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-extension-mdx-jsx": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-jsx/-/micromark-extension-mdx-jsx-3.0.2.tgz", + "integrity": "sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "estree-util-is-identifier-name": "^3.0.0", + "micromark-factory-mdx-expression": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdx-md": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdx-md/-/micromark-extension-mdx-md-2.0.0.tgz", + "integrity": "sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs/-/micromark-extension-mdxjs-3.0.0.tgz", + "integrity": "sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "acorn": "^8.0.0", + "acorn-jsx": "^5.0.0", + "micromark-extension-mdx-expression": "^3.0.0", + "micromark-extension-mdx-jsx": "^3.0.0", + "micromark-extension-mdx-md": "^2.0.0", + "micromark-extension-mdxjs-esm": "^3.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-mdxjs-esm": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs-esm/-/micromark-extension-mdxjs-esm-3.0.0.tgz", + "integrity": "sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-mdx-expression": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-factory-mdx-expression/-/micromark-factory-mdx-expression-2.0.3.tgz", + "integrity": "sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-events-to-acorn": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-position-from-estree": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.1.0.tgz", + "integrity": "sha512-fS8hnLIjnjvdQIj39Geug8wWsR0HrYZ43KShKxNfwT7t2LOHo/LbWZEzEaSOjwtjdCsjoE6syHhonEzW0zv0+Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-string": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz", + "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-edit-map": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/micromark-util-edit-map/-/micromark-util-edit-map-1.0.0.tgz", + "integrity": "sha512-Pa2ljlsEL6sVwFaYeyrOLSYbQt73JvGbPOYFq+9AElXiSnfI5Q4465RRZ1sHv7lDjDOnGRDDaqPXqClqWK/q1Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-events-to-acorn": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-util-events-to-acorn/-/micromark-util-events-to-acorn-2.0.3.tgz", + "integrity": "sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/unist": "^3.0.0", + "devlop": "^1.0.0", + "estree-util-visit": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "vfile-message": "^4.0.0" + } + }, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", + "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.3.tgz", + "integrity": "sha512-oxB2Ik03hI0gv+VNn9tnh1t1YEe9MDPptViAEgfdf3YQHsn0pzGTgCdlSCJXcwhqm8phaEuM7zeEu3QQzVBrPg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/nprogress": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/nprogress/-/nprogress-0.2.0.tgz", + "integrity": "sha512-I19aIingLgR1fmhftnbWWO3dXc0hSxqHQHQb3H8m+K3TnEn/iSeTZZOyvKXWqQESMwuUVnatlCnZdLBZZt2VSA==", + "dev": true, + "license": "MIT" + }, + "node_modules/oniguruma-parser": { + "version": "0.12.2", + "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.2.tgz", + "integrity": "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==", + "dev": true, + "license": "MIT" + }, + "node_modules/oniguruma-to-es": { + "version": "4.3.6", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.6.tgz", + "integrity": "sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==", + "dev": true, + "license": "MIT", + "dependencies": { + "oniguruma-parser": "^0.12.2", + "regex": "^6.1.0", + "regex-recursion": "^6.0.2" + } + }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse-entities/node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "dev": true, + "license": "MIT" + }, + "node_modules/parse5": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.1.0.tgz", + "integrity": "sha512-sq3qBFpee5jeocbFbO48VHlGr8sT7mbXS0vxlKN6sottBtJzrOG3998sr0llSZcQAGgfpdmEYAIZE0P9z0dE8w==", + "dev": true, + "license": "MIT", + "dependencies": { + "entities": "^9.0.0" + }, + "funding": { + "url": "https://github.com/inikulin/parse5?sponsor=1" + } + }, + "node_modules/property-information": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.2.0.tgz", + "integrity": "sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/react": { + "version": "19.3.1", + "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz", + "integrity": "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-dom": { + "version": "19.3.1", + "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.1.tgz", + "integrity": "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "scheduler": "^0.28.0" + }, + "peerDependencies": { + "react": "^19.3.1" + } + }, + "node_modules/react-lazy-with-preload": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/react-lazy-with-preload/-/react-lazy-with-preload-2.2.1.tgz", + "integrity": "sha512-ONSb8gizLE5jFpdHAclZ6EAAKuFX2JydnFXPPPjoUImZlLjGtKzyBS8SJgJq7CpLgsGKh9QCZdugJyEEOVC16Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/react-reconciler": { + "version": "0.33.0", + "resolved": "https://registry.npmjs.org/react-reconciler/-/react-reconciler-0.33.0.tgz", + "integrity": "sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA==", + "dev": true, + "license": "MIT", + "dependencies": { + "scheduler": "^0.27.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "peerDependencies": { + "react": "^19.2.0" + } + }, + "node_modules/react-reconciler/node_modules/scheduler": { + "version": "0.27.0", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz", + "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/react-refresh": { + "version": "0.19.0", + "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.19.0.tgz", + "integrity": "sha512-5HdstYgoJBbBofjapO5qCPcovECJCBfvjLb+iTcsmqDFVMRdqy0qs7iiInBJTUXmIFc2bjoc5b2HVLp2zRtYhQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-render-to-markdown": { + "version": "19.1.0", + "resolved": "https://registry.npmjs.org/react-render-to-markdown/-/react-render-to-markdown-19.1.0.tgz", + "integrity": "sha512-dF9b3tO41ezqdmHP8X92kbHbMexJ6iC7iHw4ykC8fwiO7DgpFc9PhMoKlI+BcPzRxGcWgQSdrixVB9RykhjJpQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "react-reconciler": "0.33.0" + }, + "peerDependencies": { + "react": ">=19" + } + }, + "node_modules/react-router": { + "version": "7.18.5", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.18.5.tgz", + "integrity": "sha512-dTgvcXDOrLPrlLHrcZAqWveiK1hMSqN+rGAJzegP8HtmNkfRxOoshGWBNX3ZJ0cZjOHkRdlUJtaIhZMLLyGyPw==", + "dev": true, + "license": "MIT", + "dependencies": { + "cookie": "^1.0.1", + "set-cookie-parser": "^2.6.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "react": ">=18", + "react-dom": ">=18" + }, + "peerDependenciesMeta": { + "react-dom": { + "optional": true + } + } + }, + "node_modules/react-router-dom": { + "version": "7.18.5", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.18.5.tgz", + "integrity": "sha512-9HcfDMU6JJ/fp6gJZYGwNE6RknVGS4kBjH1HkNw959mCJi70TVwdipQWv2FEol9uGpi+SZTFtVpJPtEQfayeOw==", + "dev": true, + "license": "MIT", + "dependencies": { + "react-router": "7.18.5" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "react": ">=18", + "react-dom": ">=18" + } + }, + "node_modules/recma-build-jsx": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-build-jsx/-/recma-build-jsx-1.0.0.tgz", + "integrity": "sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-util-build-jsx": "^3.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-jsx": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/recma-jsx/-/recma-jsx-1.0.1.tgz", + "integrity": "sha512-huSIy7VU2Z5OLv6oFLosQGGDqPqdO1iq6bWNAdhzMxSJP7RAso4fCZ1cKu8j9YHCZf3TPrq4dw3okhrylgcd7w==", + "dev": true, + "license": "MIT", + "dependencies": { + "acorn-jsx": "^5.0.0", + "estree-util-to-js": "^2.0.0", + "recma-parse": "^1.0.0", + "recma-stringify": "^1.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" + } + }, + "node_modules/recma-parse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-parse/-/recma-parse-1.0.0.tgz", + "integrity": "sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "esast-util-from-js": "^2.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/recma-stringify": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/recma-stringify/-/recma-stringify-1.0.0.tgz", + "integrity": "sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "estree-util-to-js": "^2.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/regex": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/regex/-/regex-6.1.0.tgz", + "integrity": "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz", + "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==", + "dev": true, + "license": "MIT" + }, + "node_modules/rehype-external-links": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/rehype-external-links/-/rehype-external-links-3.0.0.tgz", + "integrity": "sha512-yp+e5N9V3C6bwBeAC4n796kc86M4gJCdlVhiMTxIrJG5UHDMh+PJANf9heqORJbt1nrCbDwIlAZKjANIaVBbvw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@ungap/structured-clone": "^1.0.0", + "hast-util-is-element": "^3.0.0", + "is-absolute-url": "^4.0.0", + "space-separated-tokens": "^2.0.0", + "unist-util-visit": "^5.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-raw": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/rehype-raw/-/rehype-raw-7.0.0.tgz", + "integrity": "sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-raw": "^9.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/rehype-recma": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/rehype-recma/-/rehype-recma-1.0.0.tgz", + "integrity": "sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.0", + "@types/hast": "^3.0.0", + "hast-util-to-estree": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-cjk-friendly": { + "version": "2.3.4", + "resolved": "https://registry.npmjs.org/remark-cjk-friendly/-/remark-cjk-friendly-2.3.4.tgz", + "integrity": "sha512-xhBzjXkumeN5tKXXg6k/THSCZCP6AYV6+wSxnCsPTkxHt60bb9Yk0IWhdD87CFaDCiTqd86LKHtVObcJTmgcow==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-to-markdown-cjk-friendly": "1.0.2", + "micromark-extension-cjk-friendly": "2.0.2" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/mdast": "^4.0.0", + "unified": "^11.0.0" + }, + "peerDependenciesMeta": { + "@types/mdast": { + "optional": true + } + } + }, + "node_modules/remark-cjk-friendly-gfm-strikethrough": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/remark-cjk-friendly-gfm-strikethrough/-/remark-cjk-friendly-gfm-strikethrough-2.3.3.tgz", + "integrity": "sha512-UBujdRd1TTgr79iPdXhCnB9ag7kaM54FBCzTa/jLCNfZFGPyZCZb8G6yoCA0k4M3HTKDvilIVKvPxU6K/05dDw==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-to-markdown-cjk-friendly-gfm-strikethrough": "1.0.2", + "micromark-extension-cjk-friendly-gfm-strikethrough": "2.0.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/mdast": "^4.0.0", + "unified": "^11.0.0" + }, + "peerDependenciesMeta": { + "@types/mdast": { + "optional": true + } + } + }, + "node_modules/remark-gfm": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz", + "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-gfm": "^3.0.0", + "micromark-extension-gfm": "^3.0.0", + "remark-parse": "^11.0.0", + "remark-stringify": "^11.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-mdx": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.1.1.tgz", + "integrity": "sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==", + "dev": true, + "license": "MIT", + "dependencies": { + "mdast-util-mdx": "^3.0.0", + "micromark-extension-mdxjs": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-parse": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz", + "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-rehype": { + "version": "11.1.2", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.2.tgz", + "integrity": "sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "mdast-util-to-hast": "^13.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/remark-stringify": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz", + "integrity": "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-to-markdown": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/scheduler": { + "version": "0.28.0", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz", + "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==", + "dev": true, + "license": "MIT" + }, + "node_modules/scroll-into-view-if-needed": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/scroll-into-view-if-needed/-/scroll-into-view-if-needed-3.1.0.tgz", + "integrity": "sha512-49oNpRjWRvnU8NyGVmUaYG4jtTkNonFZI86MmGRDqBphEK2EXT9gdEUoQPZhuBM8yWHxCWbobltqYO5M4XrUvQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "compute-scroll-into-view": "^3.0.2" + } + }, + "node_modules/set-cookie-parser": { + "version": "2.7.3", + "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.3.tgz", + "integrity": "sha512-irZHtTqurLna57KQG/s+fzOwv/J6XSH4cs8M/vsrY3uCaQ3S6+QJguAH0WdN47SXlk82voMZ4naWMQf8fdEoIg==", + "dev": true, + "license": "MIT" + }, + "node_modules/shiki": { + "version": "4.6.0", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-4.6.0.tgz", + "integrity": "sha512-imjLsVHgPuWhvpU3P+zOekvMYqnel7QmKsFC4Sn0fCuAvaaalBsxwKEsrU8Ko5BdFnZA6Go/8a0RzahS634UgA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "4.6.0", + "@shikijs/engine-javascript": "4.6.0", + "@shikijs/engine-oniguruma": "4.6.0", + "@shikijs/langs": "4.6.0", + "@shikijs/themes": "4.6.0", + "@shikijs/types": "4.6.0", + "@shikijs/vscode-textmate": "^10.1.0", + "@types/hast": "^3.0.5" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/source-map": { + "version": "0.7.6", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz", + "integrity": "sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">= 12" + } + }, + "node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "dev": true, + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/style-to-js": { + "version": "1.1.21", + "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz", + "integrity": "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "style-to-object": "1.0.14" + } + }, + "node_modules/style-to-js/node_modules/inline-style-parser": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz", + "integrity": "sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==", + "dev": true, + "license": "MIT" + }, + "node_modules/style-to-js/node_modules/style-to-object": { + "version": "1.0.14", + "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.14.tgz", + "integrity": "sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==", + "dev": true, + "license": "MIT", + "dependencies": { + "inline-style-parser": "0.2.7" + } + }, + "node_modules/style-to-object": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-2.0.2.tgz", + "integrity": "sha512-QmbXPUylqU80HAgTOJeEOdbA40W9KtxmjMhQy+tq+b8F2aoh3aQLuy82hh2jm2qsC9hR9eI0+eQidTMydKcqRA==", + "dev": true, + "license": "MIT", + "dependencies": { + "inline-style-parser": "0.2.9" + } + }, + "node_modules/toggle-selection": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/toggle-selection/-/toggle-selection-1.0.6.tgz", + "integrity": "sha512-BiZS+C1OS8g/q2RRbJmy59xpyghNBqrr6k5L/uKBGRsTfxmu3ffiRnd8mlGPUVayg8pvfi5urfnu8TU7DVOkLQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/trough": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz", + "integrity": "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/tslib": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz", + "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==", + "dev": true, + "license": "0BSD", + "optional": true + }, + "node_modules/unhead": { + "version": "2.1.17", + "resolved": "https://registry.npmjs.org/unhead/-/unhead-2.1.17.tgz", + "integrity": "sha512-HLMKXOszRhAPBrr6VlqCeVeJq2kbC4kXwzGLEZvvojPLWNYTJw22xG7Bfwhsvs31+IBet3Wl8ADg9dwYdyphfQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "hookable": "^6.0.1" + }, + "funding": { + "url": "https://github.com/sponsors/harlan-zw" + } + }, + "node_modules/unified": { + "version": "11.0.5", + "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", + "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "bail": "^2.0.0", + "devlop": "^1.0.0", + "extend": "^3.0.0", + "is-plain-obj": "^4.0.0", + "trough": "^2.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz", + "integrity": "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position-from-estree": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position-from-estree/-/unist-util-position-from-estree-2.0.0.tgz", + "integrity": "sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.2.0.tgz", + "integrity": "sha512-fpsYs/VVoZxfGY9/j3FQpZmN8wdLJaV1Pt38AaJNZu9uKIHcFU3halCdBveEq1HGKO1OEfJY65w1zvoFV1b3qQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-children": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/unist-util-visit-children/-/unist-util-visit-children-3.0.0.tgz", + "integrity": "sha512-RgmdTfSBOg04sdPcpTSD1jzoNBjt9a80/ZCzp5cI9n1qPzLZWF9YdvWGN2zmTumP1HWhXKdUWexjy/Wy/lJ7tA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.1.0.tgz", + "integrity": "sha512-vKXxz6O38sKDj1mtx/k2cWvkkFBuYGx6uGrlzBkVeWCRF/F8sdI0j3Wbkz/5rVNRRuVc8UrgRdbCxNhmYXgP3w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-location": { + "version": "5.0.4", + "resolved": "https://registry.npmjs.org/vfile-location/-/vfile-location-5.0.4.tgz", + "integrity": "sha512-vEvxatYZCIpNvzGk2UD+u4I/sZkSKoOsdRCbkOIsN73QpJbriJ1qvvBAL1PeI0y55Leoqf7pORbaSPpG/smmOg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.4.tgz", + "integrity": "sha512-66ycRswIkNmHH9PHku7ADtv5RVwgIrOcuv3J8Svz6h4qgGRrKVa+9/neuKyJZUXyOpYwLTvS+whZ4R2urHHgQg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/web-namespaces": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz", + "integrity": "sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + } + } +} diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..3aeecf4 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,15 @@ +{ + "name": "@flanksource/telltale-docs", + "private": true, + "type": "module", + "scripts": { + "dev": "rspress dev", + "build": "npm run check:catalog && rspress build", + "check:catalog": "go -C .. run ./hack/docs-catalog --check", + "generate:catalog": "go -C .. run ./hack/docs-catalog", + "preview": "rspress preview" + }, + "devDependencies": { + "@rspress/core": "2.1.0" + } +} diff --git a/docs/replay.md b/docs/replay.md new file mode 100644 index 0000000..0d0f901 --- /dev/null +++ b/docs/replay.md @@ -0,0 +1,19 @@ +# Replay recorded traces + +`telltale trace replay` reads the saved captures of one or more trace/run IDs. It never executes the recorded commands. Find IDs with `telltale trace list`, then pass them as positional arguments: + +```sh +telltale trace list +telltale trace replay buildhost20261107T123000Z +telltale trace replay buildhost20261107T123000Z buildhost20261107T123000Z_2 --ui +telltale trace replay buildhost20261107T123000Z --tui +telltale trace replay buildhost20261107T123000Z --format ndjson --sort timestamp +``` + +Replace the example IDs with ones from your data directory. Every form accepts `--data-dir` when the recordings live outside the default cache directory. Unknown IDs, duplicate selections, invalid paths and recordings without a readable manifest fail before any records are printed. + +Terminal output reads every page, merging captures by `--sort seq` (the default) or `--sort timestamp`. Sequence numbers belong to individual streams. NDJSON records include `runId`, `kind`, `stream`, `seq`, `timestamp`, `summary` and the original payload under `record`. `--follow` reads and follows selected captures until their streams seal; live arrivals preserve each stream's order. + +`--ui` opens a loopback viewer restricted to the selected runs and serves until Ctrl+C. A **Run** selector switches between multiple recordings and retains the selection in the URL. Kind-specific rendering opens in **Captures**; **Raw stream** opens the record table and JSON details on demand. `--tui` opens the full-screen kind monitors and separate stdout/stderr tabs. Tab/Shift+Tab switches kinds; `[` and `]` switch selected runs, retaining each run's tab state. Older combined recordings display their saved output in Stdout and explicitly report that separate stderr is unavailable. Attached processes without recorded output show an unavailable message. Choose one of `--ui` and `--tui`. + +New trace IDs concatenate up to nine characters from the short hostname with a compact UTC timestamp: `buildhost20261107T123000Z`. Hostname dashes are removed, and the timestamp contains no dashes. Runs created on the same host in the same second receive `_2`, `_3`, and subsequent suffixes. Existing recordings keep their IDs and remain selectable. Listing and retention use recorded start times across hostnames and ID formats; stores without a manifest use their directory modification time for retention. diff --git a/docs/rspress.config.ts b/docs/rspress.config.ts new file mode 100644 index 0000000..f27ce8e --- /dev/null +++ b/docs/rspress.config.ts @@ -0,0 +1,67 @@ +import { defineConfig } from '@rspress/core'; + +export default defineConfig({ + root: '.', + title: 'Telltale', + description: 'Trace applications and inspect the processes running on your host.', + outDir: 'doc_build', + route: { + extensions: ['.md', '.mdx'], + exclude: ['plans/**', 'doc_build/**'], + }, + builderConfig: { + plugins: [{ + name: 'telltale-docs-watch', + setup(api) { + api.modifyRsbuildConfig((config) => { + const watches = config.dev?.watchFiles; + if (!watches) return; + for (const watch of Array.isArray(watches) ? watches : [watches]) { + if (watch.type !== 'restart') continue; + const ignored = watch.options?.ignored; + watch.options = { + ...watch.options, + ignored: [ + ...(ignored ? (Array.isArray(ignored) ? ignored : [ignored]) : []), + /(^|[/\\])(node_modules|\.git|\.rspress|doc_build|plans)([/\\]|$)/, + ], + }; + } + }); + }, + }], + }, + themeConfig: { + nav: [ + { text: 'Guide', link: '/getting-started' }, + { text: 'GitHub', link: 'https://github.com/flanksource/telltale' }, + ], + sidebar: { + '/': [ + { + text: 'Get started', + items: [ + { text: 'Introduction', link: '/' }, + { text: 'Quick start', link: '/getting-started' }, + ], + }, + { + text: 'Guides', + items: [ + { text: 'Web workspace', link: '/web-ui' }, + { text: 'OpenTelemetry receiver', link: '/otlp-receiver' }, + { text: 'Resource monitoring rules', link: '/rules' }, + { text: 'SQL Server and JVM captures', link: '/sqlserver-jvm' }, + ], + }, + { + text: 'Trace kinds', + items: [ + { text: 'Overview', link: '/traces/' }, + ...['exec', 'goprof', 'http', 'jvm_jfr', 'llm', 'logs', 'process', 'prometheus', 'query', 'spans', 'sql', 'sql_deadlock', 'sql_plancache', 'sql_xevent', 'stacks', 'terminal'].map((kind) => ({ text: kind, link: `/traces/${kind}` })), + ], + }, + ], + }, + }, +}); diff --git a/docs/rules.md b/docs/rules.md index 091721a..d196923 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -94,7 +94,7 @@ timeout: 5s ## Concurrent browser, test and build jobs -[The concurrency example](../examples/concurrency-rules.yaml) uses `groupBy: host` to detect excessive independent jobs across repositories: +[The concurrency example](https://github.com/flanksource/telltale/blob/main/examples/concurrency-rules.yaml) uses `groupBy: host` to detect excessive independent jobs across repositories: | Rule | Allowed concurrent jobs | Counted roots | | --- | --- | --- | diff --git a/docs/sqlserver-jvm.md b/docs/sqlserver-jvm.md index 831c0d3..300e934 100644 --- a/docs/sqlserver-jvm.md +++ b/docs/sqlserver-jvm.md @@ -4,7 +4,7 @@ ## SQL Server -Configure a SQL Server connection using the [connection configuration](../README.md) and pass its `connection://name` reference. These captures need neither a local PID nor a command. An empty database filter selects the connection's database; `--databases '*'` selects all databases. Filters accept exact names, `*` wildcards, and `!` exclusions. +Configure a SQL Server connection using the [connection configuration](https://github.com/flanksource/telltale#connections) and pass its `connection://name` reference. These captures need neither a local PID nor a command. An empty database filter selects the connection's database; `--databases '*'` selects all databases. Filters accept exact names, `*` wildcards, and `!` exclusions. ```sh telltale run sql_xevent --connection connection://orders --session-name diagnostic --min-duration 10ms --duration 30s diff --git a/docs/traces/exec.mdx b/docs/traces/exec.mdx new file mode 100644 index 0000000..b245cd5 --- /dev/null +++ b/docs/traces/exec.mdx @@ -0,0 +1,12 @@ +# exec + +import { KindReference } from '../_components/KindReference'; + +Records Clicky executions observed in Telltale itself or an instrumented agent, including output tails and environment variable names. The default `self` seam observes Telltale; use `agent` for a connected agent. + +```sh +telltale run exec --pid 1234 --name git --duration 1m +``` + +`--name` filters executable names with a glob, and `--tail-bytes` limits each output tail (default 4096 bytes). Select an agent with `--pid`, `--agent`, or `--selector`; `--wait` waits for a matching agent. Run `telltale run exec --help` for all options. + diff --git a/docs/traces/goprof.mdx b/docs/traces/goprof.mdx new file mode 100644 index 0000000..1eca299 --- /dev/null +++ b/docs/traces/goprof.mdx @@ -0,0 +1,12 @@ +# goprof + +import { KindReference } from '../_components/KindReference'; + +Reads Go pprof profiles at checkpoints from a command, an attached process, or an agent. The default process source is a [gops agent](https://github.com/google/gops) in the target process, discovered through its port file. + +```sh +telltale run goprof --pid 1234 --duration 1m --every 15s +``` + +`--profile` selects `heap` (default), `cpu`, `allocs`, `mutex`, `block`, or `goroutine`; `--source` selects `gops`, `pprof`, or `file`. `--seconds` sets the CPU profile window. Checkpoints occur at `--every` and once when an attached run stops. Run `telltale run goprof --help` for all options. + diff --git a/docs/traces/http.mdx b/docs/traces/http.mdx new file mode 100644 index 0000000..8fdf2a4 --- /dev/null +++ b/docs/traces/http.mdx @@ -0,0 +1,12 @@ +# http + +import { KindReference } from '../_components/KindReference'; + +Records HTTP exchanges from Telltale, an instrumented agent, or a local proxy. The default seam is `self`; choose `proxy` to route a command through the capture. + +```sh +telltale run http --seam proxy --mode mitm -- curl -sS https://example.com +``` + +`--mode connect` records HTTPS tunnels by host; `mitm` decrypts exchanges using an ephemeral CA exported to the command. `--hosts` and `--paths` filter traffic, `--bodies` limits retained body size, and `--redact` adds headers to redact. The proxy exports standard proxy and CA environment variables; the application must honor them. Run `telltale run http --help` for all options. + diff --git a/docs/traces/index.md b/docs/traces/index.md new file mode 100644 index 0000000..4a60608 --- /dev/null +++ b/docs/traces/index.md @@ -0,0 +1,26 @@ +# Trace kinds + +Each trace kind records a particular source. Run one with `telltale run `, or combine captures using `telltale trace run --trace`. Run `telltale run --help` for the complete, schema-derived flags for your installed version. + +The target seam determines what is observed: `process` follows a command or PID, `host` observes host resources or remote services, `connection` uses a configured database, `proxy` routes a command through a local proxy, `agent` observes an instrumented agent, and `self` observes Telltale's own instrumented sources. A self capture does not automatically record the command's activity. + +| Kind | Records | +| --- | --- | +| [exec](/traces/exec) | Instrumented command executions | +| [goprof](/traces/goprof) | Go profiles at checkpoints | +| [http](/traces/http) | HTTP exchanges | +| [jvm_jfr](/traces/jvm_jfr) | JVM profiling samples | +| [llm](/traces/llm) | Instrumented LLM provider calls | +| [logs](/traces/logs) | Application logs | +| [process](/traces/process) | Process startup metadata, resource deltas and numeric metrics | +| [prometheus](/traces/prometheus) | Metrics scrapes | +| [query](/traces/query) | Query profile or provider results | +| [spans](/traces/spans) | Application or imported spans | +| [sql](/traces/sql) | Instrumented or proxied SQL statements | +| [sql_deadlock](/traces/sql_deadlock) | SQL Server deadlocks | +| [sql_plancache](/traces/sql_plancache) | SQL Server plan cost deltas | +| [sql_xevent](/traces/sql_xevent) | SQL Server Extended Events | +| [stacks](/traces/stacks) | Process stacks at checkpoints | +| [terminal](/traces/terminal) | Terminal events supplied by a host | + +Runs are stored in the data directory. Use `telltale trace list --kind ` to find runs, and `--follow`, `--tui`, or `--ui` to inspect captures while recording. Some kinds require an instrumented application, a connection, or external tools; their pages explain the relevant prerequisites. diff --git a/docs/traces/jvm_jfr.mdx b/docs/traces/jvm_jfr.mdx new file mode 100644 index 0000000..3924836 --- /dev/null +++ b/docs/traces/jvm_jfr.mdx @@ -0,0 +1,12 @@ +# jvm_jfr + +import { KindReference } from '../_components/KindReference'; + +Profiles a local JVM or a connected Java agent with Flight Recorder or async-profiler. Checkpoints decode new samples into the run store. + +```sh +telltale run jvm_jfr --pid 1234 --duration 30s --every 10s +``` + +The process seam requires a compatible JDK's `jcmd`, attach permission, and JFR. Select `--engine async-profiler --event cpu` (or `wall`, `alloc`, or `lock`) to use async-profiler; local captures require `asprof`. `--threads`, `--interval`, and `--max-stack-depth` control sampling and decoded output. See [SQL Server and JVM captures](/sqlserver-jvm#local-jvm) for prerequisites and [Java agent installation](/sqlserver-jvm#java-agent-installation). + diff --git a/docs/traces/llm.mdx b/docs/traces/llm.mdx new file mode 100644 index 0000000..5f9e57c --- /dev/null +++ b/docs/traces/llm.mdx @@ -0,0 +1,12 @@ +# llm + +import { KindReference } from '../_components/KindReference'; + +Records Captain provider calls in Telltale or an instrumented agent. The default `self` seam observes Telltale itself. + +```sh +telltale run llm --pid 1234 --include-prompts --duration 1m +``` + +Prompts and responses are excluded by default; enable them separately with `--include-prompts` and `--include-responses`. Use `--models` to filter model names by glob. Agent selection supports `--pid`, `--agent`, and `--selector`. Run `telltale run llm --help` for all options. + diff --git a/docs/traces/logs.mdx b/docs/traces/logs.mdx new file mode 100644 index 0000000..a5cdf6d --- /dev/null +++ b/docs/traces/logs.mdx @@ -0,0 +1,12 @@ +# logs + +import { KindReference } from '../_components/KindReference'; + +Records application logs from Telltale, an instrumented agent, or a configured host source. The default seam is `self`. + +```sh +telltale run logs --seam agent --agent my-agent --duration 1m +``` + +Options include `--min-level`, `--match`, and per-logger `--levels`; host-source options include `--backend`, `--connection`, `--query`, `--namespace`, `--pod-selector`, and `--container`. Available settings depend on the selected source. Run `telltale run logs --help` for the complete flags. + diff --git a/docs/traces/process.mdx b/docs/traces/process.mdx new file mode 100644 index 0000000..1be1f51 --- /dev/null +++ b/docs/traces/process.mdx @@ -0,0 +1,35 @@ +# process + +import { KindReference } from '../_components/KindReference'; + +Capture a process tree or the host with one kind and three tables: + +| Result | Storage | Contents | +| --- | --- | --- | +| Primary | `process` | Stable PID/start identity, parent, startup command, CWD, selected masked environment and grouping tags; observed exit updates the same row. | +| `facets` | `process_facets` | Timestamp, tick, process identity, facet, entity, `added`/`removed`, descriptor and direction evidence. | +| `metrics` | `process_metrics` | One numeric column per metric, keyed by process identity, observation time and tick. Unavailable values are NULL; measured zero stays zero. | + +```sh +telltale run process --pid 1234 --facets files,sockets,connections --duration 30s +telltale run process --seam host --duration 1m +telltale records process --run +telltale records process --run --result metrics --stats cpuPercent,rssBytes --group-by entity +telltale records process --run --result facets --follow +telltale trace replay --tui +``` + +Files and receiving sockets can be selected independently. Receiving sockets include TCP listeners and bound UDP sockets. Connections count established TCP peers, collapsed across concurrent sockets to the same remote endpoint: the first adds a peer and closing the last removes it. Listener history supplies inbound inference; a newly observed peer without a listener supplies outbound inference after the initial observation. Other initial peers remain unknown. UDP sockets are not TCP connections. Polling can miss short-lived resources, and unreadable descriptor observations do not remove resources. Observed process exits remove held resources with `reason: observed_exit`. + +Each observation commits identities, deltas and metrics in one transaction. Failed writes leave the observation state unchanged for retry. Metric columns are seeded, grow for newly encountered numeric metrics, and have a bounded count. Group totals are derived from startup grouping information and metric rows; group snapshots and full descriptor lists are not repeated in storage. + +The storage benchmark uses 20 processes with 100 file descriptors each, changes one file per tick and writes 100 observations to SQLite. On an Apple M2 Pro, repeated snapshots used 168,346 bytes per tick and 6.71 ms per write; the unified tables used 33,260 bytes and 5.99 ms. This is about 80% less disk use for that workload. Allocated bytes were slightly higher for the unified writer. Process and descriptor polling are measured separately; delta storage does not reduce the cost of discovering resources, and savings depend on resource churn. + +```sh +go test ./pkg/tracing/processcapture -run '^$' -bench BenchmarkProcessObservationStorage -benchtime=100x -benchmem +go test ./pkg/tracing/processcapture -run '^$' -bench BenchmarkProcessCollection -benchtime=3x -benchmem +``` + +`process_tree`, `process_samples` and `process_groups` recordings require the build that recorded them. This build leaves those files untouched and reports their format as unsupported. + + diff --git a/docs/traces/prometheus.mdx b/docs/traces/prometheus.mdx new file mode 100644 index 0000000..558aab7 --- /dev/null +++ b/docs/traces/prometheus.mdx @@ -0,0 +1,12 @@ +# prometheus + +import { KindReference } from '../_components/KindReference'; + +Scrapes metrics endpoints using a managed Prometheus process. Each completed scrape records its endpoint, health, duration, error, and sample count; the metric samples remain in the managed TSDB. + +```sh +telltale run prometheus --endpoints http://localhost:8080/metrics --interval 5s --duration 1m +``` + +The first capture downloads and starts Prometheus. `--endpoints` accepts multiple URLs, `--interval` defaults to 15 seconds, `--timeout` bounds a scrape, and `--labels` adds labels to samples. Query samples at the URL shown by the run or through the read-only `telltale-prometheus` connection in the server. Stopping capture stops scraping, but retains samples. + diff --git a/docs/traces/query.mdx b/docs/traces/query.mdx new file mode 100644 index 0000000..1379f65 --- /dev/null +++ b/docs/traces/query.mdx @@ -0,0 +1,12 @@ +# query + +import { KindReference } from '../_components/KindReference'; + +Reads a saved commons-db query profile or a provider configured in place over a run's window. The host seam does not require a command or PID. + +```sh +telltale run query --profile pod-cpu-by-pod --every 30s --duration 10m +``` + +`--profile` selects a saved profile; `--provider` accepts typed provider configuration as JSON. `--from` and `--to` set the window, `--every` polls for newer rows, and `--until-stopped` reads once at the end. Supported providers include SQL, Prometheus, OpenSearch, HTTP, PostgREST, BigQuery, Jaeger, and OpenTelemetry. Run `telltale run query --help` for all options. + diff --git a/docs/traces/spans.mdx b/docs/traces/spans.mdx new file mode 100644 index 0000000..bee5155 --- /dev/null +++ b/docs/traces/spans.mdx @@ -0,0 +1,12 @@ +# spans + +import { KindReference } from '../_components/KindReference'; + +Records SDK spans in Telltale or an instrumented agent, or imports span documents from an OpenSearch-backed OpenTelemetry connection using the host seam. + +```sh +telltale run spans --seam host --opensearch-connection traces --opensearch-from now-1h +``` + +Use `--opensearch-follow-index` to follow new documents, `--opensearch-to` to bound a window, and `--opensearch-search` for a structured JSON search. For continuous OTLP ingestion without a capture run, see [Receive OpenTelemetry traces](/otlp-receiver). The [web workspace](/web-ui) can search and inspect recorded spans. + diff --git a/docs/traces/sql.mdx b/docs/traces/sql.mdx new file mode 100644 index 0000000..76e09b3 --- /dev/null +++ b/docs/traces/sql.mdx @@ -0,0 +1,12 @@ +# sql + +import { KindReference } from '../_components/KindReference'; + +Records SQL statements from Telltale, an instrumented agent, or a local PostgreSQL proxy. The default seam is `self`; use `proxy` for a command's database traffic. + +```sh +telltale run sql --seam proxy --env ORDERS_DB_URL -- go test ./... +``` + +The proxy reads the upstream DSN from the named environment variable and exports a proxied DSN under the same name. Alternatively use `--dsn` or the standard database environment variables. `--min-duration` filters statements and `--max-statements` limits retained rows. `--params` includes bind values, which can contain sensitive data. Run `telltale run sql --help` for all options. + diff --git a/docs/traces/sql_deadlock.mdx b/docs/traces/sql_deadlock.mdx new file mode 100644 index 0000000..decd929 --- /dev/null +++ b/docs/traces/sql_deadlock.mdx @@ -0,0 +1,12 @@ +# sql_deadlock + +import { KindReference } from '../_components/KindReference'; + +Reads SQL Server deadlock graphs from `system_health`, either historically or by following new deadlocks. It uses a configured SQL Server connection and does not require a local process. + +```sh +telltale run sql_deadlock --connection connection://orders --duration 1m --poll 5s +``` + +Set `--from` to an RFC 3339 timestamp for a historical read; `--to` is exclusive and defaults to server time. `--databases` filters participants, defaulting to the connected database. Reading requires the appropriate server-state and event-file permissions. See [SQL Server captures](/sqlserver-jvm#sql-server) for retention, shutdown, and permission details. + diff --git a/docs/traces/sql_plancache.mdx b/docs/traces/sql_plancache.mdx new file mode 100644 index 0000000..21cdf15 --- /dev/null +++ b/docs/traces/sql_plancache.mdx @@ -0,0 +1,12 @@ +# sql_plancache + +import { KindReference } from '../_components/KindReference'; + +Samples SQL Server's plan cache, recording interval execution and resource deltas, recompiles, and evictions. Each poll ranks plans by interval CPU. + +```sh +telltale run sql_plancache --connection connection://warehouse --duration 2m --poll 30s --top 200 +``` + +`--databases` and `--text` filter with wildcard and exclusion patterns; `--min-executions` sets a minimum interval execution count. `--top` defaults to 200 and `--poll` to 30 seconds. This connection capture does not need a local process. Run `telltale run sql_plancache --help` for all options. + diff --git a/docs/traces/sql_xevent.mdx b/docs/traces/sql_xevent.mdx new file mode 100644 index 0000000..c4a269c --- /dev/null +++ b/docs/traces/sql_xevent.mdx @@ -0,0 +1,12 @@ +# sql_xevent + +import { KindReference } from '../_components/KindReference'; + +Captures SQL Server Extended Events through a configured connection, either by creating an owned session or reading the existing `system_health` session. + +```sh +telltale run sql_xevent --connection connection://orders --session-name diagnostic --duration 30s +``` + +An owned session requires permission to create and alter server event sessions; Telltale drains and drops only its own session. Use `--session system_health` to read the existing session without changing it. Filters include `--events`, `--databases`, `--users`, `--apps`, `--hosts`, `--types`, and `--tables`. See [SQL Server captures](/sqlserver-jvm#sql-server) for permissions and behavior. + diff --git a/docs/traces/stacks.mdx b/docs/traces/stacks.mdx new file mode 100644 index 0000000..b0c8d6c --- /dev/null +++ b/docs/traces/stacks.mdx @@ -0,0 +1,12 @@ +# stacks + +import { KindReference } from '../_components/KindReference'; + +Dumps Go goroutines or, for other processes, threads using the OS sampler. Observe a command, an attached process, or an agent. + +```sh +telltale run stacks --pid 1234 --duration 1m --every 10s +``` + +Checkpoints run at `--every` and once when an attached run stops. An attached process remains running after capture. Use `--seam agent` with an agent selector for a connected agent, or `--seam self` for Telltale. Run `telltale run stacks --help` for all options. + diff --git a/docs/traces/terminal.mdx b/docs/traces/terminal.mdx new file mode 100644 index 0000000..d11ceea --- /dev/null +++ b/docs/traces/terminal.mdx @@ -0,0 +1,12 @@ +# terminal + +import { KindReference } from '../_components/KindReference'; + +Records terminal events supplied by a host such as a test runner. Arming this kind for a normal command does not feed events into it: the command's output is stored separately as the run's output. + +```sh +telltale run terminal -- true +``` + +The example arms an empty terminal stream. A host feeding events can configure `--width`, `--height`, `--max-bytes`, `--snapshot-interval`, and the command named in the cast header. The supported seam is `self`. Run `telltale run terminal --help` for all options. + diff --git a/docs/vitest.config.ts b/docs/vitest.config.ts new file mode 100644 index 0000000..293a48f --- /dev/null +++ b/docs/vitest.config.ts @@ -0,0 +1,3 @@ +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ test: { include: ['docs/_components/**/*.test.tsx'] } }); From 01cf677bb46599cf40cf74da38cdde776d215a61 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:05:35 +0200 Subject: [PATCH 05/89] feat(tracing): Add unified process capture with atomic facet and metric storage Add a process capture pipeline under pkg/tracing/processcapture that records process identities once at startup, numeric metrics per tick, and resource facet deltas (files, receiving sockets, inbound/outbound connections) in atomic batches. Facet state advances only after storage commits, so failed writes are retried without losing or duplicating deltas. Group totals are derived on read rather than stored as snapshots, and secrets in commands and environment are masked before persistence. --- pkg/tracing/processcapture/benchmark_test.go | 129 +++++++++++ pkg/tracing/processcapture/facets.go | 213 +++++++++++++++++ pkg/tracing/processcapture/facets_test.go | 72 ++++++ pkg/tracing/processcapture/follow.go | 134 +++++++++++ pkg/tracing/processcapture/frames.go | 56 +++++ pkg/tracing/processcapture/kind.go | 180 +++++++++++++++ pkg/tracing/processcapture/kind_test.go | 45 ++++ pkg/tracing/processcapture/observe.go | 173 ++++++++++++++ pkg/tracing/processcapture/pretty.go | 58 +++++ pkg/tracing/processcapture/projection.go | 56 +++++ pkg/tracing/processcapture/projection_test.go | 26 +++ pkg/tracing/processcapture/store.go | 217 ++++++++++++++++++ pkg/tracing/processcapture/store_test.go | 72 ++++++ 13 files changed, 1431 insertions(+) create mode 100644 pkg/tracing/processcapture/benchmark_test.go create mode 100644 pkg/tracing/processcapture/facets.go create mode 100644 pkg/tracing/processcapture/facets_test.go create mode 100644 pkg/tracing/processcapture/follow.go create mode 100644 pkg/tracing/processcapture/frames.go create mode 100644 pkg/tracing/processcapture/kind.go create mode 100644 pkg/tracing/processcapture/kind_test.go create mode 100644 pkg/tracing/processcapture/observe.go create mode 100644 pkg/tracing/processcapture/pretty.go create mode 100644 pkg/tracing/processcapture/projection.go create mode 100644 pkg/tracing/processcapture/projection_test.go create mode 100644 pkg/tracing/processcapture/store.go create mode 100644 pkg/tracing/processcapture/store_test.go diff --git a/pkg/tracing/processcapture/benchmark_test.go b/pkg/tracing/processcapture/benchmark_test.go new file mode 100644 index 0000000..12cadf6 --- /dev/null +++ b/pkg/tracing/processcapture/benchmark_test.go @@ -0,0 +1,129 @@ +package processcapture + +import ( + "context" + "fmt" + "os" + "path/filepath" + "strconv" + "testing" + "time" + + clickyprocess "github.com/flanksource/clicky/process" + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/commons-db/recordstore/metrics" + "github.com/flanksource/commons-db/recordstore/sqlite" + "github.com/flanksource/telltale/pkg/tracing/process" +) + +func BenchmarkProcessCollection(b *testing.B) { + b.Run("process_listing", func(b *testing.B) { + for b.Loop() { + if _, err := clickyprocess.Discover(context.Background(), clickyprocess.SnapshotOptions{}); err != nil { + b.Fatal(err) + } + } + }) + b.Run("descriptors", func(b *testing.B) { + for b.Loop() { + if _, err := clickyprocess.Descriptors(context.Background(), os.Getpid()); err != nil { + b.Fatal(err) + } + } + }) +} + +func BenchmarkProcessObservationStorage(b *testing.B) { + for _, format := range []string{"snapshot", "unified"} { + b.Run(format, func(b *testing.B) { + ctx := context.Background() + path := filepath.Join(b.TempDir(), "records.sqlite") + schemas, err := Schemas() + if err != nil { + b.Fatal(err) + } + for kind, plugin := range map[string]interface { + Schema(string) (recordstore.KindSchema, error) + }{process.TreeKind: process.NewTreeKind(process.NewSampler(), process.TreeKindOptions{}), process.SamplesKind: process.NewSamplesKind(process.NewSampler())} { + schema, err := plugin.Schema(kind) + if err != nil { + b.Fatal(err) + } + schemas = append(schemas, schema) + } + backend, err := sqlite.Open(sqlite.Options{Path: path, SweepInterval: time.Hour, Schema: func(kind string) (recordstore.KindSchema, error) { + for _, schema := range schemas { + if schema.Kind == kind { + return schema, nil + } + } + return recordstore.KindSchema{}, fmt.Errorf("unknown benchmark kind %s", kind) + }}) + if err != nil { + b.Fatal(err) + } + defer func() { + if err := backend.Close(); err != nil { + b.Error(err) + } + }() + store, err := NewStore(StoreOptions{Backend: backend, Stream: "capture"}) + if err != nil { + b.Fatal(err) + } + const processes, files = 20, 100 + at := time.Unix(100, 0) + descriptors := make([]clickyprocess.Descriptor, files) + for i := range descriptors { + descriptors[i] = clickyprocess.Descriptor{FD: strconv.Itoa(i), Type: "REG", Name: "/work/checkout/source/" + strconv.Itoa(i) + ".go"} + } + b.ReportAllocs() + b.ResetTimer() + for tick := 1; tick <= b.N; tick++ { + descriptors[0].Name = "/work/output/" + strconv.Itoa(tick) + ".log" + o := Observation{At: at.Add(time.Duration(tick) * time.Second), Tick: int64(tick)} + nodes, samples := []recordstore.Row{}, []recordstore.Row{} + for pid := 1; pid <= processes; pid++ { + key := strconv.Itoa(pid) + identity := Identity{Key: key, PID: pid, Name: "worker", Command: "worker --mode compile --config /work/checkout/config.yaml", FirstObservedAt: at, StartedAt: at, Environment: map[string]string{"MODE": "compile", "PATH": "/usr/bin:/usr/local/bin"}} + if format == "unified" { + o.Processes = append(o.Processes, identity) + o.Metrics = append(o.Metrics, metrics.Sample{Entity: key, Values: map[string]any{"rssBytes": 1024 * tick, "cpuPercent": tick % 100}}) + o.Facets = append(o.Facets, FacetObservation{Process: key, Complete: true, Descriptors: descriptors}) + } else { + node, err := recordstore.EncodeRow(process.Node{Key: key, PID: pid, Name: identity.Name, Command: identity.Command, Environment: identity.Environment, StartedAt: at, LastSeenAt: o.At, RSSBytes: uint64(1024 * tick)}) + if err != nil { + b.Fatal(err) + } + sample, err := recordstore.EncodeRow(process.Sample{Key: key, PID: pid, SampledAt: o.At, Tick: o.Tick, RSSBytes: uint64(1024 * tick), OpenFileList: descriptors}) + if err != nil { + b.Fatal(err) + } + nodes, samples = append(nodes, node), append(samples, sample) + } + } + if format == "unified" { + if err := store.Apply(ctx, o); err != nil { + b.Fatal(err) + } + } else { + if _, err := backend.Append(ctx, "tree", process.TreeKind, nodes); err != nil { + b.Fatal(err) + } + if _, err := backend.Append(ctx, "samples", process.SamplesKind, samples); err != nil { + b.Fatal(err) + } + } + } + b.StopTimer() + if err := backend.Close(); err != nil { + b.Fatal(err) + } + info, err := os.Stat(backend.Path()) + if err != nil { + b.Fatal(err) + } + b.ReportMetric(float64(info.Size())/float64(b.N), "bytes/tick") + }) + } +} diff --git a/pkg/tracing/processcapture/facets.go b/pkg/tracing/processcapture/facets.go new file mode 100644 index 0000000..18f2a87 --- /dev/null +++ b/pkg/tracing/processcapture/facets.go @@ -0,0 +1,213 @@ +package processcapture + +import ( + "cmp" + "crypto/sha256" + "encoding/hex" + "encoding/json" + clickyprocess "github.com/flanksource/clicky/process" + "maps" + "net" + "slices" + "strings" + "time" +) + +const ( + Files = "files" + Sockets = "sockets" + ConnectionIn = "connection_in" + ConnectionOut = "connection_out" + ConnectionUnknown = "connection_unknown" +) + +type FacetEvent struct { + Process string `json:"process"` + At time.Time `json:"observedAt"` + Tick int64 `json:"tick"` + Facet string `json:"facet"` + Entity string `json:"entity"` + Operation string `json:"operation"` + DirectionSource string `json:"directionSource,omitempty"` + Reason string `json:"reason,omitempty"` + Resource clickyprocess.Descriptor `json:"resource"` +} + +type FacetObservation struct { + Process string + At time.Time + Tick int64 + Complete bool + Exited bool + Descriptors []clickyprocess.Descriptor + Enabled []string +} + +type facetResource struct { + facet, entity, direction string + descriptor clickyprocess.Descriptor +} + +// FacetState is an immutable observation checkpoint. Diff returns its successor; +// the collector adopts it only after the observation's storage transaction commits. +type FacetState struct { + resources map[string]map[string]facetResource + listeners map[string][]clickyprocess.Descriptor +} + +func NewFacetState() *FacetState { + return &FacetState{resources: map[string]map[string]facetResource{}, listeners: map[string][]clickyprocess.Descriptor{}} +} + +func (s *FacetState) Diff(o FacetObservation) ([]FacetEvent, *FacetState) { + if !o.Complete && !o.Exited { + return nil, s + } + next := s.clone() + return next.diff(o), next +} + +func (s *FacetState) clone() *FacetState { + return &FacetState{resources: maps.Clone(s.resources), listeners: maps.Clone(s.listeners)} +} + +func (s *FacetState) diff(o FacetObservation) []FacetEvent { + if !o.Complete && !o.Exited { + return nil + } + previous := s.resources[o.Process] + peers := map[string]facetResource{} + for _, old := range previous { + if strings.HasPrefix(old.facet, "connection_") { + peers[old.descriptor.Protocol+"/"+old.descriptor.RemoteAddr] = old + } + } + current := map[string]facetResource{} + if !o.Exited { + listeners := slices.Clone(s.listeners[o.Process]) + for _, d := range o.Descriptors { + if d.IsListening() && !slices.Contains(listeners, d) { + listeners = append(listeners, d) + } + } + s.listeners[o.Process] = listeners + for _, d := range o.Descriptors { + resource, ok := s.classify(o.Process, d, listeners) + if !ok { + continue + } + selection := resource.facet + if strings.HasPrefix(selection, "connection_") { + selection = "connections" + } + if o.Enabled != nil && !slices.Contains(o.Enabled, selection) { + continue + } + // Retain the first inferred direction for an active peer. A later + // polling observation cannot establish who initiated that connection. + if strings.HasPrefix(resource.facet, "connection_") { + if old, ok := peers[d.Protocol+"/"+d.RemoteAddr]; ok { + resource = old + } + } + current[resource.facet+"/"+resource.entity] = resource + } + } + events := []FacetEvent{} + for key, old := range previous { + if _, ok := current[key]; !ok { + events = append(events, facetEvent(o, old, "removed")) + } + } + for key, value := range current { + if _, ok := previous[key]; !ok { + events = append(events, facetEvent(o, value, "added")) + } + } + slices.SortFunc(events, func(a, b FacetEvent) int { + if n := cmp.Compare(a.Operation, b.Operation); n != 0 { + return -n + } + if n := cmp.Compare(a.Facet, b.Facet); n != 0 { + return n + } + return cmp.Compare(a.Entity, b.Entity) + }) + if o.Exited { + delete(s.resources, o.Process) + delete(s.listeners, o.Process) + } else { + s.resources[o.Process] = current + } + return events +} + +func (s *FacetState) classify(process string, d clickyprocess.Descriptor, listeners []clickyprocess.Descriptor) (facetResource, bool) { + facet, direction := Files, "" + if d.IsSocket() { + switch { + case d.IsListening(): + facet = Sockets + case d.Protocol == "TCP" && d.State == "ESTABLISHED" && d.RemoteAddr != "": + facet, direction = ConnectionUnknown, "unknown" + for _, listener := range listeners { + if receiving(listener, d) { + facet, direction = ConnectionIn, "inferred_listener" + break + } + } + if facet == ConnectionUnknown { + if _, observed := s.resources[process]; observed { + facet, direction = ConnectionOut, "inferred_no_listener" + } + } + d = clickyprocess.Descriptor{Protocol: d.Protocol, RemoteAddr: d.RemoteAddr} + default: + return facetResource{}, false + } + } + encoded, err := json.Marshal(d) + if err != nil { + panic(err) + } + sum := sha256.Sum256(encoded) + return facetResource{facet: facet, entity: hex.EncodeToString(sum[:]), direction: direction, descriptor: d}, true +} + +func receiving(listener, connection clickyprocess.Descriptor) bool { + if listener.Protocol != connection.Protocol { + return false + } + host, port, err := net.SplitHostPort(listener.LocalAddr) + if err != nil { + return listener.LocalAddr == connection.LocalAddr + } + localHost, localPort, err := net.SplitHostPort(connection.LocalAddr) + return err == nil && port == localPort && (host == localHost || host == "*" || host == "0.0.0.0" || host == "::") +} + +func facetEvent(o FacetObservation, r facetResource, operation string) FacetEvent { + event := FacetEvent{Process: o.Process, At: o.At, Tick: o.Tick, Facet: r.facet, Entity: r.entity, Operation: operation, DirectionSource: r.direction, Resource: r.descriptor} + if o.Exited { + event.Reason = "observed_exit" + } + return event +} + +func (s *FacetState) counts(o FacetObservation) map[string]any { + counts := map[string]int{} + for _, resource := range s.resources[o.Process] { + counts[resource.facet]++ + } + values := map[string]any{} + for facet, metric := range map[string]string{Files: "openFiles", Sockets: "receivingSockets", ConnectionIn: "connectionsIn", ConnectionOut: "connectionsOut", ConnectionUnknown: "connectionsUnknown"} { + selected := facet + if strings.HasPrefix(facet, "connection_") { + selected = "connections" + } + if o.Enabled == nil || slices.Contains(o.Enabled, selected) { + values[metric] = counts[facet] + } + } + return values +} diff --git a/pkg/tracing/processcapture/facets_test.go b/pkg/tracing/processcapture/facets_test.go new file mode 100644 index 0000000..ce4baf9 --- /dev/null +++ b/pkg/tracing/processcapture/facets_test.go @@ -0,0 +1,72 @@ +package processcapture + +import ( + clickyprocess "github.com/flanksource/clicky/process" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "testing" + "time" +) + +func TestProcessCapture(t *testing.T) { + RegisterFailHandler(Fail) + RunSpecs(t, "Unified process capture") +} + +var _ = Describe("facet deltas", func() { + It("keeps files and receiving sockets independent and infers inbound peers from a listener", func() { + listener := clickyprocess.Descriptor{FD: "3", Type: "IPv4", Protocol: "TCP", State: "LISTEN", LocalAddr: "*:8080"} + peer := clickyprocess.Descriptor{FD: "4", Type: "IPv4", Protocol: "TCP", State: "ESTABLISHED", LocalAddr: "127.0.0.1:8080", RemoteAddr: "127.0.0.1:51000"} + o := FacetObservation{Process: "worker", At: time.Unix(1, 0), Tick: 1, Complete: true, Enabled: []string{Sockets, "connections"}, Descriptors: []clickyprocess.Descriptor{listener, peer, {FD: "5", Type: "REG", Name: "config"}}} + events, state := NewFacetState().Diff(o) + Expect(events).To(ConsistOf(HaveField("Facet", Sockets), And(HaveField("Facet", ConnectionIn), HaveField("DirectionSource", "inferred_listener")))) + o.Exited, o.Complete = true, false + events, _ = state.Diff(o) + Expect(events).To(HaveEach(And(HaveField("Operation", "removed"), HaveField("Reason", "observed_exit")))) + }) + It("infers outbound only after an initial complete observation and keeps reused process identities separate", func() { + state := NewFacetState() + o := FacetObservation{Process: "123@1", At: time.Unix(1, 0), Tick: 1, Complete: true} + _, state = state.Diff(o) + o.Descriptors = []clickyprocess.Descriptor{{Type: "IPv4", Protocol: "TCP", State: "ESTABLISHED", RemoteAddr: "127.0.0.1:5432", LocalAddr: "127.0.0.1:51000"}} + events, state := state.Diff(o) + Expect(events).To(ConsistOf(HaveField("Facet", ConnectionOut))) + o.Process = "123@2" + events, _ = state.Diff(o) + Expect(events).To(ConsistOf(HaveField("Facet", ConnectionUnknown))) + }) + It("aggregates parallel connections by peer and removes only the last one", func() { + state := NewFacetState() + first := clickyprocess.Descriptor{FD: "7u", Type: "IPv4", Protocol: "TCP", State: "ESTABLISHED", LocalAddr: "127.0.0.1:51000", RemoteAddr: "127.0.0.1:5432"} + second := first + second.FD = "8u" + second.LocalAddr = "127.0.0.1:51001" + observation := FacetObservation{Process: "p", At: time.Unix(1, 0), Tick: 1, Complete: true, Descriptors: []clickyprocess.Descriptor{first, second}} + events, next := state.Diff(observation) + Expect(events).To(HaveLen(1)) + Expect(events[0].Facet).To(Equal(ConnectionUnknown)) + Expect(events[0].Operation).To(Equal("added")) + observation.Tick++ + observation.Descriptors = []clickyprocess.Descriptor{second} + events, next = next.Diff(observation) + Expect(events).To(BeEmpty()) + observation.Tick++ + observation.Descriptors = nil + events, _ = next.Diff(observation) + Expect(events).To(HaveLen(1)) + Expect(events[0].Operation).To(Equal("removed")) + }) + It("preserves state for incomplete reads and ignores descriptor order", func() { + state := NewFacetState() + o := FacetObservation{Process: "p", At: time.Unix(1, 0), Tick: 1, Complete: true, Descriptors: []clickyprocess.Descriptor{{FD: "1", Type: "REG", Name: "a"}, {FD: "2", Type: "REG", Name: "b"}}} + _, state = state.Diff(o) + o.Complete = false + o.Descriptors = nil + events, next := state.Diff(o) + Expect(events).To(BeEmpty()) + o.Complete = true + o.Descriptors = []clickyprocess.Descriptor{{FD: "2", Type: "REG", Name: "b"}, {FD: "1", Type: "REG", Name: "a"}} + events, _ = next.Diff(o) + Expect(events).To(BeEmpty()) + }) +}) diff --git a/pkg/tracing/processcapture/follow.go b/pkg/tracing/processcapture/follow.go new file mode 100644 index 0000000..28d2b1c --- /dev/null +++ b/pkg/tracing/processcapture/follow.go @@ -0,0 +1,134 @@ +package processcapture + +import ( + "context" + "fmt" + "slices" + "strings" + "sync" + + clickyprocess "github.com/flanksource/clicky/process" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/groups" + "github.com/flanksource/telltale/pkg/tracing/process" +) + +type Follower struct { + mu sync.Mutex + runtime *tracing.Runtime + ref tracing.TraceRef + after int64 + latest groups.Snapshot +} + +func NewFollower(runtime *tracing.Runtime, ref tracing.TraceRef) (*Follower, error) { + if runtime == nil || ref.Kind != Kind { + return nil, fmt.Errorf("process follower requires a process capture and runtime") + } + if err := ref.Validate(); err != nil { + return nil, err + } + return &Follower{runtime: runtime, ref: ref}, nil +} + +// Frame derives the latest committed observation from identities and metrics. +func (f *Follower) Frame(ctx context.Context) (groups.Frame, bool, error) { + f.mu.Lock() + defer f.mu.Unlock() + ref := tracing.TraceRef{Kind: MetricsTable, Stream: f.ref.Stream + "-metrics", AfterSeq: f.after} + meta, err := f.runtime.Results.Backend.Meta(ctx, ref.Stream) + if err != nil { + return groups.Frame{}, false, err + } + if meta.HighSeq == f.after { + return f.latest.Frame, f.latest.Frame.Tick > 0, nil + } + ref.ToSeq = meta.HighSeq + var identities []Identity + if err := tracing.ReadRecords(ctx, f.runtime, f.ref, func(p Identity) error { identities = append(identities, p); return nil }); err != nil { + return groups.Frame{}, false, err + } + var rows []MetricRow + var latest int64 + if err := tracing.ReadRecords(ctx, f.runtime, ref, func(row MetricRow) error { + if row.Tick > latest { + rows, latest = rows[:0], row.Tick + } + if row.Tick == latest { + rows = append(rows, row) + } + return nil + }); err != nil { + return groups.Frame{}, false, err + } + snapshot, err := GroupSnapshot(identities, rows) + if err != nil { + return groups.Frame{}, false, err + } + f.after, f.latest = meta.HighSeq, snapshot + return snapshot.Frame, snapshot.Frame.Tick > 0, nil +} + +func (f *Follower) Processes(filter groups.ProcessFilter) []groups.ProcessSample { + f.mu.Lock() + defer f.mu.Unlock() + return groups.FilterProcesses(f.latest.Processes, filter) +} + +// GroupSnapshot aggregates process measurements using startup grouping tags. +func GroupSnapshot(identities []Identity, rows []MetricRow) (groups.Snapshot, error) { + byKey := map[string]Identity{} + for _, p := range identities { + byKey[p.Key] = p + } + definitions := map[string]GroupInfo{} + classified := []groups.Group{} + indices := map[string]int{} + readings := map[string]groups.Reading{} + result := groups.Snapshot{} + for _, row := range rows { + p, ok := byKey[row.Entity] + if !ok { + return result, fmt.Errorf("metrics reference unknown process %q", row.Entity) + } + if len(p.Groups) == 0 { + return result, fmt.Errorf("process %s has no startup grouping tags", p.Key) + } + for _, info := range slices.Backward(p.Groups) { + if _, exists := definitions[info.Key]; exists { + continue + } + definitions[info.Key] = info + indices[info.Key] = len(classified) + classified = append(classified, groups.Group{Key: info.Key, ParentKey: info.ParentKey}) + } + observed := process.Observed{Process: clickyprocess.Process{PID: p.PID, PPID: p.PPID, Command: p.Command}} + if strings.Contains(p.Key, "@") { + observed.StartedAt = &p.StartedAt + } + if process.Key(observed.Process) != p.Key { + return result, fmt.Errorf("process identity %q does not match its pid and start", p.Key) + } + index := indices[p.Groups[0].Key] + classified[index].Members = append(classified[index].Members, observed) + var connections *int + if row.ConnectionsIn != nil && row.ConnectionsOut != nil && row.ConnectionsUnknown != nil { + n := *row.ConnectionsIn + *row.ConnectionsOut + *row.ConnectionsUnknown + connections = &n + } + reading := groups.Reading{CPUPercent: row.CPUPercent, RSSBytes: row.RSSBytes, SwapBytes: row.SwapBytes, CompressedBytes: row.CompressedBytes, Sockets: row.ReceivingSockets, Connections: connections, + PerSecond: groups.PerSecond{DiskRead: row.DiskReadBps, DiskWrite: row.DiskWriteBps, NetRx: row.NetRxBps, NetTx: row.NetTxBps}} + readings[p.Key] = reading + result.Processes = append(result.Processes, groups.ProcessSample{Key: p.Key, PID: p.PID, PPID: p.PPID, Name: p.Name, Command: p.Command, GroupKey: p.Groups[0].Key, + Origin: groups.Origin{Owner: p.Tags["owner"], Scope: p.Tags["scope"], Source: p.Tags["source"], Service: p.Tags["service"]}, + Usage: groups.Usage{Processes: 1, CPUPercent: reading.CPUPercent, RSSBytes: reading.RSSBytes, SwapBytes: reading.SwapBytes, CompressedBytes: reading.CompressedBytes, PerSecond: reading.PerSecond, Sockets: reading.Sockets, Connections: reading.Connections}}) + result.Frame.SampledAt, result.Frame.Tick = row.At, row.Tick + } + totals := groups.Aggregate(classified, readings) + for _, group := range classified { + info := definitions[group.Key] + result.Frame.Groups = append(result.Frame.Groups, groups.GroupSample{SampledAt: result.Frame.SampledAt, Tick: result.Frame.Tick, Key: info.Key, ParentKey: info.ParentKey, Name: info.Name, Kind: info.Kind, Target: info.Target, PID: info.PID, Command: info.Command, Context: info.Context, Origin: info.Origin, SkipAncestry: info.SkipAncestry, + Self: totals[info.Key].Self, Total: totals[info.Key].Total}) + } + return result, nil +} diff --git a/pkg/tracing/processcapture/frames.go b/pkg/tracing/processcapture/frames.go new file mode 100644 index 0000000..48f3c22 --- /dev/null +++ b/pkg/tracing/processcapture/frames.go @@ -0,0 +1,56 @@ +package processcapture + +import ( + "context" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/groups" +) + +type Frames struct { + HighSeq int64 `json:"highSeq"` + Frames []groups.Frame `json:"frames"` +} + +// ReadFrames derives complete ticks from an atomic process metrics stream. +func ReadFrames(ctx context.Context, runtime *tracing.Runtime, ref tracing.TraceRef) (Frames, error) { + result := Frames{Frames: []groups.Frame{}} + metricRef := tracing.TraceRef{Kind: MetricsTable, Stream: ref.Stream + "-metrics", AfterSeq: ref.AfterSeq} + meta, err := runtime.Results.Backend.Meta(ctx, metricRef.Stream) + if err != nil { + return result, err + } + metricRef.ToSeq, result.HighSeq = meta.HighSeq, meta.HighSeq + identities := []Identity{} + primary := tracing.TraceRef{Kind: Kind, Stream: ref.Stream} + if err := tracing.ReadRecords(ctx, runtime, primary, func(p Identity) error { identities = append(identities, p); return nil }); err != nil { + return result, err + } + var tick []MetricRow + flush := func() error { + if len(tick) == 0 { + return nil + } + snapshot, err := GroupSnapshot(identities, tick) + if err != nil { + return err + } + result.Frames = append(result.Frames, snapshot.Frame) + tick = tick[:0] + return nil + } + if err := tracing.ReadRecords(ctx, runtime, metricRef, func(row MetricRow) error { + if len(tick) > 0 && tick[0].Tick != row.Tick { + if err := flush(); err != nil { + return err + } + } + tick = append(tick, row) + return nil + }); err != nil { + return result, err + } + if err := flush(); err != nil { + return result, err + } + return result, nil +} diff --git a/pkg/tracing/processcapture/kind.go b/pkg/tracing/processcapture/kind.go new file mode 100644 index 0000000..9b1e2f7 --- /dev/null +++ b/pkg/tracing/processcapture/kind.go @@ -0,0 +1,180 @@ +package processcapture + +import ( + "context" + "fmt" + "os" + "slices" + "sync" + "time" + + dbcontext "github.com/flanksource/commons-db/context" + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/commons-db/recordstore/recordresults" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/groups" + "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/target" +) + +type Options struct { + process.Options + Environment *process.EnvironmentParams `json:"environment,omitempty"` + Facets []string `json:"facets,omitempty"` + Catalog string `json:"catalog,omitempty"` + Net bool `json:"net,omitempty"` +} + +type Params struct { + Options + Target target.Target `json:"target,omitzero"` +} + +func (p Params) Validate() error { + if err := p.Options.Validate(); err != nil { + return err + } + if p.Target.PID < 0 { + return fmt.Errorf("invalid process pid %d", p.Target.PID) + } + for i, facet := range p.Facets { + if !slices.Contains([]string{Files, Sockets, "connections"}, facet) || slices.Contains(p.Facets[:i], facet) { + return fmt.Errorf("invalid or repeated process facet %q: expected files, sockets or connections", facet) + } + } + return nil +} + +func (p Params) root() int { + if p.Target.Seam == target.Host { + return 0 + } + if p.Target.PID == 0 { + return os.Getpid() + } + return p.Target.PID +} + +type KindOptions struct{ Dumpers process.TransportLister } +type collector struct { + sampler *process.Sampler + options KindOptions +} +type captureKey struct{} +type capture struct { + mu sync.Mutex + store *Store + top *groups.Top + params Params + sampler *process.Sampler + rootGone bool + dumpers process.TransportLister +} + +func (collector) Params() Params { return Params{} } +func (collector) Schema() recordresults.ResultType[Identity] { + return recordresults.ResultType[Identity]{Title: "Processes", TimeColumn: "firstObservedAt", KeyColumn: "key", OnConflict: recordstore.OnConflictReplace, + Hierarchy: &recordresults.HierarchyColumns{ID: "key", Parent: "parentKey"}, SearchColumns: []string{"name", "command"}} +} + +func (c collector) Prepare(ctx dbcontext.Context, params Params, _ tracing.Emitter[Identity]) (dbcontext.Context, func() error, error) { + backend, err := tracing.CaptureBackend(ctx) + if err != nil { + return ctx, nil, err + } + store, err := NewStore(StoreOptions{Backend: backend, Stream: tracing.StreamOf(ctx)}) + if err != nil { + return ctx, nil, err + } + interval := time.Second + if params.Interval != "" { + interval, err = time.ParseDuration(params.Interval) + } + if err != nil { + return ctx, nil, err + } + var paths []string + if params.Catalog != "" { + paths = append(paths, params.Catalog) + } else { + path, err := groups.CatalogFile() + if err != nil { + return ctx, nil, err + } + if path != "" { + paths = append(paths, path) + } + } + catalog, err := groups.LoadCatalog(paths...) + if err != nil { + return ctx, nil, err + } + top, err := groups.NewTop(ctx, c.sampler, groups.TopOptions{Catalog: catalog, All: true, RootPID: params.root(), Interval: interval, Net: params.Net, SkipDescriptors: len(params.Facets) == 0}) + if err != nil { + return ctx, nil, err + } + run := &capture{store: store, top: top, params: params, sampler: c.sampler, dumpers: c.options.Dumpers} + if err := run.observe(ctx); err != nil { + top.Close() + return ctx, nil, err + } + if params.root() > 0 && run.rootGone { + top.Close() + return ctx, nil, fmt.Errorf("process %d is not running", params.root()) + } + return ctx.WithValue(captureKey{}, run), func() error { top.Close(); return store.Close(context.WithoutCancel(ctx)) }, nil +} + +func (collector) Handle(ctx dbcontext.Context, params Params, _ tracing.Emitter[Identity], _ tracing.Records[Identity]) error { + run := ctx.Value(captureKey{}).(*capture) + interval := time.Second + if params.Interval != "" { + var err error + interval, err = time.ParseDuration(params.Interval) + if err != nil { + return err + } + } + ticker := time.NewTicker(interval) + defer ticker.Stop() + for { + select { + case <-ctx.Done(): + return run.observe(context.WithoutCancel(ctx)) + case <-ticker.C: + if err := run.observe(ctx); err != nil { + if ctx.Err() != nil { + return run.observe(context.WithoutCancel(ctx)) + } + return err + } + run.mu.Lock() + gone := run.rootGone + run.mu.Unlock() + if gone { + return nil + } + } + } +} + +func (collector) Checkpoint(ctx dbcontext.Context, _ Params, _ tracing.Emitter[Identity]) error { + return ctx.Value(captureKey{}).(*capture).observe(ctx) +} + +// NewKind records one process table, resource deltas, and a wide metrics table. +func NewKind(sampler *process.Sampler, options KindOptions) *tracing.Handler[Params, Identity] { + return tracing.NewHandler[Params, Identity](collector{sampler: sampler, options: options}, tracing.Capabilities{Live: true}, target.Process, target.Host).WithResults( + tracing.NewResultTable("facets", recordresults.ResultType[FacetEvent]{Title: "Process facets", TimeColumn: "observedAt", Follow: true, Indexes: []recordstore.IndexDef{{Columns: []string{"process", "facet", "entity", "tick"}}}}), + tracing.NewResultTable("metrics", recordresults.ResultType[MetricRow]{Title: "Process metrics", TimeColumn: "observedAt", Dynamic: true, Follow: true, Indexes: []recordstore.IndexDef{{Columns: []string{"entity", "observedAt"}}}}), + ) +} + +func (s *Store) Close(ctx context.Context) error { + s.mu.Lock() + defer s.mu.Unlock() + _, err := s.backend.AppendBatch(ctx, recordstore.Batch{ID: s.stream + "-close", Atomic: true, Producer: recordstore.Producer{Instance: s.stream, Seq: s.tick + 1}, Entries: []recordstore.BatchEntry{ + {Op: recordstore.BatchSeal, Stream: s.stream + "-facets"}, {Op: recordstore.BatchSeal, Stream: s.stream + "-metrics"}, + }}) + return err +} diff --git a/pkg/tracing/processcapture/kind_test.go b/pkg/tracing/processcapture/kind_test.go new file mode 100644 index 0000000..47fe318 --- /dev/null +++ b/pkg/tracing/processcapture/kind_test.go @@ -0,0 +1,45 @@ +package processcapture_test + +import ( + "context" + "fmt" + _ "github.com/flanksource/commons-db/query/providers/sqlite" + "os" + "time" + + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" + "github.com/flanksource/telltale/pkg/tracing/tracingtest" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("unified process runtime", func() { + It("records startup once, numeric metrics separately, and seals all results", func() { + env := tracingtest.NewEnv(map[string]tracing.TracePlugin{processcapture.Kind: processcapture.NewKind(process.NewSampler(), processcapture.KindOptions{})}) + session := env.Start(processcapture.Kind, fmt.Sprintf(`{"target":{"pid":%d},"interval":"250ms"}`, os.Getpid())) + tracingtest.Running(session) + Eventually(func() int64 { + meta, _ := env.Results.Backend.Meta(context.Background(), session.Snapshot().Events.Stream+"-metrics") + return meta.Total + }, 10*time.Second).Should(BeNumerically(">=", 2)) + session.Stop("test") + info := tracingtest.Ended(session) + Expect(info.Error).To(BeEmpty()) + stream := info.Events.Stream + for _, name := range []string{stream, stream + "-metrics", stream + "-facets"} { + meta, err := env.Results.Backend.Meta(context.Background(), name) + Expect(err).NotTo(HaveOccurred()) + Expect(meta.Sealed).To(BeTrue()) + } + identities := env.Rows(info) + Expect(identities).To(ContainElement(HaveKeyWithValue("pid", BeNumerically("==", os.Getpid())))) + Expect(env.Results.Backend.Scan(context.Background(), stream+"-metrics", 0, func(_ int64, row recordstore.Row) error { + Expect(row).To(HaveKey("rssBytes")) + Expect(row).NotTo(HaveKey("command")) + return nil + })).To(Succeed()) + }) +}) diff --git a/pkg/tracing/processcapture/observe.go b/pkg/tracing/processcapture/observe.go new file mode 100644 index 0000000..4f0154a --- /dev/null +++ b/pkg/tracing/processcapture/observe.go @@ -0,0 +1,173 @@ +package processcapture + +import ( + "context" + "fmt" + "path/filepath" + "strconv" + "strings" + "time" + + clickyprocess "github.com/flanksource/clicky/process" + "github.com/flanksource/commons-db/recordstore/metrics" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/groups" + "github.com/flanksource/telltale/pkg/tracing/process" +) + +type MetricRow struct { + Entity string `json:"entity" filter:"exact"` + At time.Time `json:"observedAt"` + Tick int64 `json:"tick"` + CPUPercent *float64 `json:"cpuPercent" pretty:"unit=percent"` + RSSBytes uint64 `json:"rssBytes" pretty:"unit=bytes"` + MemoryPercent float64 `json:"memoryPercent" pretty:"unit=percent"` + DiskReadBytes *uint64 `json:"diskReadBytes" pretty:"unit=bytes"` + DiskWriteBytes *uint64 `json:"diskWriteBytes" pretty:"unit=bytes"` + OpenFiles *int `json:"openFiles"` + ReceivingSockets *int `json:"receivingSockets"` + ConnectionsIn *int `json:"connectionsIn"` + ConnectionsOut *int `json:"connectionsOut"` + ConnectionsUnknown *int `json:"connectionsUnknown"` + DiskReadBps *float64 `json:"diskReadBps" pretty:"unit=Bps"` + DiskWriteBps *float64 `json:"diskWriteBps" pretty:"unit=Bps"` + NetRxBps *float64 `json:"netRxBps" pretty:"unit=Bps"` + NetTxBps *float64 `json:"netTxBps" pretty:"unit=Bps"` + SwapBytes *uint64 `json:"swapBytes" pretty:"unit=bytes"` + CompressedBytes *uint64 `json:"compressedBytes" pretty:"unit=bytes"` +} + +func (r *capture) observe(ctx context.Context) error { + r.mu.Lock() + defer r.mu.Unlock() + snapshot, err := r.top.Snapshot(ctx) + if err != nil { + return err + } + o := Observation{At: snapshot.Frame.SampledAt, Tick: r.store.tick + 1} + keys := map[int]string{} + for _, p := range snapshot.Observed { + keys[p.PID] = process.Key(p.Process) + } + root := r.params.root() + r.rootGone = root != 0 && keys[root] == "" + tags := groupingTags(snapshot) + paths := groupPaths(snapshot) + usage := map[string]groups.Usage{} + for _, p := range snapshot.Processes { + usage[p.Key] = p.Usage + } + var fresh []clickyprocess.Process + var pids []int + for _, p := range snapshot.Observed { + if _, ok := r.store.identities[keys[p.PID]]; !ok { + fresh = append(fresh, p.Process) + pids = append(pids, p.PID) + } + } + startup := clickyprocess.NewSnapshot(fresh) + startup.PopulateWorkingDirectories(ctx, pids) + for _, p := range snapshot.Observed { + key := keys[p.PID] + if _, ok := r.store.identities[key]; !ok { + initial, _ := startup.Get(p.PID) + fields := strings.Fields(p.Command) + if len(fields) == 0 { + return fmt.Errorf("process %s has no command", key) + } + identity := Identity{Key: key, ParentKey: keys[p.PPID], PID: p.PID, PPID: p.PPID, Name: filepath.Base(fields[0]), Command: p.Command, CWD: initial.CWD, FirstObservedAt: o.At, StartedAt: o.At, Tags: tags[key], Groups: paths[key]} + if p.StartedAt != nil { + identity.StartedAt = *p.StartedAt + } + if r.dumpers != nil { + identity.StackTransports = r.dumpers.Transports(p.PID) + } + if r.params.Environment != nil { + environment, err := clickyprocess.Environment(ctx, p.PID, clickyprocess.EnvironmentOptions{Keys: r.params.Environment.Keys, Prefixes: r.params.Environment.Prefixes}) + if err != nil { + identity.EnvironmentError = err.Error() + } else { + identity.Environment = tracing.MaskEnvironment(environment) + } + } + o.Processes = append(o.Processes, identity) + } + values := map[string]any{"rssBytes": p.RSSBytes, "memoryPercent": p.MemoryPercent, "cpuPercent": nil, "diskReadBytes": nil, "diskWriteBytes": nil} + if p.IntervalCPUPercent != nil { + values["cpuPercent"] = *p.IntervalCPUPercent + } + if reading := snapshot.IO[p.PID]; reading.IO != nil { + values["diskReadBytes"], values["diskWriteBytes"] = reading.IO.DiskReadBytes, reading.IO.DiskWriteBytes + } + u := usage[key] + for name, value := range map[string]*float64{"diskReadBps": u.DiskRead, "diskWriteBps": u.DiskWrite, "netRxBps": u.NetRx, "netTxBps": u.NetTx} { + values[name] = nil + if value != nil { + values[name] = *value + } + } + for name, value := range map[string]*uint64{"swapBytes": u.SwapBytes, "compressedBytes": u.CompressedBytes} { + values[name] = nil + if value != nil { + values[name] = *value + } + } + o.Metrics = append(o.Metrics, metrics.Sample{Entity: key, Values: values}) + if len(r.params.Facets) > 0 { + held, complete := snapshot.Descriptors[p.PID] + o.Facets = append(o.Facets, FacetObservation{Process: key, Complete: complete, Descriptors: held, Enabled: r.params.Facets}) + } + } + // A process outside the selected subtree may have been reparented. Only a + // successful host listing can establish that its identity is no longer alive. + all, _, err := r.sampler.Observe(ctx, 0) + if err != nil { + return err + } + alive := map[string]bool{} + for _, p := range all { + alive[process.Key(p.Process)] = true + } + for key, identity := range r.store.identities { + if identity.ExitedAt == nil && !alive[key] { + identity.ExitedAt = &o.At + o.Processes = append(o.Processes, identity) + o.Facets = append(o.Facets, FacetObservation{Process: key, Exited: true}) + } + } + return r.store.Apply(ctx, o) +} + +func groupPaths(snapshot groups.Snapshot) map[string][]GroupInfo { + byKey := map[string]groups.GroupSample{} + for _, g := range snapshot.Frame.Groups { + byKey[g.Key] = g + } + paths := map[string][]GroupInfo{} + for _, p := range snapshot.Processes { + for key := p.GroupKey; key != ""; { + g, ok := byKey[key] + if !ok { + break + } + paths[p.Key] = append(paths[p.Key], GroupInfo{Key: g.Key, ParentKey: g.ParentKey, Name: g.Name, Kind: g.Kind, Target: g.Target, PID: g.PID, Command: g.Command, Context: g.Context, Origin: g.Origin, SkipAncestry: g.SkipAncestry}) + key = g.ParentKey + } + } + return paths +} + +func groupingTags(snapshot groups.Snapshot) map[string]map[string]string { + byGroup := map[string]groups.GroupSample{} + for _, group := range snapshot.Frame.Groups { + byGroup[group.Key] = group + } + result := map[string]map[string]string{} + for _, p := range snapshot.Processes { + g := byGroup[p.GroupKey] + result[p.Key] = map[string]string{"group": g.Key, "groupParent": g.ParentKey, "groupName": g.Name, "groupKind": g.Kind, "groupPID": strconv.Itoa(g.PID), "groupCommand": g.Command, "target": g.Target, + "owner": p.Origin.Owner, "scope": p.Origin.Scope, "source": p.Origin.Source, "service": p.Origin.Service, + "repo": g.Context.Repo, "branch": g.Context.Branch, "cwd": g.Context.CWD, "agent": g.Context.Agent, "session": g.Context.Session, "workspace": g.Context.Workspace, "surface": g.Context.Surface} + } + return result +} diff --git a/pkg/tracing/processcapture/pretty.go b/pkg/tracing/processcapture/pretty.go new file mode 100644 index 0000000..95ba672 --- /dev/null +++ b/pkg/tracing/processcapture/pretty.go @@ -0,0 +1,58 @@ +package processcapture + +import ( + "fmt" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +func (r Identity) Pretty() api.Text { + t := clicky.Text(fmt.Sprintf("pid %d", r.PID), "text-muted").Space().Append(r.Name, "text-blue-500 font-bold").Space().Append(r.Command, "font-mono") + if r.ExitedAt != nil { + t = t.Space().Append("exited", "text-yellow-500") + } + if r.EnvironmentError != "" { + t = t.Space().Append(r.EnvironmentError, "text-red-500") + } + return t +} + +func (r Identity) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.Map(r.Tags)).NewLine().Add(clicky.Map(map[string]any{"groups": r.Groups, "cwd": r.CWD, "parent": r.ParentKey})) +} + +func (r MetricRow) Pretty() api.Text { + t := clicky.Text(r.Entity, "text-muted") + if r.CPUPercent != nil { + t = t.Space().Append(fmt.Sprintf("CPU %.1f%%", *r.CPUPercent), "text-blue-500") + } + t = t.Space().Append("RSS ", "text-muted").Add(api.HumanizeBytes(int64(r.RSSBytes))) + if r.OpenFiles != nil { + t = t.Space().Append(fmt.Sprintf("%d files", *r.OpenFiles), "text-muted") + } + return t +} + +func (r MetricRow) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.Map(map[string]any{ + "CPU %": r.CPUPercent, "RSS": api.HumanizeBytes(int64(r.RSSBytes)), "Files": r.OpenFiles, + "Disk read bytes": r.DiskReadBytes, "Disk write bytes": r.DiskWriteBytes, + "Disk read B/s": r.DiskReadBps, "Disk write B/s": r.DiskWriteBps, + "Network receive B/s": r.NetRxBps, "Network send B/s": r.NetTxBps, + "Connections in": r.ConnectionsIn, "Connections out": r.ConnectionsOut, + })) +} + +func (r FacetEvent) Pretty() api.Text { + name := r.Entity + if r.Resource.Name != "" { + name = r.Resource.Name + } + return clicky.Text(r.Process, "text-muted").Space().Append(r.Facet, "text-blue-500"). + Space().Append(r.Operation, "text-yellow-500").Space().Append(name, "font-mono") +} + +func (r FacetEvent) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.Map(map[string]any{"resource": r.Resource, "reason": r.Reason, "directionSource": r.DirectionSource})) +} diff --git a/pkg/tracing/processcapture/projection.go b/pkg/tracing/processcapture/projection.go new file mode 100644 index 0000000..4c98b0a --- /dev/null +++ b/pkg/tracing/processcapture/projection.go @@ -0,0 +1,56 @@ +package processcapture + +import "github.com/flanksource/telltale/pkg/tracing/process" + +// Nodes projects startup identities and numeric history into a current tree. +func Nodes(identities []Identity, metrics []MetricRow) []process.Node { + index := map[string]int{} + nodes := make([]process.Node, 0, len(identities)) + for _, p := range identities { + status := "running" + if p.ExitedAt != nil { + status = "exited" + } + index[p.Key] = len(nodes) + nodes = append(nodes, process.Node{Key: p.Key, ParentKey: p.ParentKey, PID: p.PID, PPID: p.PPID, Name: p.Name, Command: p.Command, CWD: p.CWD, Status: status, + StartedAt: p.StartedAt, ExitedAt: p.ExitedAt, LastSeenAt: p.FirstObservedAt, IsRoot: p.ParentKey == "", Environment: p.Environment, EnvironmentError: p.EnvironmentError, StackTransports: p.StackTransports}) + } + for _, sample := range metrics { + i, ok := index[sample.Entity] + if !ok { + continue + } + n := &nodes[i] + if !sample.At.Before(n.LastSeenAt) { + n.CPUPercent, n.RSSBytes, n.LastSeenAt = sample.CPUPercent, sample.RSSBytes, sample.At + } + n.PeakRSSBytes = max(n.PeakRSSBytes, sample.RSSBytes) + if sample.CPUPercent != nil && (n.PeakCPUPercent == nil || *sample.CPUPercent > *n.PeakCPUPercent) { + n.PeakCPUPercent = sample.CPUPercent + } + } + return nodes +} + +// Samples joins each metric row to its process identity for SDK consumers. +func Samples(identities []Identity, metrics []MetricRow) []process.Sample { + byKey := map[string]Identity{} + for _, p := range identities { + byKey[p.Key] = p + } + samples := make([]process.Sample, 0, len(metrics)) + for _, row := range metrics { + p, ok := byKey[row.Entity] + if !ok { + continue + } + var connections *int + if row.ConnectionsIn != nil && row.ConnectionsOut != nil && row.ConnectionsUnknown != nil { + total := *row.ConnectionsIn + *row.ConnectionsOut + *row.ConnectionsUnknown + connections = &total + } + samples = append(samples, process.Sample{SampledAt: row.At, Tick: row.Tick, Key: row.Entity, PID: p.PID, CPUPercent: row.CPUPercent, MemoryPercent: row.MemoryPercent, RSSBytes: row.RSSBytes, + DiskReadBytes: row.DiskReadBytes, DiskWriteBytes: row.DiskWriteBytes, OpenFiles: row.OpenFiles, Ports: row.ReceivingSockets, Sockets: row.ReceivingSockets, Connections: connections}) + } + return samples +} diff --git a/pkg/tracing/processcapture/projection_test.go b/pkg/tracing/processcapture/projection_test.go new file mode 100644 index 0000000..7fc530a --- /dev/null +++ b/pkg/tracing/processcapture/projection_test.go @@ -0,0 +1,26 @@ +package processcapture + +import ( + "github.com/flanksource/telltale/pkg/tracing/groups" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "time" +) + +var _ = Describe("derived process groups", func() { + It("rebuilds self and descendant totals without storing group snapshots", func() { + at := time.Unix(100, 0) + root := GroupInfo{Key: "tools", Name: "tools", Kind: groups.KindTool} + child := GroupInfo{Key: "tests", ParentKey: root.Key, Name: "tests", Kind: groups.KindTest} + identities := []Identity{{Key: "1", PID: 1, Name: "runner", Groups: []GroupInfo{root}}, {Key: "2", PID: 2, Name: "worker", Groups: []GroupInfo{child, root}}} + cpu := 12.5 + rows := []MetricRow{{Entity: "1", At: at, Tick: 1, RSSBytes: 1024}, {Entity: "2", At: at, Tick: 1, RSSBytes: 2048, CPUPercent: &cpu}} + snapshot, err := GroupSnapshot(identities, rows) + Expect(err).NotTo(HaveOccurred()) + Expect(snapshot.Frame.Groups).To(HaveExactElements( + And(HaveField("Key", root.Key), HaveField("Self", And(HaveField("Processes", 1), HaveField("RSSBytes", uint64(1024)))), HaveField("Total", And(HaveField("Processes", 2), HaveField("RSSBytes", uint64(3072)), HaveField("CPUPercent", Equal(&cpu))))), + And(HaveField("Key", child.Key), HaveField("Total", And(HaveField("Processes", 1), HaveField("RSSBytes", uint64(2048))))), + )) + Expect(snapshot.Processes).To(HaveLen(2)) + }) +}) diff --git a/pkg/tracing/processcapture/store.go b/pkg/tracing/processcapture/store.go new file mode 100644 index 0000000..ca3ea6f --- /dev/null +++ b/pkg/tracing/processcapture/store.go @@ -0,0 +1,217 @@ +package processcapture + +import ( + "context" + "fmt" + "maps" + "reflect" + "slices" + "sync" + "time" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/commons-db/recordstore/metrics" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/groups" + "github.com/flanksource/telltale/pkg/tracing/process" + sdk "github.com/flanksource/telltale/sdk" +) + +const Kind = "process" +const FacetsTable = "process_facets" +const MetricsTable = "process_metrics" + +type Identity struct { + Key string `json:"key"` + ParentKey string `json:"parentKey,omitempty"` + PID int `json:"pid"` + PPID int `json:"ppid"` + Name string `json:"name"` + Command string `json:"command"` + CWD string `json:"cwd,omitempty"` + StartedAt time.Time `json:"startedAt"` + FirstObservedAt time.Time `json:"firstObservedAt"` + ExitedAt *time.Time `json:"exitedAt,omitempty"` + Environment map[string]string `json:"environment,omitempty"` + Tags map[string]string `json:"tags,omitempty"` + EnvironmentError string `json:"environmentError,omitempty"` + Groups []GroupInfo `json:"groups,omitempty"` + StackTransports []process.StackTransport `json:"stackTransports,omitempty"` +} + +type GroupInfo struct { + Key string `json:"key"` + ParentKey string `json:"parentKey,omitempty"` + Name string `json:"name"` + Kind string `json:"kind"` + Target string `json:"target,omitempty"` + PID int `json:"pid"` + Command string `json:"command,omitempty"` + Context groups.Context `json:"context"` + Origin groups.Origin `json:"origin"` + SkipAncestry bool `json:"skipAncestry,omitempty"` +} + +type Observation struct { + At time.Time + Tick int64 + Processes []Identity + Facets []FacetObservation + Metrics []metrics.Sample +} + +type StoreOptions struct { + Backend recordstore.BatchAppender + Stream string +} + +type Store struct { + mu sync.Mutex + backend recordstore.BatchAppender + stream string + metrics *metrics.DynamicMetricTable + facets *FacetState + tick int64 + identities map[string]Identity +} + +func NewStore(options StoreOptions) (*Store, error) { + if options.Backend == nil { + return nil, fmt.Errorf("process capture requires an atomic batch backend") + } + if err := recordstore.ValidateStream(options.Stream); err != nil { + return nil, err + } + table, err := metricTable() + if err != nil { + return nil, err + } + return &Store{backend: options.Backend, stream: options.Stream, metrics: table, facets: NewFacetState(), identities: map[string]Identity{}}, nil +} + +func metricTable() (*metrics.DynamicMetricTable, error) { + return metrics.NewDynamicMetricTable(metrics.TableOptions{Kind: MetricsTable, Metrics: []metrics.Definition{ + {Name: "cpuPercent", Unit: "percent"}, {Name: "rssBytes", Unit: "bytes"}, {Name: "memoryPercent", Unit: "percent"}, + {Name: "diskReadBytes", Unit: "bytes", Counter: true}, {Name: "diskWriteBytes", Unit: "bytes", Counter: true}, + {Name: "openFiles"}, {Name: "receivingSockets"}, {Name: "connectionsIn"}, {Name: "connectionsOut"}, {Name: "connectionsUnknown"}, + {Name: "diskReadBps", Unit: "Bps"}, {Name: "diskWriteBps", Unit: "Bps"}, {Name: "netRxBps", Unit: "Bps"}, {Name: "netTxBps", Unit: "Bps"}, + {Name: "swapBytes", Unit: "bytes"}, {Name: "compressedBytes", Unit: "bytes"}, + }}) +} + +func Schemas() ([]recordstore.KindSchema, error) { + identity, err := query.ColumnsFor(reflect.TypeFor[Identity]()) + if err != nil { + return nil, err + } + facets, err := query.ColumnsFor(reflect.TypeFor[FacetEvent]()) + if err != nil { + return nil, err + } + table, err := metricTable() + if err != nil { + return nil, err + } + return []recordstore.KindSchema{ + {Kind: Kind, Columns: identity, Options: recordstore.KindOptions{Key: "key", OnConflict: recordstore.OnConflictReplace, TimeColumn: "firstObservedAt"}}, + {Kind: FacetsTable, Columns: facets, Options: recordstore.KindOptions{TimeColumn: "observedAt", Indexes: []recordstore.IndexDef{{Columns: []string{"process", "facet", "entity", "tick"}}}}}, + table.Schema(), + }, nil +} + +func (s *Store) Apply(ctx context.Context, o Observation) error { + s.mu.Lock() + defer s.mu.Unlock() + if o.At.IsZero() || o.Tick != s.tick+1 { + return fmt.Errorf("process observation must advance tick %d to %d with a timestamp", s.tick, s.tick+1) + } + schemas, err := Schemas() + if err != nil { + return err + } + batch := recordstore.Batch{ID: fmt.Sprintf("%s-%d", s.stream, o.Tick), Atomic: true, Producer: recordstore.Producer{Instance: s.stream, Seq: o.Tick}, Schemas: schemas[:2]} + identities, rows, err := s.processRows(o.Processes) + if err != nil { + return err + } + batch.Entries = append(batch.Entries, recordstore.BatchEntry{Op: recordstore.BatchAppend, Kind: Kind, Stream: s.stream, Rows: rows}) + next := s.facets.clone() + counts := map[string]map[string]any{} + events := []recordstore.Row{} + for _, facet := range o.Facets { + if _, ok := identities[facet.Process]; !ok { + return fmt.Errorf("facets reference unknown process %q", facet.Process) + } + facet.At, facet.Tick = o.At, o.Tick + changes := next.diff(facet) + if facet.Complete { + counts[facet.Process] = next.counts(facet) + } + for _, change := range changes { + row, err := recordstore.EncodeRow(change) + if err != nil { + return err + } + events = append(events, row) + } + } + batch.Entries = append(batch.Entries, recordstore.BatchEntry{Op: recordstore.BatchAppend, Kind: FacetsTable, Stream: s.stream + "-facets", Rows: events}) + source := metrics.DynamicMetricSource{Table: s.metrics, Stream: s.stream + "-metrics"} + samples := slices.Clone(o.Metrics) + for i := range samples { + if _, ok := identities[samples[i].Entity]; !ok { + return fmt.Errorf("metrics reference unknown process %q", samples[i].Entity) + } + samples[i].At, samples[i].Tick = o.At, o.Tick + values := map[string]any{} + maps.Copy(values, samples[i].Values) + samples[i].Values = values + maps.Copy(samples[i].Values, counts[samples[i].Entity]) + } + if _, err := source.Append(ctx, metrics.AppendOptions{Backend: s.backend, Batch: batch, Samples: samples}); err != nil { + return err + } + s.identities, s.facets, s.tick = identities, next, o.Tick + return nil +} + +func (s *Store) processRows(processes []Identity) (map[string]Identity, []recordstore.Row, error) { + identities := maps.Clone(s.identities) + rows := []recordstore.Row{} + for _, process := range processes { + if process.Key == "" || process.PID <= 0 || process.FirstObservedAt.IsZero() { + return nil, nil, fmt.Errorf("process identity requires key, pid and first observation time") + } + if previous, ok := identities[process.Key]; ok { + if previous.PID != process.PID { + return nil, nil, fmt.Errorf("process identity %s changed pid", process.Key) + } + if previous.ExitedAt != nil || process.ExitedAt == nil { + continue + } + previous.ExitedAt = process.ExitedAt + process = previous + } + process.Command = sdk.Mask(process.Command) + process.Environment = tracing.MaskEnvironment(process.Environment) + process.Groups = slices.Clone(process.Groups) + process.StackTransports = slices.Clone(process.StackTransports) + if process.ExitedAt != nil { + exited := *process.ExitedAt + process.ExitedAt = &exited + } + for i := range process.Groups { + process.Groups[i].Command = sdk.Mask(process.Groups[i].Command) + } + row, err := recordstore.EncodeRow(process) + if err != nil { + return nil, nil, err + } + process.Environment = maps.Clone(process.Environment) + process.Tags = maps.Clone(process.Tags) + identities[process.Key] = process + rows = append(rows, row) + } + return identities, rows, nil +} diff --git a/pkg/tracing/processcapture/store_test.go b/pkg/tracing/processcapture/store_test.go new file mode 100644 index 0000000..01ac0cf --- /dev/null +++ b/pkg/tracing/processcapture/store_test.go @@ -0,0 +1,72 @@ +package processcapture + +import ( + "context" + "fmt" + clickyprocess "github.com/flanksource/clicky/process" + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/commons-db/recordstore/metrics" + "github.com/flanksource/commons-db/recordstore/sqlite" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "path/filepath" + "time" +) + +type refusingBackend struct { + recordstore.BatchAppender + refuse bool +} + +func (b *refusingBackend) AppendBatch(ctx context.Context, batch recordstore.Batch) (recordstore.BatchResult, error) { + if b.refuse { + return recordstore.BatchResult{}, fmt.Errorf("storage unavailable") + } + return b.BatchAppender.AppendBatch(ctx, batch) +} + +var _ = Describe("process observation storage", func() { + It("stores independent tables atomically and retries deltas without advancing state after failure", func() { + ctx := context.Background() + backend, err := sqlite.Open(sqlite.Options{Path: filepath.Join(GinkgoT().TempDir(), "records.sqlite"), Schema: func(kind string) (recordstore.KindSchema, error) { + schemas, err := Schemas() + if err != nil { + return recordstore.KindSchema{}, err + } + for _, schema := range schemas { + if schema.Kind == kind { + return schema, nil + } + } + return recordstore.KindSchema{}, fmt.Errorf("undeclared %s", kind) + }, SweepInterval: time.Hour}) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(backend.Close) + writer := &refusingBackend{BatchAppender: backend, refuse: true} + store, err := NewStore(StoreOptions{Backend: writer, Stream: "capture"}) + Expect(err).NotTo(HaveOccurred()) + at := time.Unix(1, 0) + o := Observation{At: at, Tick: 1, Processes: []Identity{{Key: "p", PID: 1, FirstObservedAt: at, StartedAt: at, Command: "worker", Environment: map[string]string{"MODE": "test"}}}, Facets: []FacetObservation{{Process: "p", Complete: true, Descriptors: []clickyprocess.Descriptor{{FD: "1", Type: "REG", Name: "data"}}}}, Metrics: []metrics.Sample{{Entity: "p", Values: map[string]any{"rssBytes": uint64(1024), "customMetric": 2}}}} + Expect(store.Apply(ctx, o)).NotTo(Succeed()) + Expect(store.tick).To(BeZero()) + Expect(store.identities).To(BeEmpty()) + writer.refuse = false + Expect(store.Apply(ctx, o)).To(Succeed()) + for _, stream := range []string{"capture", "capture-facets", "capture-metrics"} { + meta, err := backend.Meta(ctx, stream) + Expect(err).NotTo(HaveOccurred()) + Expect(meta.Total).To(Equal(int64(1))) + } + o.Tick = 2 + o.At = at.Add(time.Second) + o.Processes[0].Command = "must not rewrite startup metadata" + Expect(store.Apply(ctx, o)).To(Succeed()) + meta, err := backend.Meta(ctx, "capture-facets") + Expect(err).NotTo(HaveOccurred()) + Expect(meta.Total).To(Equal(int64(1))) + Expect(backend.Scan(ctx, "capture", 0, func(_ int64, row recordstore.Row) error { Expect(row["command"]).To(Equal("worker")); return nil })).To(Succeed()) + meta, err = backend.Meta(ctx, "capture-metrics") + Expect(err).NotTo(HaveOccurred()) + Expect(meta.Total).To(Equal(int64(2))) + }) +}) From f5eed5cd4c5c1477f28f6f3cbc5c071b895df15e Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:05:51 +0200 Subject: [PATCH 06/89] feat(tracing): add gavel status tracking, memory columns, and result summaries to tracing Add a tracing layer that shows what gavel publishes about its tasks: gavel processes are followed by pid through their status files, their task groups and running tasks are nested under them, and their slot pools are summarized. Gavel rules can be skip-listed so their tasks claim processes by pid instead of ancestry. Top also gains compressed and swap memory columns, resource hog detection with a 120s retention, and a grouping by slot pool. Result tables are registered per capture kind, and summaries now report durations, latest prometheus target health, and top-ranked profile functions. Pretty renderers are added for the record kinds. --- pkg/tracing/exec/pretty.go | 21 +++ pkg/tracing/exec/summary.go | 16 +++ pkg/tracing/exec/summary_test.go | 20 +++ pkg/tracing/goprof/export.go | 14 +- pkg/tracing/goprof/pretty.go | 26 ++++ pkg/tracing/groups/catalog.go | 4 + pkg/tracing/groups/catalog.yaml | 1 + pkg/tracing/groups/catalog_test.go | 13 +- pkg/tracing/groups/empty_read_test.go | 21 +++ pkg/tracing/groups/gavel.go | 151 +++++++++++++++++++++ pkg/tracing/groups/gavel_render.go | 152 ++++++++++++++++++++++ pkg/tracing/groups/gavel_tasks.go | 114 ++++++++++++++++ pkg/tracing/groups/gavel_tasks_test.go | 112 ++++++++++++++++ pkg/tracing/groups/gavel_test.go | 110 ++++++++++++++++ pkg/tracing/groups/grouping.go | 96 +++++++++++++- pkg/tracing/groups/grouping_test.go | 40 ++++++ pkg/tracing/groups/hogs.go | 82 ++++++++++++ pkg/tracing/groups/hogs_test.go | 87 +++++++++++++ pkg/tracing/groups/memory.go | 68 ++++++++++ pkg/tracing/groups/memory_darwin.go | 36 +++++ pkg/tracing/groups/memory_linux.go | 29 +++++ pkg/tracing/groups/memory_other.go | 10 ++ pkg/tracing/groups/memory_test.go | 31 +++++ pkg/tracing/groups/render.go | 76 +++++++++-- pkg/tracing/groups/snapshot.go | 14 +- pkg/tracing/groups/summary.go | 29 +++++ pkg/tracing/groups/top.go | 95 ++++++++++++-- pkg/tracing/groups/usage.go | 37 +++++- pkg/tracing/http/export.go | 3 + pkg/tracing/http/pretty.go | 22 ++++ pkg/tracing/jfr/pretty.go | 18 +++ pkg/tracing/jfr/summary.go | 30 +++++ pkg/tracing/kinds.go | 39 +++++- pkg/tracing/kinds_spec_test.go | 14 ++ pkg/tracing/llm/pretty.go | 33 +++++ pkg/tracing/llm/summary.go | 22 ++++ pkg/tracing/logs/pretty.go | 19 +++ pkg/tracing/logs/summary.go | 11 ++ pkg/tracing/plugin.go | 13 +- pkg/tracing/presentation.go | 106 +++++++++++++++ pkg/tracing/presentation_handler.go | 19 +++ pkg/tracing/presentation_test.go | 42 ++++++ pkg/tracing/pretty.go | 32 +++++ pkg/tracing/prometheus/pretty.go | 21 +++ pkg/tracing/prometheus/summary.go | 25 ++++ pkg/tracing/prometheus/summary_test.go | 17 +++ pkg/tracing/ranking.go | 25 ++++ pkg/tracing/results.go | 101 ++++++++++++++ pkg/tracing/spans/pretty.go | 27 ++++ pkg/tracing/spans/summary.go | 18 +++ pkg/tracing/sql/pretty.go | 29 +++++ pkg/tracing/sqlserver/history/pretty.go | 21 +++ pkg/tracing/sqlserver/plancache/pretty.go | 32 +++++ pkg/tracing/sqlserver/xesession/pretty.go | 25 ++++ pkg/tracing/stacks/pretty.go | 45 +++++++ pkg/tracing/terminal/pretty.go | 39 ++++++ 56 files changed, 2309 insertions(+), 44 deletions(-) create mode 100644 pkg/tracing/exec/pretty.go create mode 100644 pkg/tracing/exec/summary.go create mode 100644 pkg/tracing/exec/summary_test.go create mode 100644 pkg/tracing/goprof/pretty.go create mode 100644 pkg/tracing/groups/empty_read_test.go create mode 100644 pkg/tracing/groups/gavel.go create mode 100644 pkg/tracing/groups/gavel_render.go create mode 100644 pkg/tracing/groups/gavel_tasks.go create mode 100644 pkg/tracing/groups/gavel_tasks_test.go create mode 100644 pkg/tracing/groups/gavel_test.go create mode 100644 pkg/tracing/groups/hogs.go create mode 100644 pkg/tracing/groups/hogs_test.go create mode 100644 pkg/tracing/groups/memory.go create mode 100644 pkg/tracing/groups/memory_darwin.go create mode 100644 pkg/tracing/groups/memory_linux.go create mode 100644 pkg/tracing/groups/memory_other.go create mode 100644 pkg/tracing/groups/memory_test.go create mode 100644 pkg/tracing/groups/summary.go create mode 100644 pkg/tracing/http/pretty.go create mode 100644 pkg/tracing/jfr/pretty.go create mode 100644 pkg/tracing/jfr/summary.go create mode 100644 pkg/tracing/llm/pretty.go create mode 100644 pkg/tracing/llm/summary.go create mode 100644 pkg/tracing/logs/pretty.go create mode 100644 pkg/tracing/logs/summary.go create mode 100644 pkg/tracing/presentation.go create mode 100644 pkg/tracing/presentation_handler.go create mode 100644 pkg/tracing/presentation_test.go create mode 100644 pkg/tracing/pretty.go create mode 100644 pkg/tracing/prometheus/pretty.go create mode 100644 pkg/tracing/prometheus/summary.go create mode 100644 pkg/tracing/prometheus/summary_test.go create mode 100644 pkg/tracing/ranking.go create mode 100644 pkg/tracing/results.go create mode 100644 pkg/tracing/spans/pretty.go create mode 100644 pkg/tracing/spans/summary.go create mode 100644 pkg/tracing/sql/pretty.go create mode 100644 pkg/tracing/sqlserver/history/pretty.go create mode 100644 pkg/tracing/sqlserver/plancache/pretty.go create mode 100644 pkg/tracing/sqlserver/xesession/pretty.go create mode 100644 pkg/tracing/stacks/pretty.go create mode 100644 pkg/tracing/terminal/pretty.go diff --git a/pkg/tracing/exec/pretty.go b/pkg/tracing/exec/pretty.go new file mode 100644 index 0000000..4fe9259 --- /dev/null +++ b/pkg/tracing/exec/pretty.go @@ -0,0 +1,21 @@ +package exec + +import ( + "errors" + "time" + + "github.com/flanksource/clicky/api" + clickyexec "github.com/flanksource/clicky/exec" +) + +func (r ExecRecord) result() clickyexec.ExecResult { + result := clickyexec.ExecResult{Command: r.Name, Args: r.Args, PID: r.PID, ExitCode: r.ExitCode, + Duration: time.Duration(r.DurationMs * float64(time.Millisecond)), Stdout: r.StdoutTail, Stderr: r.StderrTail} + if r.Error != "" { + result.Error = errors.New(r.Error) + } + return result +} + +func (r ExecRecord) Pretty() api.Text { return r.result().Pretty() } +func (r ExecRecord) PrettyFull() api.Textable { return r.result().PrettyFull() } diff --git a/pkg/tracing/exec/summary.go b/pkg/tracing/exec/summary.go new file mode 100644 index 0000000..578d388 --- /dev/null +++ b/pkg/tracing/exec/summary.go @@ -0,0 +1,16 @@ +package exec + +import "iter" + +func (capture) Summarize(rows iter.Seq[ExecRecord]) (map[string]any, error) { + count, failed := 0, 0 + duration := 0.0 + for row := range rows { + count++ + duration += row.DurationMs + if row.ExitCode != 0 || row.Error != "" { + failed++ + } + } + return map[string]any{"executions": count, "failures": failed, "durationMs": duration}, nil +} diff --git a/pkg/tracing/exec/summary_test.go b/pkg/tracing/exec/summary_test.go new file mode 100644 index 0000000..ce66ed9 --- /dev/null +++ b/pkg/tracing/exec/summary_test.go @@ -0,0 +1,20 @@ +package exec + +import ( + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "slices" +) + +var _ = Describe("execution monitor summary", func() { + It("counts errors and duration across more than one displayed page", func() { + rows := make([]ExecRecord, 125) + for i := range rows { + rows[i].DurationMs = 2 + } + rows[124].ExitCode = 1 + summary, err := (capture{}).Summarize(slices.Values(rows)) + Expect(err).NotTo(HaveOccurred()) + Expect(summary).To(Equal(map[string]any{"executions": 125, "failures": 1, "durationMs": float64(250)})) + }) +}) diff --git a/pkg/tracing/goprof/export.go b/pkg/tracing/goprof/export.go index 9224a5c..feefb3a 100644 --- a/pkg/tracing/goprof/export.go +++ b/pkg/tracing/goprof/export.go @@ -21,11 +21,23 @@ func (profiler) Formats() []tracing.ExportFormat { return []tracing.ExportFormat func (profiler) Summarize(rows iter.Seq[Sample]) (map[string]any, error) { checkpoints := map[string]bool{} totals := map[string]int64{} + functions := map[string]map[string]int64{} for record := range rows { checkpoints[record.CheckpointID] = true totals[record.SampleType+"/"+record.Unit] += record.Value + if len(record.Frames) > 0 { + key := record.SampleType + "/" + record.Unit + if functions[key] == nil { + functions[key] = map[string]int64{} + } + functions[key][record.Frames[0].Func] += record.Value + } + } + ranked := map[string]any{} + for key, values := range functions { + ranked[key] = tracing.RankedValues(values) } - return map[string]any{"checkpoints": len(checkpoints), "totals": totals}, nil + return map[string]any{"checkpoints": len(checkpoints), "totals": totals, "functions": ranked}, nil } // Export rebuilds the window's records into one pprof profile: its sample diff --git a/pkg/tracing/goprof/pretty.go b/pkg/tracing/goprof/pretty.go new file mode 100644 index 0000000..c256491 --- /dev/null +++ b/pkg/tracing/goprof/pretty.go @@ -0,0 +1,26 @@ +package goprof + +import ( + "fmt" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing" +) + +func (r Sample) Pretty() api.Text { + t := clicky.Text(fmt.Sprintf("pid %d", r.PID), "text-muted").Space().Append(r.Profile, "text-blue-500 font-bold"). + Space().Append(r.SampleType, "text-muted").Space().Add(tracing.PrettySampleValue(r.Value, r.Unit)) + if len(r.Frames) > 0 { + t = t.Space().Append(r.Frames[0].Func, "font-mono") + } + return t +} + +func (r Sample) PrettyFull() api.Textable { + t := r.Pretty() + for _, frame := range r.Frames { + t = t.NewLine().Add(frame.Pretty()) + } + return t +} diff --git a/pkg/tracing/groups/catalog.go b/pkg/tracing/groups/catalog.go index 9cb20ea..e939c43 100644 --- a/pkg/tracing/groups/catalog.go +++ b/pkg/tracing/groups/catalog.go @@ -53,6 +53,10 @@ type Rule struct { // TargetSession, or a flag such as --session whose value it is. Target string `yaml:"target,omitempty" json:"target,omitempty"` Match []Match `yaml:"match,omitempty" json:"match,omitempty"` + // SkipAncestry marks a runner, such as gavel, whose groups do not own the + // processes they start by ancestry alone: what it publishes about its + // tasks claims them first, by pid, wherever they run. + SkipAncestry bool `yaml:"skipAncestry,omitempty" json:"skipAncestry,omitempty"` // Disabled drops the built-in rule of this name. Disabled bool `yaml:"disabled,omitempty" json:"-"` } diff --git a/pkg/tracing/groups/catalog.yaml b/pkg/tracing/groups/catalog.yaml index e46d2b5..249fe4d 100644 --- a/pkg/tracing/groups/catalog.yaml +++ b/pkg/tracing/groups/catalog.yaml @@ -26,6 +26,7 @@ groups: - name: gavel kind: test target: positional + skipAncestry: true match: - exec: [gavel] - name: go-test diff --git a/pkg/tracing/groups/catalog_test.go b/pkg/tracing/groups/catalog_test.go index 1baf6b8..0dcda4c 100644 --- a/pkg/tracing/groups/catalog_test.go +++ b/pkg/tracing/groups/catalog_test.go @@ -40,10 +40,21 @@ groups: - exec: [gavel-dev] - name: gopls disabled: true + - name: acme-runner + kind: build + skipAncestry: true + match: + - exec: [acme-runner] `)) Expect(err).NotTo(HaveOccurred()) + runner, ok := catalog.Rule("acme-runner") + Expect(ok).To(BeTrue()) + Expect(runner.SkipAncestry).To(BeTrue(), "groups.yaml can skip-list a runner") + builtinGavel, ok := builtin.Rule("gavel") + Expect(ok).To(BeTrue()) + Expect(builtinGavel.SkipAncestry).To(BeTrue(), "the built-in gavel rule is skip-listed") - expected := []string{"acme-server"} + expected := []string{"acme-server", "acme-runner"} for _, name := range ruleNames(builtin) { if name != "gopls" { expected = append(expected, name) diff --git a/pkg/tracing/groups/empty_read_test.go b/pkg/tracing/groups/empty_read_test.go new file mode 100644 index 0000000..ee2de03 --- /dev/null +++ b/pkg/tracing/groups/empty_read_test.go @@ -0,0 +1,21 @@ +package groups + +import ( + "context" + "time" + + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = ginkgo.Describe("an empty process observation", func() { + ginkgo.It("does not poll memory or resources after the last process exits", func() { + ctx, cancel := context.WithCancel(context.Background()) + cancel() + top := &Top{rates: NewRates()} + readings, held, err := top.read(ctx, nil, time.Now()) + Expect(err).NotTo(HaveOccurred()) + Expect(readings).To(BeEmpty()) + Expect(held).To(BeEmpty()) + }) +}) diff --git a/pkg/tracing/groups/gavel.go b/pkg/tracing/groups/gavel.go new file mode 100644 index 0000000..9e311ad --- /dev/null +++ b/pkg/tracing/groups/gavel.go @@ -0,0 +1,151 @@ +package groups + +import ( + "cmp" + "context" + "errors" + "os" + "slices" + "sync" + + "github.com/flanksource/gavel/sdk/status" +) + +// gavelRule names the catalog rule whose groups are gavel processes. +const gavelRule = "gavel" + +// SlotPool is one gavel slot pool as the gavel processes shown use it. +type SlotPool struct { + // Name is "global" or "project/". + Name string `json:"name"` + // Project is the git common directory of a project pool. + Project string `json:"project,omitempty"` + Limit int `json:"limit"` + Held int `json:"held"` + Waiting int `json:"waiting"` +} + +// SlotPools adds up the leases of statuses by pool, global first. +func SlotPools(statuses []status.Status) []SlotPool { + byName := map[string]*SlotPool{} + for _, s := range statuses { + for _, lease := range s.Slots { + pool, ok := byName[lease.Pool] + if !ok { + pool = &SlotPool{Name: lease.Pool} + byName[lease.Pool] = pool + } + pool.Project = cmp.Or(pool.Project, lease.Project) + pool.Limit = max(pool.Limit, lease.Limit) + if lease.State == status.LeaseWaiting { + pool.Waiting++ + } else { + pool.Held++ + } + } + } + pools := make([]SlotPool, 0, len(byName)) + for _, pool := range byName { + pools = append(pools, *pool) + } + rank := func(p SlotPool) int { + if p.Name == "global" { + return 0 + } + return 1 + } + slices.SortFunc(pools, func(a, b SlotPool) int { + return cmp.Or(cmp.Compare(rank(a), rank(b)), cmp.Compare(a.Project, b.Project), cmp.Compare(a.Name, b.Name)) + }) + return pools +} + +// gavelStatuses follows what each gavel process shown publishes, by pid, +// until it is closed. +type gavelStatuses struct { + cache string + ctx context.Context + cancel context.CancelFunc + mu sync.Mutex + byPID map[int]*gavelWatch +} + +type gavelWatch struct { + cancel context.CancelFunc + latest *status.Status + err error +} + +func newGavelStatuses(cache string) *gavelStatuses { + ctx, cancel := context.WithCancel(context.Background()) + return &gavelStatuses{cache: cache, ctx: ctx, cancel: cancel, byPID: map[int]*gavelWatch{}} +} + +// GavelReading is what a gavel process published, or why it could not be read. +type GavelReading struct { + Status *status.Status + Err error +} + +// of follows the processes pids, stops following the others, and returns +// what each has published so far. A process that has published nothing yet +// is retried on the next call. +func (g *gavelStatuses) of(pids []int) map[int]GavelReading { + g.mu.Lock() + defer g.mu.Unlock() + wanted := map[int]bool{} + for _, pid := range pids { + wanted[pid] = true + if _, ok := g.byPID[pid]; !ok { + g.follow(pid) + } + } + readings := map[int]GavelReading{} + for pid, watch := range g.byPID { + if !wanted[pid] { + watch.cancel() + delete(g.byPID, pid) + continue + } + readings[pid] = GavelReading{Status: watch.latest, Err: watch.err} + } + return readings +} + +// follow starts watching pid, once it has published its status. +func (g *gavelStatuses) follow(pid int) { + if _, err := os.Stat(status.Path(g.cache, pid)); errors.Is(err, os.ErrNotExist) { + return + } + ctx, cancel := context.WithCancel(g.ctx) + watch := &gavelWatch{cancel: cancel} + g.byPID[pid] = watch + watcher, err := status.Watch(ctx, status.WatchOptions{Cache: g.cache, PID: pid}) + if err != nil { + watch.err = err + return + } + go func() { + for update := range watcher.Updates() { + g.mu.Lock() + watch.latest = &update + g.mu.Unlock() + } + g.mu.Lock() + defer g.mu.Unlock() + watch.err = watcher.Err() + // A process whose status went away has finished; it is followed + // again should it publish once more. + if g.byPID[pid] == watch && watch.err == nil { + delete(g.byPID, pid) + } + }() +} + +// close stops following every process. +func (g *gavelStatuses) close() { + g.cancel() + g.mu.Lock() + defer g.mu.Unlock() + clear(g.byPID) +} diff --git a/pkg/tracing/groups/gavel_render.go b/pkg/tracing/groups/gavel_render.go new file mode 100644 index 0000000..8b7a473 --- /dev/null +++ b/pkg/tracing/groups/gavel_render.go @@ -0,0 +1,152 @@ +package groups + +import ( + "cmp" + "fmt" + "path/filepath" + "strings" + "time" + + "github.com/flanksource/gavel/sdk/status" +) + +// GavelText is a gavel process's progress in a line: each task group's and +// its tests' finished of total and failures, then the slots it holds (●) +// and waits for (⧗). +func GavelText(s *status.Status) string { + if s == nil { + return "" + } + var parts []string + for _, group := range s.Groups { + if group.Summary.Total > 0 { + parts = append(parts, summaryText(cmp.Or(group.Kind, group.Name), group.Summary)) + } + } + if s.Tests != nil && s.Tests.Total > 0 { + parts = append(parts, summaryText("tests", *s.Tests)) + } + if slots := SlotGlyphs(s); slots != "" { + parts = append(parts, slots) + } + return strings.Join(parts, " · ") +} + +func leaseGlyph(lease status.Lease) string { + if lease.State == status.LeaseWaiting { + return "⧗" + } + return "●" +} + +// rowBar is the width of a progress bar on a tree row. +const rowBar = 8 + +// barPart is n of a bar's total, drawn as glyph. +type barPart struct { + n int + glyph string +} + +// progressBar draws parts of total across width cells, in order, leaving the +// rest ░. Each part ends where its running sum rounds to, so the parts never +// overflow the bar, but a part that has any takes at least a cell: one +// failure in hundreds still shows. +func progressBar(width, total int, parts ...barPart) string { + var b strings.Builder + b.WriteString("[") + drawn, sum := 0, 0 + for _, part := range parts { + sum += part.n + end := width + if total > 0 { + end = min(width, (sum*width+total/2)/total) + } + if part.n > 0 && end <= drawn && drawn < width { + end = drawn + 1 + } + if end > drawn { + b.WriteString(strings.Repeat(part.glyph, end-drawn)) + drawn = end + } + } + b.WriteString(strings.Repeat("░", width-drawn) + "]") + return b.String() +} + +// summaryBar is a summary as a bar: █ finished, ▓ failed, ▒ running, ░ pending. +func summaryBar(width int, s status.Summary) string { + return progressBar(width, s.Total, barPart{s.Done() - s.Failed, "█"}, barPart{s.Failed, "▓"}, barPart{s.Running, "▒"}) +} + +func summaryText(label string, s status.Summary) string { + text := fmt.Sprintf("%s %s %d/%d", label, summaryBar(rowBar, s), s.Done(), s.Total) + if s.Failed > 0 { + text += fmt.Sprintf(" ✗%d", s.Failed) + } + return text +} + +// poolLabel is "global", or a project pool's repository name. +func poolLabel(pool, project string) string { + if pool == "global" || project == "" { + return pool + } + if filepath.Base(project) == ".git" { + project = filepath.Dir(project) + } + return strings.TrimSuffix(filepath.Base(project), ".git") +} + +// SlotsText is each slot pool's held of limit and how many wait for it. +func SlotsText(pools []SlotPool) string { + var parts []string + for _, pool := range pools { + text := fmt.Sprintf("%s %s %d/%d", poolLabel(pool.Name, pool.Project), progressBar(rowBar, pool.Limit, barPart{pool.Held, "█"}), pool.Held, pool.Limit) + if pool.Waiting > 0 { + text += fmt.Sprintf(" +%d waiting", pool.Waiting) + } + parts = append(parts, text) + } + return strings.Join(parts, " · ") +} + +// SlotGlyphs are the slots a gavel process holds (●) and waits for (⧗). +func SlotGlyphs(s *status.Status) string { + if s == nil { + return "" + } + var leases []string + for _, lease := range s.Slots { + leases = append(leases, leaseGlyph(lease)+poolLabel(lease.Pool, lease.Project)) + } + return strings.Join(leases, " ") +} + +// TaskText is what a row WithGavelTasks added says at now: a task group's +// progress, or a running task, how long it has run and its own progress. +func TaskText(group GroupSample, now time.Time) string { + task := group.Task + switch { + case task == nil: + return "" + case task.Summary != nil: + return summaryText(group.Name, *task.Summary) + } + item := task.Item + text := fmt.Sprintf("▶ %s %s", item.Name, age(now, item.Started)) + if item.Total > 0 { + text += fmt.Sprintf(" %s %d/%d", progressBar(rowBar, item.Total, barPart{item.Done, "█"}), item.Done, item.Total) + } + if item.Description != "" { + text += " · " + item.Description + } + return text +} + +func age(now, since time.Time) string { + if since.IsZero() { + return "-" + } + return now.Sub(since).Round(time.Second).String() +} diff --git a/pkg/tracing/groups/gavel_tasks.go b/pkg/tracing/groups/gavel_tasks.go new file mode 100644 index 0000000..fe3438a --- /dev/null +++ b/pkg/tracing/groups/gavel_tasks.go @@ -0,0 +1,114 @@ +package groups + +import ( + "cmp" + "math" + "strconv" + + "github.com/flanksource/gavel/sdk/status" +) + +// GavelTask is what a row WithGavelTasks adds shows: a task group's +// progress, or one running task. Order keeps the rows in gavel's order. +type GavelTask struct { + Order int + Summary *status.Summary + Item *status.Item +} + +// taskRank orders a gavel's task rows first, in gavel's order. +func taskRank(group GroupSample) int { + if group.Task == nil { + return math.MaxInt + } + return group.Task.Order +} + +// WithGavelTasks nests what each gavel group publishes under it: a row per +// task group with progress, and under each a row per task it is running. +// A skip-listed gavel's tasks claim the group of the process each runs, by +// pid, wherever that group is (a detached process included); its other +// groups stay where ancestry put them. The frame is rolled up again, so a +// claimed group's use counts once, under its task. +func (f Frame) WithGavelTasks() Frame { + byKey := map[string]GroupSample{} + for _, group := range f.Groups { + byKey[group.Key] = group + } + var added []GroupSample + claims := map[int]string{} + ancestors := map[int]map[string]bool{} + for _, group := range f.Groups { + if group.Gavel == nil || group.Kind == KindBucket { + continue + } + rows, itemPIDs := gavelTaskRows(group) + added = append(added, rows...) + if !group.SkipAncestry { + continue + } + lineage := map[string]bool{} + for key := group.Key; key != ""; key = byKey[key].ParentKey { + if lineage[key] { + break + } + lineage[key] = true + } + for pid, key := range itemPIDs { + claims[pid], ancestors[pid] = key, lineage + } + } + if len(added) == 0 { + return f + } + groups := make([]GroupSample, 0, len(f.Groups)+len(added)) + for _, group := range f.Groups { + if key, ok := claims[group.PID]; ok && group.PID != 0 && group.Kind != KindBucket && !ancestors[group.PID][group.Key] { + group.ParentKey = key + } + groups = append(groups, group) + } + f.Groups = Rollup(append(groups, added...)) + return f +} + +// gavelTaskRows are the rows of gavel's task groups and running tasks, and +// the row of each task that runs a process, by its pid. +func gavelTaskRows(gavel GroupSample) ([]GroupSample, map[int]string) { + row := func(key, parent, name, kind string, task *GavelTask) GroupSample { + return GroupSample{ + SampledAt: gavel.SampledAt, Tick: gavel.Tick, Key: key, ParentKey: parent, Name: name, Kind: kind, + Context: gavel.Context, Origin: gavel.Origin, Task: task, + } + } + var rows []GroupSample + byName := map[string]string{} + for _, group := range gavel.Gavel.Groups { + if group.Summary.Total == 0 { + continue + } + name := cmp.Or(group.Kind, group.Name) + key := gavel.Key + "/gavel/" + name + summary := group.Summary + rows = append(rows, row(key, gavel.Key, name, KindGavelTask, &GavelTask{Order: len(rows), Summary: &summary})) + byName[group.Name] = key + } + if tests := gavel.Gavel.Tests; tests != nil && tests.Total > 0 { + summary := *tests + rows = append(rows, row(gavel.Key+"/gavel/tests", gavel.Key, "tests", KindGavelTask, &GavelTask{Order: len(rows), Summary: &summary})) + } + pids := map[int]string{} + for index, item := range gavel.Gavel.Running { + parent, ok := byName[item.Group] + if !ok { + parent = gavel.Key + } + key := parent + "/" + strconv.Itoa(index) + running := item + rows = append(rows, row(key, parent, item.Name, KindGavelItem, &GavelTask{Order: index, Item: &running})) + if item.PID > 0 { + pids[item.PID] = key + } + } + return rows, pids +} diff --git a/pkg/tracing/groups/gavel_tasks_test.go b/pkg/tracing/groups/gavel_tasks_test.go new file mode 100644 index 0000000..1307608 --- /dev/null +++ b/pkg/tracing/groups/gavel_tasks_test.go @@ -0,0 +1,112 @@ +package groups_test + +import ( + "github.com/flanksource/gavel/sdk/status" + "github.com/flanksource/telltale/pkg/tracing/groups" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func parentsOf(frame groups.Frame) map[string]string { + parents := map[string]string{} + for _, group := range frame.Groups { + parents[group.Key] = group.ParentKey + } + return parents +} + +func groupByKey(frame groups.Frame, key string) groups.GroupSample { + GinkgoHelper() + for _, group := range frame.Groups { + if group.Key == key { + return group + } + } + Fail("no group " + key) + return groups.GroupSample{} +} + +var _ = Describe("WithGavelTasks", func() { + usage := func(processes int, rss uint64) groups.Usage { return groups.Usage{Processes: processes, RSSBytes: rss} } + var frame groups.Frame + BeforeEach(func() { + gavel := &status.Status{ + Groups: []status.Group{ + {Name: "Running tests across packages", Kind: status.GroupPackages, Summary: status.Summary{Total: 3, Passed: 1, Running: 2}}, + {Name: "Running linters", Kind: status.GroupLint, Summary: status.Summary{Total: 0}}, + }, + Tests: &status.Summary{Total: 40, Passed: 10, Pending: 30}, + Running: []status.Item{ + {Name: "go test ./pkg/a", Group: "Running tests across packages", PID: 300}, + {Name: "go test ./pkg/b", Group: "Running tests across packages", PID: 400}, + {Name: "prepare", Group: "Unknown group"}, + }, + } + frame = groups.Frame{Groups: []groups.GroupSample{ + {Key: "agent", Name: "claude", Kind: groups.KindAgent, PID: 100, Self: usage(1, 10)}, + {Key: "gavel", ParentKey: "agent", Name: "gavel", Kind: groups.KindTest, PID: 200, Gavel: gavel, SkipAncestry: true, Self: usage(1, 20)}, + {Key: "go-a", ParentKey: "gavel", Name: "go-test", Kind: groups.KindTest, PID: 300, Self: usage(2, 300)}, + {Key: "go-c", ParentKey: "gavel", Name: "go-test", Kind: groups.KindTest, PID: 500, Self: usage(1, 50)}, + {Key: "launchd", Name: "launchd", Kind: groups.KindOther, PID: 1, Self: usage(1, 1)}, + {Key: "go-b", ParentKey: "launchd", Name: "go-test", Kind: groups.KindTest, PID: 400, Self: usage(1, 40)}, + }} + }) + + It("nests task groups, then running tasks, under the gavel, and each task's process group under its task, detached ones included", func() { + nested := frame.WithGavelTasks() + Expect(parentsOf(nested)).To(Equal(map[string]string{ + "agent": "", "launchd": "", + "gavel": "agent", + "gavel/gavel/packages": "gavel", + "gavel/gavel/tests": "gavel", + "gavel/gavel/packages/0": "gavel/gavel/packages", + "gavel/gavel/packages/1": "gavel/gavel/packages", + "gavel/2": "gavel", + "go-a": "gavel/gavel/packages/0", + "go-b": "gavel/gavel/packages/1", + "go-c": "gavel", + }), "an empty lint group has no row; a task of an unknown group sits under the gavel; go-c, which no task claims, stays") + Expect(groupByKey(nested, "gavel/gavel/packages").Total).To(Equal(usage(3, 340)), "the claimed groups' use counts once, under their tasks") + Expect(groupByKey(nested, "gavel").Total).To(Equal(usage(5, 410))) + Expect(groupByKey(nested, "launchd").Total).To(Equal(usage(1, 1)), "the detached go-b moved under its task") + Expect(groupByKey(nested, "gavel/gavel/packages").Task.Summary).To(HaveValue(HaveField("Passed", 1))) + Expect(groupByKey(nested, "gavel/gavel/packages/1").Task.Item).To(HaveValue(HaveField("PID", 400))) + }) + + It("keeps the tasks of a gavel that is not skip-listed from claiming groups", func() { + frame.Groups[1].SkipAncestry = false + parents := parentsOf(frame.WithGavelTasks()) + Expect(parents).To(HaveKeyWithValue("go-a", "gavel")) + Expect(parents).To(HaveKeyWithValue("go-b", "launchd")) + Expect(parents).To(HaveKeyWithValue("gavel/gavel/packages/0", "gavel/gavel/packages")) + }) + + It("never lets a task claim its gavel or the gavel's ancestors", func() { + frame.Groups[1].Gavel.Running[0].PID = 100 + frame.Groups[1].Gavel.Running[1].PID = 200 + parents := parentsOf(frame.WithGavelTasks()) + Expect(parents).To(HaveKeyWithValue("agent", "")) + Expect(parents).To(HaveKeyWithValue("gavel", "agent")) + }) + + It("leaves a frame without gavel status as it is, and composes after a grouping", func() { + frame.Groups[1].Gavel = nil + Expect(frame.WithGavelTasks()).To(Equal(frame)) + + frame.Groups[1].Gavel = &status.Status{Running: []status.Item{{Name: "go test ./pkg/a", PID: 300}}} + for _, by := range []groups.GroupBy{groups.GroupRepo, groups.GroupSlots} { + projected, err := frame.Grouped(by) + Expect(err).NotTo(HaveOccurred()) + Expect(parentsOf(projected.WithGavelTasks())).To(HaveKeyWithValue("go-a", "gavel/0"), "grouped by %s", by) + } + }) +}) + +var _ = DescribeTable("ShortCommand drops the executable's directory", + func(command, short string) { Expect(groups.ShortCommand(command)).To(Equal(short)) }, + Entry("a program on a path", "/opt/homebrew/bin/golangci-lint run ./...", "golangci-lint run ./..."), + Entry("an app bundle's helper, whose name holds spaces", + "/Applications/Acme Browser.app/Contents/Frameworks/Acme.framework/Helpers/Acme Helper (Renderer).app/Contents/MacOS/Acme Helper (Renderer) --type=renderer", + "Acme Helper (Renderer) --type=renderer"), + Entry("a bare program", "gavel test ./...", "gavel test ./..."), +) diff --git a/pkg/tracing/groups/gavel_test.go b/pkg/tracing/groups/gavel_test.go new file mode 100644 index 0000000..4886d7a --- /dev/null +++ b/pkg/tracing/groups/gavel_test.go @@ -0,0 +1,110 @@ +package groups_test + +import ( + "encoding/json" + "os" + "os/exec" + "time" + + "github.com/flanksource/gavel/sdk/status" + "github.com/flanksource/telltale/pkg/tracing/groups" + "github.com/flanksource/telltale/pkg/tracing/process" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func publish(cache string, s status.Status) { + GinkgoHelper() + data, err := json.Marshal(s) + Expect(err).NotTo(HaveOccurred()) + Expect(os.MkdirAll(status.Dir(cache), 0o700)).To(Succeed()) + Expect(os.WriteFile(status.Path(cache, s.PID), data, 0o600)).To(Succeed()) +} + +var ( + acme = "/src/acme/.git" + global = func(state string, index int) status.Lease { + return status.Lease{Pool: "global", Limit: 4, Index: index, State: state} + } + project = func(state string, index int) status.Lease { + return status.Lease{Pool: "project/abc", Project: acme, Limit: 2, Index: index, State: state} + } +) + +var _ = Describe("gavel status in Top", func() { + It("shows what a gavel group's process publishes, until it stops publishing", func(ctx SpecContext) { + cache := GinkgoT().TempDir() + catalog, err := groups.LoadCatalog(writeCatalog("groups:\n - name: gavel\n kind: test\n target: positional\n match: [{exec: [sleep]}]\n")) + Expect(err).NotTo(HaveOccurred()) + gavel := exec.Command("sleep", "31") + Expect(gavel.Start()).To(Succeed()) + DeferCleanup(func() { _ = gavel.Process.Kill(); _ = gavel.Wait() }) + pid := gavel.Process.Pid + publish(cache, status.Status{PID: pid, Command: "gavel lint", + Groups: []status.Group{{Name: "Running linters", Kind: status.GroupLint, Summary: status.Summary{Total: 4, Passed: 1, Running: 3}}}, + Slots: []status.Lease{global(status.LeaseHeld, 0), project(status.LeaseWaiting, -1)}, + }) + + top, err := groups.NewTop(ctx, process.NewSampler(), groups.TopOptions{Catalog: catalog, Groups: []string{"gavel"}, GavelCache: cache}) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(top.Close) + var frame groups.Frame + gavelGroup := func() groups.GroupSample { + frame, err = top.Tick(ctx) + Expect(err).NotTo(HaveOccurred()) + for _, group := range frame.Groups { + if group.PID == pid { + return group + } + } + Fail("the gavel process has no group") + return groups.GroupSample{} + } + + Eventually(gavelGroup).WithTimeout(5 * time.Second).Should(SatisfyAll( + HaveField("Gavel", HaveValue(HaveField("Command", "gavel lint"))), + HaveField("Gavel.Groups", ConsistOf(HaveField("Summary.Passed", 1))), + )) + Expect(frame.Slots).To(Equal([]groups.SlotPool{ + {Name: "global", Limit: 4, Held: 1}, + {Name: "project/abc", Project: acme, Limit: 2, Waiting: 1}, + })) + + publish(cache, status.Status{PID: pid, Command: "gavel lint", + Groups: []status.Group{{Name: "Running linters", Kind: status.GroupLint, Summary: status.Summary{Total: 4, Passed: 4}}}}) + Eventually(gavelGroup).WithTimeout(5 * time.Second).Should(HaveField("Gavel.Groups", ConsistOf(HaveField("Summary.Passed", 4)))) + + Expect(os.Remove(status.Path(cache, pid))).To(Succeed()) + Eventually(gavelGroup).WithTimeout(5 * time.Second).Should(HaveField("Gavel", BeNil())) + }, SpecTimeout(30*time.Second)) +}) + +var _ = Describe("gavel slot pools", func() { + It("adds up held and waiting leases per pool across processes, global first", func() { + pools := groups.SlotPools([]status.Status{ + {PID: 1, Slots: []status.Lease{project(status.LeaseHeld, 0), global(status.LeaseHeld, 0)}}, + {PID: 2, Slots: []status.Lease{project(status.LeaseHeld, 1), global(status.LeaseHeld, 1)}}, + {PID: 3, Slots: []status.Lease{project(status.LeaseWaiting, -1)}}, + }) + Expect(pools).To(Equal([]groups.SlotPool{ + {Name: "global", Limit: 4, Held: 2}, + {Name: "project/abc", Project: acme, Limit: 2, Held: 2, Waiting: 1}, + })) + Expect(groups.SlotsText(pools)).To(Equal("global [████░░░░] 2/4 · acme [████████] 2/2 +1 waiting")) + }) + + It("says a process's progress in a line: groups, tests, then held and awaited slots", func() { + text := groups.GavelText(&status.Status{ + Groups: []status.Group{ + {Kind: status.GroupPackages, Summary: status.Summary{Total: 40, Passed: 10, Failed: 2, Running: 4, Pending: 24}}, + {Kind: status.GroupLint, Summary: status.Summary{}}, + {Name: "nested", Summary: status.Summary{Total: 1, Passed: 1}}, + }, + Tests: &status.Summary{Total: 400, Passed: 118, Failed: 2, Pending: 280}, + Slots: []status.Lease{global(status.LeaseHeld, 0), project(status.LeaseWaiting, -1)}, + }) + // packages: 10 passed → 2 cells █, 2 failed → 1 ▓, 4 running → 1 ▒; tests: one ▓ cell for 2 failures in 400. + Expect(text).To(Equal("packages [██▓▒░░░░] 12/40 ✗2 · nested [████████] 1/1 · tests [██▓░░░░░] 120/400 ✗2 · ●global ⧗acme")) + Expect(groups.GavelText(nil)).To(BeEmpty()) + }) +}) diff --git a/pkg/tracing/groups/grouping.go b/pkg/tracing/groups/grouping.go index 5331898..6710142 100644 --- a/pkg/tracing/groups/grouping.go +++ b/pkg/tracing/groups/grouping.go @@ -4,6 +4,8 @@ import ( "fmt" "path/filepath" "strings" + + "github.com/flanksource/gavel/sdk/status" ) type GroupBy string @@ -13,14 +15,23 @@ const ( GroupRepo GroupBy = "repo" GroupWorktree GroupBy = "worktree" GroupClaudeSession GroupBy = "claude-session" - KindBucket = "bucket" + // GroupSlots buckets by the gavel slot pool a group's gavel process holds. + GroupSlots GroupBy = "slots" +) + +const ( + KindBucket = "bucket" + // KindGavelTask and KindGavelItem are the rows WithGavelTasks adds: a + // gavel task group and one of its running tasks. + KindGavelTask = "gavel-task" + KindGavelItem = "gavel-item" ) -var Groupings = []GroupBy{GroupTree, GroupRepo, GroupWorktree, GroupClaudeSession} +var Groupings = []GroupBy{GroupTree, GroupRepo, GroupWorktree, GroupClaudeSession, GroupSlots} func (by GroupBy) Validate() error { switch by { - case "", GroupTree, GroupRepo, GroupWorktree, GroupClaudeSession: + case "", GroupTree, GroupRepo, GroupWorktree, GroupClaudeSession, GroupSlots: return nil default: return fmt.Errorf("group-by %q: expected one of %v", by, Groupings) @@ -38,11 +49,19 @@ func (f Frame) Grouped(by GroupBy) (Frame, error) { if err != nil { return Frame{}, err } + identities := map[string]bucket{} + if by == GroupSlots { + identities = slotBuckets(f.Groups) + } else { + for _, group := range f.Groups { + identity, label := bucketIdentity(by, contexts[group.Key]) + identities[group.Key] = bucket{identity, label} + } + } buckets := map[string]string{} skipped := map[string]bool{} for _, group := range f.Groups { - identity, _ := bucketIdentity(by, contexts[group.Key]) - buckets[group.Key] = "bucket:" + string(by) + ":" + identity + buckets[group.Key] = "bucket:" + string(by) + ":" + identities[group.Key].identity skipped[group.Key] = group.PID == 0 && (group.Kind == KindOther || group.Kind == KindApp) } var projected []GroupSample @@ -53,8 +72,8 @@ func (f Frame) Grouped(by GroupBy) (Frame, error) { } key := buckets[group.Key] if !created[key] { - identity, label := bucketIdentity(by, contexts[group.Key]) - projected = append(projected, GroupSample{Key: key, Kind: KindBucket, Name: label, Target: identity, Command: identity, SampledAt: f.SampledAt, Tick: f.Tick}) + id := identities[group.Key] + projected = append(projected, GroupSample{Key: key, Kind: KindBucket, Name: id.label, Target: id.identity, Command: id.identity, SampledAt: f.SampledAt, Tick: f.Tick}) created[key] = true } if group.ParentKey == "" || buckets[group.ParentKey] != key || skipped[group.ParentKey] { @@ -67,6 +86,69 @@ func (f Frame) Grouped(by GroupBy) (Frame, error) { return f, nil } +// bucket is what a group is bucketed by, and the bucket's name. +type bucket struct{ identity, label string } + +// slotBuckets puts each group in the slot pool its gavel process holds — a +// project pool before the global one — or, holding none, the pool it waits +// for. A group with no gavel status of its own takes its parent's bucket, so +// a gavel's tests share its pool. +func slotBuckets(groups []GroupSample) map[string]bucket { + byKey := map[string]GroupSample{} + for _, group := range groups { + byKey[group.Key] = group + } + resolved := map[string]bucket{} + // ResolveContexts has refused a cycle by now. + var resolve func(key string) bucket + resolve = func(key string) bucket { + if found, ok := resolved[key]; ok { + return found + } + group, ok := byKey[key] + if !ok { + return bucket{"", "Unattributed"} + } + found, own := slotBucket(group.Gavel) + if !own { + found = resolve(group.ParentKey) + } + resolved[key] = found + return found + } + for _, group := range groups { + resolve(group.Key) + } + return resolved +} + +// slotBucket is the pool a gavel status's leases name, and whether it has any. +func slotBucket(s *status.Status) (bucket, bool) { + if s == nil || len(s.Slots) == 0 { + return bucket{}, false + } + best := s.Slots[0] + rank := func(l status.Lease) int { + score := 0 + if l.State != status.LeaseWaiting { + score += 2 + } + if l.Pool != "global" { + score++ + } + return score + } + for _, lease := range s.Slots[1:] { + if rank(lease) > rank(best) { + best = lease + } + } + if best.State == status.LeaseWaiting { + return bucket{best.Pool + ":waiting", poolLabel(best.Pool, best.Project) + " (waiting)"}, true + } + return bucket{best.Pool, poolLabel(best.Pool, best.Project)}, true +} + func bucketIdentity(by GroupBy, c Context) (string, string) { switch by { case GroupRepo: diff --git a/pkg/tracing/groups/grouping_test.go b/pkg/tracing/groups/grouping_test.go index 7404a53..ecf3bd5 100644 --- a/pkg/tracing/groups/grouping_test.go +++ b/pkg/tracing/groups/grouping_test.go @@ -4,6 +4,7 @@ import ( "encoding/json" "os" + "github.com/flanksource/gavel/sdk/status" "github.com/flanksource/telltale/pkg/tracing/groups" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" @@ -114,4 +115,43 @@ var _ = Describe("Frame.Grouped", func() { Expect(projected.Groups[0].Total.NetRx).To(HaveValue(Equal(float64(1024)))) Expect(projected.Groups[2].Total.NetRx).To(BeNil()) }) + + It("buckets gavel groups by the slot pool they hold, their tests with them, and queued ones by the pool they wait for", func() { + held := &status.Status{Slots: []status.Lease{ + {Pool: "global", Limit: 4, State: status.LeaseHeld}, + {Pool: "project/abc", Project: "/src/acme/.git", Limit: 2, State: status.LeaseHeld}, + }} + queued := &status.Status{Slots: []status.Lease{{Pool: "project/abc", Project: "/src/acme/.git", Limit: 2, Index: -1, State: status.LeaseWaiting}}} + usage := groups.Usage{Processes: 1, RSSBytes: 10} + frame.Groups = []groups.GroupSample{ + {Key: "agent", Name: "claude", Kind: groups.KindAgent, PID: 1, Self: usage}, + {Key: "gavel-a", ParentKey: "agent", Name: "gavel", Kind: groups.KindTest, PID: 2, Gavel: held, Self: usage}, + {Key: "go-test", ParentKey: "gavel-a", Name: "go-test", Kind: groups.KindTest, PID: 3, Self: usage}, + {Key: "gavel-b", ParentKey: "agent", Name: "gavel", Kind: groups.KindTest, PID: 4, Gavel: queued, Self: usage}, + } + projected, err := frame.Grouped(groups.GroupSlots) + Expect(err).NotTo(HaveOccurred()) + parents := map[string]string{} + for _, group := range projected.Groups { + parents[group.Key] = group.ParentKey + } + Expect(parents).To(Equal(map[string]string{ + "bucket:slots:": "", + "agent": "bucket:slots:", + "bucket:slots:project/abc": "", + "gavel-a": "bucket:slots:project/abc", + "go-test": "gavel-a", + "bucket:slots:project/abc:waiting": "", + "gavel-b": "bucket:slots:project/abc:waiting", + })) + names := map[string]string{} + for _, group := range projected.Groups { + if group.Kind == groups.KindBucket { + names[group.Key] = group.Name + } + } + Expect(names).To(Equal(map[string]string{ + "bucket:slots:": "Unattributed", "bucket:slots:project/abc": "acme", "bucket:slots:project/abc:waiting": "acme (waiting)", + })) + }) }) diff --git a/pkg/tracing/groups/hogs.go b/pkg/tracing/groups/hogs.go new file mode 100644 index 0000000..f91cd9f --- /dev/null +++ b/pkg/tracing/groups/hogs.go @@ -0,0 +1,82 @@ +package groups + +import ( + "maps" + "strings" + "time" +) + +// Hogs keeps each resource's pin expiry, measured from its last excessive sample. +type Hogs map[string]time.Time + +const HogRetention = 120 * time.Second + +func (h Hogs) Pinned(at time.Time) bool { + for _, until := range h { + if until.After(at) { + return true + } + } + return false +} + +func (h Hogs) Label(at time.Time) string { + var resources []string + for _, resource := range []string{"CPU", "memory", "swap", "compressed"} { + if h[resource].After(at) { + resources = append(resources, resource) + } + } + if len(resources) == 0 { + return "" + } + return strings.Join(resources, "/") + " hog" +} + +func (h Hogs) merge(other Hogs) Hogs { + merged := maps.Clone(h) + for resource, until := range other { + if until.After(merged[resource]) { + if merged == nil { + merged = Hogs{} + } + merged[resource] = until + } + } + return merged +} + +type hogTracker struct { + last map[string]Hogs +} + +func (h *hogTracker) observe(readings map[string]Reading, host HostUsage, at time.Time) { + next := make(map[string]Hogs, len(readings)) + for key, reading := range readings { + var recent Hogs + for resource, until := range h.last[key] { + if until.After(at) { + if recent == nil { + recent = Hogs{} + } + recent[resource] = until + } + } + for resource, hogging := range map[string]bool{ + "CPU": host.Cores > 0 && reading.CPUPercent != nil && *reading.CPUPercent > 25*float64(host.Cores), + "memory": host.MemoryTotalBytes > 0 && reading.RSSBytes > host.MemoryTotalBytes/4, + "swap": host.SwapTotalBytes > 0 && reading.SwapBytes != nil && *reading.SwapBytes > host.SwapTotalBytes/4, + "compressed": host.MemoryTotalBytes > 0 && reading.CompressedBytes != nil && *reading.CompressedBytes > host.MemoryTotalBytes/4, + } { + if hogging { + if recent == nil { + recent = Hogs{} + } + recent[resource] = at.Add(HogRetention) + } + } + reading.Hogs = recent + readings[key], next[key] = reading, recent + } + h.last = next +} diff --git a/pkg/tracing/groups/hogs_test.go b/pkg/tracing/groups/hogs_test.go new file mode 100644 index 0000000..091c831 --- /dev/null +++ b/pkg/tracing/groups/hogs_test.go @@ -0,0 +1,87 @@ +package groups + +import ( + "time" + + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = ginkgo.Describe("resource hogs", func() { + start := time.Date(2026, 11, 6, 10, 0, 0, 0, time.UTC) + host := HostUsage{Cores: 8, MemoryTotalBytes: 16 << 30, SwapTotalBytes: 4 << 30} + ginkgo.DescribeTable("detects excessive use of each resource", func(reading Reading, resource string) { + readings := map[string]Reading{"worker@1": reading} + var tracker hogTracker + tracker.observe(readings, host, start) + Expect(readings["worker@1"].Hogs).To(Equal(Hogs{resource: start.Add(HogRetention)})) + }, + ginkgo.Entry("CPU across all cores", Reading{CPUPercent: new(201.0)}, "CPU"), + ginkgo.Entry("resident memory", Reading{RSSBytes: 5 << 30}, "memory"), + ginkgo.Entry("swap", Reading{SwapBytes: new(uint64(2 << 30))}, "swap"), + ginkgo.Entry("compressed memory", Reading{CompressedBytes: new(uint64(5 << 30))}, "compressed"), + ) + + ginkgo.It("uses strict thresholds and never flags unavailable capacities", func() { + readings := map[string]Reading{"worker@1": {CPUPercent: new(200.0), RSSBytes: 4 << 30, SwapBytes: new(uint64(1 << 30)), CompressedBytes: new(uint64(4 << 30))}} + var tracker hogTracker + tracker.observe(readings, host, start) + Expect(readings["worker@1"].Hogs).To(BeEmpty()) + tracker.observe(readings, HostUsage{}, start) + Expect(readings["worker@1"].Hogs).To(BeEmpty()) + }) + + ginkgo.It("retains a spike for exactly 120 seconds and extends only the resource still hogging", func() { + var tracker hogTracker + readings := map[string]Reading{"worker@1": {CPUPercent: new(201.0), RSSBytes: 5 << 30}} + tracker.observe(readings, host, start) + first := readings["worker@1"].Hogs + readings["worker@1"] = Reading{RSSBytes: 5 << 30} + tracker.observe(readings, host, start.Add(time.Minute)) + Expect(first).To(Equal(Hogs{"CPU": start.Add(HogRetention), "memory": start.Add(HogRetention)}), "previous frames must not mutate") + readings["worker@1"] = Reading{} + tracker.observe(readings, host, start.Add(HogRetention)) + Expect(readings["worker@1"].Hogs).To(Equal(Hogs{"memory": start.Add(3 * time.Minute)})) + Expect(readings["worker@1"].Hogs.Pinned(start.Add(3*time.Minute - time.Nanosecond))).To(BeTrue()) + tracker.observe(readings, host, start.Add(3*time.Minute)) + Expect(readings["worker@1"].Hogs.Pinned(start.Add(3 * time.Minute))).To(BeFalse()) + }) + + ginkgo.It("forgets exited processes and does not transfer pins to a reused pid", func() { + var tracker hogTracker + readings := map[string]Reading{"100@1": {RSSBytes: 5 << 30}} + tracker.observe(readings, host, start) + readings = map[string]Reading{"100@2": {}} + tracker.observe(readings, host, start.Add(time.Second)) + Expect(readings["100@2"].Hogs).To(BeEmpty()) + Expect(tracker.last).NotTo(HaveKey("100@1")) + }) + + ginkgo.It("rolls up swap, compressed memory and descendant pins without double counting", func() { + hogs := Hogs{"swap": start.Add(HogRetention)} + groups := Rollup([]GroupSample{ + {Key: "parent", Self: Usage{Processes: 1, RSSBytes: 100, SwapBytes: new(uint64(10)), CompressedBytes: new(uint64(20))}}, + {Key: "child", ParentKey: "parent", Self: Usage{Processes: 1, RSSBytes: 200, SwapBytes: new(uint64(30)), CompressedBytes: new(uint64(40)), Hogs: hogs}}, + }) + Expect(groups[0].Total).To(Equal(Usage{Processes: 2, RSSBytes: 300, SwapBytes: new(uint64(40)), CompressedBytes: new(uint64(60)), Hogs: hogs})) + Expect(groups[0].Self.Hogs).To(BeNil()) + }) + + ginkgo.It("pins the branch containing a hog ahead of every sort direction", func() { + frame := Frame{SampledAt: start, Groups: []GroupSample{ + {Key: "busy", Name: "a", Total: Usage{CPUPercent: new(100.0), RSSBytes: 1000}}, + {Key: "hog", Name: "z", Total: Usage{Hogs: Hogs{"memory": start.Add(HogRetention)}}}, + }} + for _, by := range Sorts { + for _, reverse := range []bool{false, true} { + sorted, err := frame.Sorted(Order{By: by, Reverse: reverse}) + Expect(err).NotTo(HaveOccurred()) + Expect(sorted.Groups[0].Key).To(Equal("hog"), "%s reverse=%t", by, reverse) + } + } + frame.SampledAt = start.Add(HogRetention) + sorted, err := frame.Sorted(Order{By: SortMemory}) + Expect(err).NotTo(HaveOccurred()) + Expect(sorted.Groups[0].Key).To(Equal("busy")) + }) +}) diff --git a/pkg/tracing/groups/memory.go b/pkg/tracing/groups/memory.go new file mode 100644 index 0000000..e11367b --- /dev/null +++ b/pkg/tracing/groups/memory.go @@ -0,0 +1,68 @@ +package groups + +import ( + "bufio" + "fmt" + "io" + "math" + "strconv" + "strings" +) + +func parseCompressed(reader io.Reader) (map[int]*uint64, error) { + values := map[int]*uint64{} + scanner := bufio.NewScanner(reader) + header := false + for scanner.Scan() { + fields := strings.Fields(scanner.Text()) + if strings.Join(fields, " ") == "PID CMPRS" { + header = true + continue + } + if !header || len(fields) == 0 { + continue + } + if len(fields) != 2 { + return nil, fmt.Errorf("compressed memory: expected PID CMPRS, got %q", scanner.Text()) + } + pid, err := strconv.Atoi(fields[0]) + if err != nil || pid < 0 { + return nil, fmt.Errorf("compressed memory: invalid PID %q", fields[0]) + } + size, err := parseMemorySize(fields[1]) + if err != nil { + return nil, err + } + if pid > 0 { + values[pid] = &size + } + } + if err := scanner.Err(); err != nil { + return nil, fmt.Errorf("compressed memory listing: %w", err) + } + if !header || len(values) == 0 { + return nil, fmt.Errorf("compressed memory listing has no PID CMPRS readings") + } + return values, nil +} + +func parseMemorySize(raw string) (uint64, error) { + if len(raw) < 2 { + return 0, fmt.Errorf("compressed memory: invalid size %q", raw) + } + unit := strings.IndexByte("BKMGTPE", raw[len(raw)-1]) + value, err := strconv.ParseFloat(raw[:len(raw)-1], 64) + value *= math.Pow(1024, float64(unit)) + if err != nil || unit < 0 || math.IsNaN(value) || value < 0 || value >= math.Exp2(64) { + return 0, fmt.Errorf("compressed memory: invalid size %q", raw) + } + return uint64(value), nil +} + +// MemorySize preserves unavailable readings as a dash. +func MemorySize(value *uint64) string { + if value == nil { + return "-" + } + return Size(float64(*value)) +} diff --git a/pkg/tracing/groups/memory_darwin.go b/pkg/tracing/groups/memory_darwin.go new file mode 100644 index 0000000..55b2b42 --- /dev/null +++ b/pkg/tracing/groups/memory_darwin.go @@ -0,0 +1,36 @@ +package groups + +import ( + "bytes" + "context" + "fmt" + "os/exec" + "strings" +) + +func readMemory(ctx context.Context, classified []Group, readings map[string]Reading) error { + var stdout, stderr bytes.Buffer + // macOS accounts compressed and swapped-out pages together in CMPRS; + // it does not expose a separate per-process disk-swap total. + cmd := exec.CommandContext(ctx, "/usr/bin/top", "-l", "1", "-stats", "pid,cmprs", "-R", "-F") + cmd.Stdout, cmd.Stderr = &stdout, &stderr + if err := cmd.Run(); err != nil { + return fmt.Errorf("read compressed memory: %w: %s", err, strings.TrimSpace(stderr.String())) + } + compressed, err := parseCompressed(&stdout) + if err != nil { + return err + } + for _, group := range classified { + for _, member := range group.Members { + key := keyOf(member) + reading := readings[key] + reading.CompressedBytes = compressed[member.PID] + if reading.CompressedBytes == nil { + reading.MemoryError = fmt.Sprintf("PID %d absent from compressed-memory listing", member.PID) + } + readings[key] = reading + } + } + return nil +} diff --git a/pkg/tracing/groups/memory_linux.go b/pkg/tracing/groups/memory_linux.go new file mode 100644 index 0000000..04b104a --- /dev/null +++ b/pkg/tracing/groups/memory_linux.go @@ -0,0 +1,29 @@ +package groups + +import ( + "context" + "fmt" + + "github.com/shirou/gopsutil/v4/process" +) + +func readMemory(ctx context.Context, classified []Group, readings map[string]Reading) error { + for _, group := range classified { + for _, member := range group.Members { + if err := ctx.Err(); err != nil { + return err + } + key := keyOf(member) + reading := readings[key] + p := process.Process{Pid: int32(member.PID)} + memory, err := p.MemoryInfoWithContext(ctx) + if err != nil { + reading.MemoryError = fmt.Sprintf("PID %d swap: %v", member.PID, err) + } else { + reading.SwapBytes = &memory.Swap + } + readings[key] = reading + } + } + return nil +} diff --git a/pkg/tracing/groups/memory_other.go b/pkg/tracing/groups/memory_other.go new file mode 100644 index 0000000..ae8bd5b --- /dev/null +++ b/pkg/tracing/groups/memory_other.go @@ -0,0 +1,10 @@ +//go:build !darwin && !linux + +package groups + +import "context" + +// Per-process swap and compressed memory are unavailable on other platforms. +func readMemory(ctx context.Context, _ []Group, _ map[string]Reading) error { + return ctx.Err() +} diff --git a/pkg/tracing/groups/memory_test.go b/pkg/tracing/groups/memory_test.go new file mode 100644 index 0000000..197ada6 --- /dev/null +++ b/pkg/tracing/groups/memory_test.go @@ -0,0 +1,31 @@ +package groups + +import ( + "strings" + + "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = ginkgo.Describe("compressed memory listing", func() { + ginkgo.It("reads macOS top's compressed bytes independently of resident memory and swap", func() { + listing := "Processes: 3 total\nPhysMem: 16G used\n\nPID CMPRS\n100 0B\n200 1.5G\n300 8384K\n0 0B\n" + values, err := parseCompressed(strings.NewReader(listing)) + Expect(err).NotTo(HaveOccurred()) + Expect(values).To(Equal(map[int]*uint64{100: new(uint64(0)), 200: new(uint64(1536 << 20)), 300: new(uint64(8384 << 10))})) + }) + + ginkgo.DescribeTable("refuses malformed listings", func(listing string) { + _, err := parseCompressed(strings.NewReader(listing)) + Expect(err).To(HaveOccurred()) + }, + ginkgo.Entry("no header", "100 20M\n"), + ginkgo.Entry("no processes", "PID CMPRS\n"), + ginkgo.Entry("invalid units", "PID CMPRS\n100 20X\n"), + ginkgo.Entry("invalid pid", "PID CMPRS\nworker 20M\n"), + ginkgo.Entry("missing column", "PID CMPRS\n100\n"), + ginkgo.Entry("negative memory", "PID CMPRS\n100 -1M\n"), + ginkgo.Entry("non-finite memory", "PID CMPRS\n100 NaNG\n"), + ginkgo.Entry("overflow", "PID CMPRS\n100 999999999999999999G\n"), + ) +}) diff --git a/pkg/tracing/groups/render.go b/pkg/tracing/groups/render.go index b364847..32f4db0 100644 --- a/pkg/tracing/groups/render.go +++ b/pkg/tracing/groups/render.go @@ -14,16 +14,18 @@ import ( // The columns a Frame's siblings are sorted by, by their Total but for the // name. const ( - SortCPU = "cpu" - SortMemory = "mem" - SortIO = "io" - SortNet = "net" - SortProcesses = "procs" - SortName = "name" + SortCPU = "cpu" + SortMemory = "mem" + SortSwap = "swap" + SortCompressed = "compressed" + SortIO = "io" + SortNet = "net" + SortProcesses = "procs" + SortName = "name" ) // Sorts are every column a Frame sorts by. -var Sorts = []string{SortCPU, SortMemory, SortIO, SortNet, SortProcesses, SortName} +var Sorts = []string{SortCPU, SortMemory, SortSwap, SortCompressed, SortIO, SortNet, SortProcesses, SortName} // Order is the column siblings are sorted by: a usage column highest first, // the name A first, unless Reverse turns it. @@ -57,7 +59,19 @@ func (f Frame) Sorted(order Order) (Frame, error) { var walk func(parent string) walk = func(parent string) { siblings := children[parent] - slices.SortStableFunc(siblings, compare) + slices.SortStableFunc(siblings, func(a, b GroupSample) int { + // A gavel's task and running-task rows come first, in gavel's order. + if a.Task != nil || b.Task != nil { + return cmp.Compare(taskRank(a), taskRank(b)) + } + if a.Total.Hogs.Pinned(f.SampledAt) != b.Total.Hogs.Pinned(f.SampledAt) { + if a.Total.Hogs.Pinned(f.SampledAt) { + return -1 + } + return 1 + } + return compare(a, b) + }) for _, group := range siblings { sorted.Groups = append(sorted.Groups, group) walk(group.Key) @@ -87,6 +101,20 @@ func comparer(order Order) (func(a, b GroupSample) int, error) { value = func(u Usage) float64 { return deref(u.CPUPercent) } case SortMemory: value = func(u Usage) float64 { return float64(u.RSSBytes) } + case SortSwap: + value = func(u Usage) float64 { + if u.SwapBytes == nil { + return 0 + } + return float64(*u.SwapBytes) + } + case SortCompressed: + value = func(u Usage) float64 { + if u.CompressedBytes == nil { + return 0 + } + return float64(*u.CompressedBytes) + } case SortIO: value = func(u Usage) float64 { return deref(u.DiskRead) + deref(u.DiskWrite) } case SortNet: @@ -110,8 +138,8 @@ const nameWidth = 44 // Pretty is the frame as a top table: each group's Total, indented under its // parent, with where it runs and what started it. func (f Frame) Pretty() api.Text { - text := api.Text{}.AddText(fmt.Sprintf("%-*s %5s %7s %8s %9s %9s %9s %9s %5s %-24s %s", - nameWidth, "GROUP", "PROCS", "CPU%", "RSS", "DISK R/s", "DISK W/s", "NET IN/s", "NET OUT/s", "SOCK", "ORIGIN", "CONTEXT"), "font-bold") + text := api.Text{}.AddText(fmt.Sprintf("%-*s %5s %7s %8s %8s %8s %9s %9s %9s %9s %5s %-24s %s", + nameWidth, "GROUP", "PROCS", "CPU%", "RSS", "CMPRS", "SWAP", "DISK R/s", "DISK W/s", "NET IN/s", "NET OUT/s", "SOCK", "ORIGIN", "CONTEXT"), "font-bold") depth := map[string]int{} for _, group := range f.Groups { level, ok := depth[group.ParentKey] @@ -121,11 +149,20 @@ func (f Frame) Pretty() api.Text { depth[group.Key] = level usage := group.Total name := strings.Repeat(" ", level) + Label(group) - text = text.NewLine().AddText(fmt.Sprintf("%-*s %5d %7s %8s %9s %9s %9s %9s %5s %-24s ", - nameWidth, Truncate(name, nameWidth), usage.Processes, Percent(usage.CPUPercent), Size(float64(usage.RSSBytes)), + if label := usage.Hogs.Label(f.SampledAt); label != "" { + name = "! " + label + " · " + name + } + text = text.NewLine().AddText(fmt.Sprintf("%-*s %5d %7s %8s %8s %8s %9s %9s %9s %9s %5s %-24s ", + nameWidth, Truncate(name, nameWidth), usage.Processes, Percent(usage.CPUPercent), Size(float64(usage.RSSBytes)), MemorySize(usage.CompressedBytes), MemorySize(usage.SwapBytes), Rate(usage.DiskRead), Rate(usage.DiskWrite), Rate(usage.NetRx), Rate(usage.NetTx), Count(usage.Sockets), Truncate(OriginText(group.Origin), 24)), kindStyle(group.Kind)). AddText(ContextText(group.Context), "text-gray-500") + if progress := GavelText(group.Gavel); progress != "" { + text = text.AddText(" · "+progress, "text-green-600") + } + } + if len(f.Slots) > 0 { + text = text.NewLine().AddText("slots "+SlotsText(f.Slots), "text-gray-500") } return text.NewLine().AddText(fmt.Sprintf("%d groups · tick %d · %s", len(f.Groups), f.Tick, f.SampledAt.Local().Format("15:04:05")), "text-gray-500") } @@ -203,6 +240,21 @@ func OriginText(o Origin) string { } // Truncate cuts text to width, ending it with an ellipsis where it cut. +// macExecutable is where an app bundle keeps its executables; the name that +// follows can hold spaces, as Google Chrome Helper (Renderer) does. +const macExecutable = "/Contents/MacOS/" + +// ShortCommand is a command line without its executable's directory; an +// app bundle's executable starts at its name, after Contents/MacOS. +func ShortCommand(command string) string { + if index := strings.LastIndex(command, macExecutable); index >= 0 { + return command[index+len(macExecutable):] + } + fields := strings.SplitN(command, " ", 2) + fields[0] = filepath.Base(fields[0]) + return strings.Join(fields, " ") +} + func Truncate(text string, width int) string { runes := []rune(text) if len(runes) <= width { diff --git a/pkg/tracing/groups/snapshot.go b/pkg/tracing/groups/snapshot.go index cd9f1c8..5b1695e 100644 --- a/pkg/tracing/groups/snapshot.go +++ b/pkg/tracing/groups/snapshot.go @@ -2,13 +2,19 @@ package groups import ( "context" + clickyprocess "github.com/flanksource/clicky/process" + "github.com/flanksource/telltale/pkg/tracing/process" + "maps" "slices" ) // Snapshot holds attribution and measurements from the same unfiltered tick. type Snapshot struct { - Frame Frame `json:"frame"` - Processes []ProcessSample `json:"processes"` + Frame Frame `json:"frame"` + Processes []ProcessSample `json:"processes"` + Observed []process.Observed `json:"-"` + Descriptors map[int][]clickyprocess.Descriptor `json:"-"` + IO map[int]clickyprocess.Process `json:"-"` } func (t *Top) Snapshot(ctx context.Context) (Snapshot, error) { @@ -18,7 +24,7 @@ func (t *Top) Snapshot(ctx context.Context) (Snapshot, error) { if err != nil { return Snapshot{}, err } - return Snapshot{Frame: frame, Processes: append([]ProcessSample(nil), t.processes...)}, nil + return Snapshot{Frame: frame, Processes: slices.Clone(t.processes), Observed: slices.Clone(t.observed), Descriptors: maps.Clone(t.held), IO: maps.Clone(t.io)}, nil } func (t *Top) Tick(ctx context.Context) (Frame, error) { @@ -29,7 +35,7 @@ func (t *Top) Tick(ctx context.Context) (Frame, error) { shown := snapshot.Frame.Groups[:0] kept := map[string]bool{} for _, group := range snapshot.Frame.Groups { - if group.Kind == KindOther && !t.options.All { + if group.Kind == KindOther && !t.options.All && !group.Total.Hogs.Pinned(snapshot.Frame.SampledAt) { continue } if len(t.options.Groups) > 0 && !slices.Contains(t.options.Groups, group.Name) && !kept[group.ParentKey] { diff --git a/pkg/tracing/groups/summary.go b/pkg/tracing/groups/summary.go new file mode 100644 index 0000000..fd09179 --- /dev/null +++ b/pkg/tracing/groups/summary.go @@ -0,0 +1,29 @@ +package groups + +import "iter" + +func (kind) Summarize(rows iter.Seq[GroupSample]) (map[string]any, error) { + var tick int64 + var usage Usage + groups := 0 + for row := range rows { + if row.Tick < tick { + continue + } + if row.Tick > tick { + tick = row.Tick + usage = Usage{} + groups = 0 + } + groups++ + usage.merge(row.Self) + } + result := map[string]any{"groups": groups, "processes": usage.Processes, "rssBytes": usage.RSSBytes} + if usage.CPUPercent != nil { + result["cpuPercent"] = *usage.CPUPercent + } + if usage.SwapBytes != nil { + result["swapBytes"] = *usage.SwapBytes + } + return result, nil +} diff --git a/pkg/tracing/groups/top.go b/pkg/tracing/groups/top.go index 77a13fc..d6f0181 100644 --- a/pkg/tracing/groups/top.go +++ b/pkg/tracing/groups/top.go @@ -12,6 +12,7 @@ import ( "time" clickyprocess "github.com/flanksource/clicky/process" + "github.com/flanksource/gavel/sdk/status" "github.com/flanksource/telltale/pkg/datadir" "github.com/flanksource/telltale/pkg/tracing/process" ) @@ -32,6 +33,16 @@ type GroupSample struct { Origin Origin `json:"origin" filter:"none"` Self Usage `json:"self" filter:"none"` Total Usage `json:"total" filter:"none"` + // Gavel is the progress and slots a gavel group's process publishes, and + // GavelError why it could not be read. + Gavel *status.Status `json:"gavel,omitempty" filter:"none" pretty:"hide"` + GavelError string `json:"gavelError,omitempty" filter:"none" pretty:"hide"` + // SkipAncestry is the group's rule's: its tasks claim their processes' + // groups by pid before ancestry does. + SkipAncestry bool `json:"skipAncestry,omitempty" filter:"none" pretty:"hide"` + // Task is what a row WithGavelTasks adds shows: a task group's progress, + // or one running task. It is never recorded. + Task *GavelTask `json:"-" filter:"none" pretty:"hide"` } // Frame is every group shown at one tick, parents before their children, @@ -43,6 +54,8 @@ type Frame struct { // Overhead is what reading the frame cost, when read live. Overhead *Overhead `json:"overhead,omitempty"` Groups []GroupSample `json:"groups"` + // Slots are the gavel slot pools the gavel groups hold or wait for. + Slots []SlotPool `json:"slots,omitempty"` } // ProcessSample is one process at one tick: who runs it, the group it is in, @@ -77,7 +90,9 @@ func (p ProcessSample) holds(query string) bool { // TopOptions choose what a Top reads and shows. type TopOptions struct { - Catalog Catalog + Catalog Catalog + RootPID int + SkipDescriptors bool // All shows, and reads the disk and descriptors of, the processes in no // tool's group too. All bool @@ -86,6 +101,9 @@ type TopOptions struct { // Net reads each process's network bytes with nettop, every Interval. Net bool Interval time.Duration + // GavelCache is where gavel processes publish their status; defaults to + // gavel's user cache directory. + GavelCache string } // Top reads the host's process groups at each Tick. @@ -100,9 +118,14 @@ type Top struct { self int overhead overheadReader host hostReader + hogs hogTracker net *NetMonitor tick int64 processes []ProcessSample + gavel *gavelStatuses + observed []process.Observed + held map[int][]clickyprocess.Descriptor + io map[int]clickyprocess.Process } // NewTop is a Top over sampler, refusing a group no rule names; with Net it @@ -113,7 +136,15 @@ func NewTop(ctx context.Context, sampler *process.Sampler, options TopOptions) ( return nil, fmt.Errorf("group %q is no rule of the catalog", name) } } - top := &Top{sampler: sampler, options: options, rates: NewRates(), contexts: newContexts(), brew: BrewPrefixes(), self: os.Getpid()} + if options.GavelCache == "" { + cache, err := status.CacheDir() + if err != nil { + return nil, fmt.Errorf("gavel status directory: %w", err) + } + options.GavelCache = cache + } + top := &Top{sampler: sampler, options: options, rates: NewRates(), contexts: newContexts(), brew: BrewPrefixes(), self: os.Getpid(), + gavel: newGavelStatuses(options.GavelCache)} if options.Net { monitor, err := StartNetMonitor(ctx, options.Interval) if err != nil { @@ -140,12 +171,13 @@ func (t *Top) Close() { if t.net != nil { t.net.Close() } + t.gavel.close() } // Tick lists the host, sorts it into groups and reads what each uses. func (t *Top) collect(ctx context.Context) (Frame, error) { started := time.Now() - listing, at, err := t.sampler.Observe(ctx, 0) + listing, at, err := t.sampler.Observe(ctx, t.options.RootPID) if err != nil { return Frame{}, err } @@ -162,10 +194,12 @@ func (t *Top) collect(ctx context.Context) (Frame, error) { if err != nil { return Frame{}, err } + t.observed, t.held = listing, held host, err := t.host.read(ctx) if err != nil { return Frame{}, err } + t.hogs.observe(readings, host, at) totals := Aggregate(classified, readings) contexts := t.contexts.of(ctx, classified, held) t.tick++ @@ -186,14 +220,33 @@ func (t *Top) collect(ctx context.Context) (Frame, error) { return Frame{}, err } frame := Frame{SampledAt: at, Tick: t.tick, Host: &host, Overhead: &overhead} + var gavelPIDs []int + for _, group := range classified { + if group.Rule.Name == gavelRule { + gavelPIDs = append(gavelPIDs, group.Anchor.PID) + } + } + gavels := t.gavel.of(gavelPIDs) + var published []status.Status for _, group := range classified { - frame.Groups = append(frame.Groups, GroupSample{ + sample := GroupSample{ SampledAt: at, Tick: t.tick, Key: group.Key, ParentKey: group.ParentKey, Name: group.Rule.Name, Kind: group.Rule.Kind, Target: group.Target, PID: group.Anchor.PID, Command: group.Anchor.Command, Context: contexts[group.Key], Origin: group.Origin, - Self: totals[group.Key].Self, Total: totals[group.Key].Total, - }) + Self: totals[group.Key].Self, Total: totals[group.Key].Total, SkipAncestry: group.Rule.SkipAncestry, + } + if reading, ok := gavels[group.Anchor.PID]; ok && group.Rule.Name == gavelRule { + sample.Gavel = reading.Status + if reading.Err != nil { + sample.GavelError = reading.Err.Error() + } + if reading.Status != nil { + published = append(published, *reading.Status) + } + } + frame.Groups = append(frame.Groups, sample) } + frame.Slots = SlotPools(published) return frame, nil } @@ -201,13 +254,17 @@ func (t *Top) collect(ctx context.Context) (Frame, error) { func (t *Top) Processes(filter ProcessFilter) []ProcessSample { t.mu.Lock() defer t.mu.Unlock() + return FilterProcesses(t.processes, filter) +} + +func FilterProcesses(processes []ProcessSample, filter ProcessFilter) []ProcessSample { picked := map[int]bool{} if filter.PID != 0 { picked[filter.PID] = true // Parents may be listed after their children: grow the subtree until it holds. for grew := true; grew; { grew = false - for _, p := range t.processes { + for _, p := range processes { if picked[p.PPID] && !picked[p.PID] && p.PID != p.PPID { picked[p.PID], grew = true, true } @@ -215,7 +272,7 @@ func (t *Top) Processes(filter ProcessFilter) []ProcessSample { } } var result []ProcessSample - for _, p := range t.processes { + for _, p := range processes { switch { case filter.PID != 0 && !picked[p.PID]: case filter.GroupKey != "" && p.GroupKey != filter.GroupKey: @@ -247,6 +304,13 @@ func (t *Top) read(ctx context.Context, classified []Group, at time.Time) (map[s } } t.rates.Forget(alive) + if len(readings) == 0 { + t.io = nil + return readings, nil, nil + } + if err := readMemory(ctx, classified, readings); err != nil { + return nil, nil, err + } pids := make([]int, 0, len(measured)) for _, p := range measured { pids = append(pids, p.PID) @@ -255,12 +319,21 @@ func (t *Top) read(ctx context.Context, classified []Group, at time.Time) (map[s if err := snapshot.PopulateIO(ctx, pids); err != nil { return nil, nil, err } - descriptors, err := clickyprocess.Descriptors(ctx, pids...) - if err != nil { - return nil, nil, fmt.Errorf("read sockets: %w", err) + t.io = make(map[int]clickyprocess.Process, len(pids)) + for _, p := range snapshot.All() { + t.io[p.PID] = p + } + var descriptors map[int][]clickyprocess.Descriptor + if !t.options.SkipDescriptors && len(pids) > 0 { + var err error + descriptors, err = clickyprocess.Descriptors(ctx, pids...) + if err != nil { + return nil, nil, fmt.Errorf("read sockets: %w", err) + } } var network map[int]NetBytes // nil leaves every process's network unknown if t.net != nil { + var err error if network, err = t.net.Counters(); err != nil { return nil, nil, err } diff --git a/pkg/tracing/groups/usage.go b/pkg/tracing/groups/usage.go index 45ab43b..aa15d6b 100644 --- a/pkg/tracing/groups/usage.go +++ b/pkg/tracing/groups/usage.go @@ -1,6 +1,7 @@ package groups import ( + "strings" "time" ) @@ -15,8 +16,11 @@ type PerSecond struct { // Reading is one process's use at one tick. type Reading struct { - CPUPercent *float64 - RSSBytes uint64 + CPUPercent *float64 + RSSBytes uint64 + SwapBytes, CompressedBytes *uint64 + Hogs Hogs + MemoryError string PerSecond Sockets, Connections *int } @@ -24,9 +28,13 @@ type Reading struct { // Usage is what a set of processes use at one tick: the sums of what is // known of them, nil where nothing is. type Usage struct { - Processes int `json:"processes"` - CPUPercent *float64 `json:"cpuPercent,omitempty" pretty:"label=CPU %"` - RSSBytes uint64 `json:"rssBytes" pretty:"label=RSS,type=bytes"` + Processes int `json:"processes"` + CPUPercent *float64 `json:"cpuPercent,omitempty" pretty:"label=CPU %"` + RSSBytes uint64 `json:"rssBytes" pretty:"label=RSS,type=bytes"` + SwapBytes *uint64 `json:"swapBytes,omitempty" pretty:"label=Swap,type=bytes"` + CompressedBytes *uint64 `json:"compressedBytes,omitempty" pretty:"label=Compressed,type=bytes"` + Hogs Hogs `json:"hogs,omitempty"` + MemoryError string `json:"memoryError,omitempty"` PerSecond Sockets *int `json:"sockets,omitempty"` Connections *int `json:"connections,omitempty"` @@ -36,6 +44,10 @@ func (u *Usage) add(r Reading) { u.Processes++ u.CPUPercent = sum(u.CPUPercent, r.CPUPercent) u.RSSBytes += r.RSSBytes + u.SwapBytes = sumBytes(u.SwapBytes, r.SwapBytes) + u.CompressedBytes = sumBytes(u.CompressedBytes, r.CompressedBytes) + u.Hogs = u.Hogs.merge(r.Hogs) + u.MemoryError = strings.TrimSpace(u.MemoryError + " " + r.MemoryError) u.PerSecond = u.PerSecond.add(r.PerSecond) u.Sockets, u.Connections = sumInt(u.Sockets, r.Sockets), sumInt(u.Connections, r.Connections) } @@ -44,6 +56,10 @@ func (u *Usage) merge(other Usage) { u.Processes += other.Processes u.CPUPercent = sum(u.CPUPercent, other.CPUPercent) u.RSSBytes += other.RSSBytes + u.SwapBytes = sumBytes(u.SwapBytes, other.SwapBytes) + u.CompressedBytes = sumBytes(u.CompressedBytes, other.CompressedBytes) + u.Hogs = u.Hogs.merge(other.Hogs) + u.MemoryError = strings.TrimSpace(u.MemoryError + " " + other.MemoryError) u.PerSecond = u.PerSecond.add(other.PerSecond) u.Sockets, u.Connections = sumInt(u.Sockets, other.Sockets), sumInt(u.Connections, other.Connections) } @@ -77,6 +93,17 @@ func sumInt(a, b *int) *int { return &total } +func sumBytes(a, b *uint64) *uint64 { + if a == nil { + return clone(b) + } + if b == nil { + return a + } + total := *a + *b + return &total +} + func clone[T any](value *T) *T { if value == nil { return nil diff --git a/pkg/tracing/http/export.go b/pkg/tracing/http/export.go index 1d8168e..d283208 100644 --- a/pkg/tracing/http/export.go +++ b/pkg/tracing/http/export.go @@ -92,8 +92,10 @@ func Summarize(rows iter.Seq[Exchange]) (map[string]any, error) { methods, statuses, hosts := map[string]int{}, map[string]int{}, map[string]bool{} requests := []map[string]any{} entries, errors := 0, 0 + durationMs := 0.0 for exchange := range rows { entries++ + durationMs += exchange.DurationMs host, path, err := splitURL(exchange.URL) if err != nil { return nil, err @@ -111,6 +113,7 @@ func Summarize(rows iter.Seq[Exchange]) (map[string]any, error) { return map[string]any{ "entries": entries, "errors": errors, "hosts": slices.Sorted(maps.Keys(hosts)), "methods": methods, "statuses": statuses, "requests": requests, + "durationMs": durationMs, }, nil } diff --git a/pkg/tracing/http/pretty.go b/pkg/tracing/http/pretty.go new file mode 100644 index 0000000..7736f3a --- /dev/null +++ b/pkg/tracing/http/pretty.go @@ -0,0 +1,22 @@ +package http + +import ( + "github.com/flanksource/clicky/api" + "github.com/flanksource/commons/har/harpretty" +) + +func (e Exchange) Pretty() api.Text { + t := harpretty.Entry(e.Entry).Pretty() + if e.Error != "" { + t = t.Space().Append(e.Error, "text-red-500") + } + return t +} + +func (e Exchange) PrettyFull() api.Textable { + t := e.Pretty() + if detail := harpretty.Entry(e.Entry).RowDetail(); detail != nil { + t = t.NewLine().Add(detail) + } + return t +} diff --git a/pkg/tracing/jfr/pretty.go b/pkg/tracing/jfr/pretty.go new file mode 100644 index 0000000..36cf850 --- /dev/null +++ b/pkg/tracing/jfr/pretty.go @@ -0,0 +1,18 @@ +package jfr + +import ( + "strings" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing" +) + +func (r Sample) Pretty() api.Text { + return clicky.Text(r.Event, "text-blue-500 font-bold").Space().Append(r.Thread, "text-muted"). + Space().Add(tracing.PrettySampleValue(r.Value, r.Unit)).Space().Append(r.Frame, "font-mono") +} + +func (r Sample) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.CodeBlock("text", strings.ReplaceAll(r.Stack, ";", "\n"))) +} diff --git a/pkg/tracing/jfr/summary.go b/pkg/tracing/jfr/summary.go new file mode 100644 index 0000000..a623e44 --- /dev/null +++ b/pkg/tracing/jfr/summary.go @@ -0,0 +1,30 @@ +package jfr + +import ( + "github.com/flanksource/telltale/pkg/tracing" + "iter" +) + +func (b builtin) Summarize(rows iter.Seq[Sample]) (map[string]any, error) { + return b.native.Summarize(rows) +} + +func (profiler[P]) Summarize(rows iter.Seq[Sample]) (map[string]any, error) { + events := map[string]int64{} + totals := map[string]int64{} + functions := map[string]map[string]int64{} + for row := range rows { + events[row.Event] += row.Samples + totals[row.Event+"/"+row.Unit] += row.Value + key := row.Event + "/" + row.Unit + if functions[key] == nil { + functions[key] = map[string]int64{} + } + functions[key][row.Frame] += row.Value + } + ranked := map[string]any{} + for key, values := range functions { + ranked[key] = tracing.RankedValues(values) + } + return map[string]any{"events": events, "totals": totals, "functions": ranked}, nil +} diff --git a/pkg/tracing/kinds.go b/pkg/tracing/kinds.go index 5f791e2..d860146 100644 --- a/pkg/tracing/kinds.go +++ b/pkg/tracing/kinds.go @@ -16,12 +16,18 @@ import ( ) // KindInfo describes one registered kind. +type KindResult struct { + Name string `json:"name"` + Columns []query.ColumnDef `json:"columns"` +} + type KindInfo struct { Name string `json:"name"` Title string `json:"title"` Capabilities Capabilities `json:"capabilities"` Params *rpc.OpenAPISchema `json:"params"` Columns []query.ColumnDef `json:"columns"` + Results []KindResult `json:"results,omitempty"` // ExportFormats are the formats a window of the kind's records downloads // in, NDJSON first. ExportFormats []ExportFormat `json:"exportFormats"` @@ -31,10 +37,11 @@ type KindInfo struct { type Kinds struct { mu sync.RWMutex plugins map[string]TracePlugin + results map[string]TracePlugin } func NewKinds() *Kinds { - return &Kinds{plugins: map[string]TracePlugin{}} + return &Kinds{plugins: map[string]TracePlugin{}, results: map[string]TracePlugin{}} } // RegisterKind serves plugin as kind name, refusing a plugin whose params or @@ -63,10 +70,28 @@ func (k *Kinds) RegisterKind(name string, plugin TracePlugin) error { } k.mu.Lock() defer k.mu.Unlock() - if _, ok := k.plugins[name]; ok { + if k.plugins[name] != nil || k.results[name] != nil { return fmt.Errorf("trace kind %q is already registered", name) } + seen := map[string]bool{name: true} + for _, table := range plugin.ResultTables() { + if err := recordstore.ValidateKind(table.Name); err != nil { + return err + } + storage := name + "_" + table.Name + if seen[storage] || k.results[storage] != nil || k.plugins[storage] != nil { + return fmt.Errorf("result table %s already registered", storage) + } + seen[storage] = true + if _, err := table.plugin.Schema(storage); err != nil { + return err + } + } plugin.setKind(name) + for _, table := range plugin.ResultTables() { + table.plugin.setKind(name + "_" + table.Name) + k.results[name+"_"+table.Name] = table.plugin + } k.plugins[name] = plugin return nil } @@ -76,6 +101,9 @@ func (k *Kinds) Get(name string) (TracePlugin, bool) { k.mu.RLock() defer k.mu.RUnlock() plugin, ok := k.plugins[name] + if !ok { + plugin, ok = k.results[name] + } return plugin, ok } @@ -98,6 +126,13 @@ func (k *Kinds) List() ([]KindInfo, error) { Name: name, Title: plugin.Title(), Capabilities: plugin.Capabilities(), Params: params, Columns: schema.Columns, ExportFormats: plugin.ExportFormats(), }) + for _, table := range plugin.ResultTables() { + schema, err := table.plugin.Schema(name + "_" + table.Name) + if err != nil { + return nil, err + } + infos[len(infos)-1].Results = append(infos[len(infos)-1].Results, KindResult{Name: table.Name, Columns: schema.Columns}) + } } return infos, nil } diff --git a/pkg/tracing/kinds_spec_test.go b/pkg/tracing/kinds_spec_test.go index 784fe21..14e713e 100644 --- a/pkg/tracing/kinds_spec_test.go +++ b/pkg/tracing/kinds_spec_test.go @@ -66,6 +66,20 @@ func (labeller) Handle(ctx dbcontext.Context, p labelParams, records tracing.Emi } var _ = Describe("Kinds", func() { + It("advertises named results under one capture and refuses table name collisions", func() { + kinds := tracing.NewKinds() + plugin := tickPlugin().WithResults(tracing.NewResultTable("metrics", ticker{}.Schema())) + Expect(kinds.RegisterKind("ticks", plugin)).To(Succeed()) + infos, err := kinds.List() + Expect(err).NotTo(HaveOccurred()) + Expect(infos).To(HaveLen(1)) + Expect(infos[0].Results).To(ConsistOf(HaveField("Name", "metrics"))) + Expect(kinds.RegisterKind("ticks_metrics", tickPlugin())).To(MatchError(ContainSubstring("already registered"))) + duplicate := tickPlugin().WithResults(tracing.NewResultTable("metrics", ticker{}.Schema()), tracing.NewResultTable("metrics", ticker{}.Schema())) + Expect(kinds.RegisterKind("duplicate", duplicate)).To(MatchError(ContainSubstring("already registered"))) + _, exists := kinds.Get("duplicate_metrics") + Expect(exists).To(BeFalse()) + }) It("passes the resolved seam into the handler's typed params", func() { got := make(chan target.Target, 1) plugin := tracing.NewHandler[targetParams, tick](targetRecorder{got: got}, tracing.Capabilities{Live: true}, target.Self) diff --git a/pkg/tracing/llm/pretty.go b/pkg/tracing/llm/pretty.go new file mode 100644 index 0000000..4d767ca --- /dev/null +++ b/pkg/tracing/llm/pretty.go @@ -0,0 +1,33 @@ +package llm + +import ( + "fmt" + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +func (r LLMCall) Pretty() api.Text { + t := clicky.Text(r.Phase, "text-blue-500 font-bold").Space().Append(r.Model, "font-bold"). + Space().Append(r.Backend, "text-muted").Space(). + Append("tokens in ", "text-muted").Add(api.HumanNumber(int64(r.Usage.InputTokens), "text-blue-500")). + Append(" out ", "text-muted").Add(api.HumanNumber(int64(r.Usage.OutputTokens), "text-blue-500")). + Space().Append(fmt.Sprintf("$%.6f", r.Cost), "text-yellow-500").Space(). + Add(api.Human(time.Duration(r.DurationMs*float64(time.Millisecond)), "text-muted")) + if r.Error != "" { + t = t.Space().Append(r.Error, "text-red-500") + } + return t +} + +func (r LLMCall) PrettyFull() api.Textable { + t := r.Pretty() + if r.Prompt != "" { + t = t.NewLine().Append("Prompt", "font-bold").NewLine().Add(clicky.CodeBlock("text", r.Prompt)) + } + if r.Response != "" { + t = t.NewLine().Append("Response", "font-bold").NewLine().Add(clicky.CodeBlock("json", r.Response)) + } + return t +} diff --git a/pkg/tracing/llm/summary.go b/pkg/tracing/llm/summary.go new file mode 100644 index 0000000..4b847d1 --- /dev/null +++ b/pkg/tracing/llm/summary.go @@ -0,0 +1,22 @@ +package llm + +import "iter" + +func (capture) Summarize(rows iter.Seq[LLMCall]) (map[string]any, error) { + count, failed := 0, 0 + duration, cost := 0.0, 0.0 + models := map[string]int{} + input, output := 0, 0 + for row := range rows { + count++ + duration += row.DurationMs + cost += row.Cost + input += row.Usage.InputTokens + output += row.Usage.OutputTokens + models[row.Model]++ + if row.Error != "" { + failed++ + } + } + return map[string]any{"calls": count, "failures": failed, "durationMs": duration, "cost": cost, "models": models, "inputTokens": input, "outputTokens": output}, nil +} diff --git a/pkg/tracing/logs/pretty.go b/pkg/tracing/logs/pretty.go new file mode 100644 index 0000000..f1ad09b --- /dev/null +++ b/pkg/tracing/logs/pretty.go @@ -0,0 +1,19 @@ +package logs + +import ( + "strings" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing" +) + +func (r Log) Pretty() api.Text { + return clicky.Text(r.FirstObserved.Format("15:04:05.000"), "text-muted").Space(). + Append(strings.ToUpper(r.Severity), tracing.SeverityStyle(r.Severity)). + Space().Append(r.Logger, "text-blue-500").Space().Append(r.Message) +} + +func (r Log) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.Map(r.Labels)).NewLine().Add(clicky.Map(r.Resource)) +} diff --git a/pkg/tracing/logs/summary.go b/pkg/tracing/logs/summary.go new file mode 100644 index 0000000..b48ffab --- /dev/null +++ b/pkg/tracing/logs/summary.go @@ -0,0 +1,11 @@ +package logs + +import "iter" + +func (capture) Summarize(rows iter.Seq[Log]) (map[string]any, error) { + levels := map[string]int{} + for row := range rows { + levels[row.Severity]++ + } + return map[string]any{"levels": levels}, nil +} diff --git a/pkg/tracing/plugin.go b/pkg/tracing/plugin.go index 1ed7167..a950068 100644 --- a/pkg/tracing/plugin.go +++ b/pkg/tracing/plugin.go @@ -138,6 +138,7 @@ type TracePlugin interface { summarize(ctx context.Context, store scanner, ref TraceRef) (map[string]any, error) recordType() reflect.Type jsonFields() []string + ResultTables() []ResultTable } // openOptions are what a session gives the capture it opens. @@ -152,6 +153,7 @@ type openOptions struct { // Handler is a TraceHandler as a TracePlugin, with the processing its records // get before they are stored. type Handler[P, R any] struct { + tables []ResultTable handler TraceHandler[P, R] capabilities Capabilities defaults *P @@ -415,7 +417,15 @@ func (h *Handler[P, R]) ValidateParams(params json.RawMessage) error { } func (h *Handler[P, R]) register(registry *recordresults.Registry, kind string) error { - return recordresults.RegisterResultType(registry, h.resultType(kind)) + if err := recordresults.RegisterResultType(registry, h.resultType(kind)); err != nil { + return err + } + for _, table := range h.tables { + if err := table.plugin.register(registry, kind+"_"+table.Name); err != nil { + return err + } + } + return nil } // open decodes params and prepares the handler's capture into a new source, @@ -438,6 +448,7 @@ func (h *Handler[P, R]) open(ctx dbcontext.Context, options openOptions) (*sourc } } ctx = ctx.WithValue(streamKey{}, options.stream) + ctx = ctx.WithValue(captureBackendKey{}, options.store) captureCtx, release := ctx, func() error { return nil } if preparer, ok := h.handler.(Preparer[P, R]); ok { prepared, prepareRelease, err := preparer.Prepare(ctx, params, emitter) diff --git a/pkg/tracing/presentation.go b/pkg/tracing/presentation.go new file mode 100644 index 0000000..4f8dd82 --- /dev/null +++ b/pkg/tracing/presentation.go @@ -0,0 +1,106 @@ +package tracing + +import ( + "bytes" + "encoding/json" + "fmt" + "reflect" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/commons-db/query" +) + +type RecordPresentation struct { + Summary api.Text + Detail api.Textable +} + +// Present restores typed presentation from the processed, stored record. Schema +// fields provide the standard presentation for kinds without Pretty methods. +func (k *Kinds) Present(kind string, row query.Row) (RecordPresentation, error) { + plugin, ok := k.Get(kind) + if !ok { + return RecordPresentation{}, fmt.Errorf("%w: %s", ErrUnknownKind, kind) + } + encoded, err := json.Marshal(row) + if err != nil { + return RecordPresentation{}, err + } + var stored query.Row + decoder := json.NewDecoder(bytes.NewReader(encoded)) + decoder.UseNumber() + if err := decoder.Decode(&stored); err != nil { + return RecordPresentation{}, err + } + jsonAsText(stored, plugin.jsonFields()) + encoded, err = json.Marshal(stored) + if err != nil { + return RecordPresentation{}, err + } + if presenter, ok := plugin.(interface { + presentRecord([]byte) (RecordPresentation, bool, error) + }); ok { + if presentation, handled, err := presenter.presentRecord(encoded); handled || err != nil { + return presentation, err + } + } + value := reflect.New(plugin.recordType()) + if err := json.Unmarshal(encoded, value.Interface()); err != nil { + return RecordPresentation{}, fmt.Errorf("present %s: %w", kind, err) + } + if value.Elem().Kind() == reflect.Pointer { + value = value.Elem() + } + var summary api.Text + if pretty, ok := value.Interface().(api.Pretty); ok { + summary = pretty.Pretty() + } else if table, ok := value.Interface().(api.TableProvider); ok { + summary = prettyRecordFields(table.Columns(), table.Row()) + } else { + schema, err := plugin.Schema(kind) + if err != nil { + return RecordPresentation{}, err + } + columns := []api.ColumnDef{} + for _, column := range schema.Columns { + if column.Hidden || column.Type == query.ColumnTypeJSON || row[column.Name] == nil { + continue + } + columns = append(columns, api.Column(column.Name).Label(column.Label).Build()) + } + summary = prettyRecordFields(columns, row) + } + native, err := json.MarshalIndent(row, "", " ") + if err != nil { + return RecordPresentation{}, err + } + var detail api.Textable = clicky.CodeBlock("json", string(native)) + if full, ok := value.Interface().(api.PrettyFull); ok { + detail = full.PrettyFull() + } + return RecordPresentation{Summary: summary, Detail: detail}, nil +} + +func prettyRecordFields(columns []api.ColumnDef, row map[string]any) api.Text { + text := api.Text{} + count := 0 + for _, column := range columns { + if column.Hidden || column.DefaultHidden || row[column.Name] == nil { + continue + } + if count > 0 { + text = text.Append(" · ", "muted") + } + value, ok := row[column.Name].(api.Textable) + if !ok { + value = clicky.Human(row[column.Name]) + } + text = text.Append(column.DisplayLabel()+"=", "muted").Add(value) + count++ + if count == 4 { + break + } + } + return text +} diff --git a/pkg/tracing/presentation_handler.go b/pkg/tracing/presentation_handler.go new file mode 100644 index 0000000..c9e80c0 --- /dev/null +++ b/pkg/tracing/presentation_handler.go @@ -0,0 +1,19 @@ +package tracing + +import "encoding/json" + +type recordPresenter[R any] interface { + Present(R) RecordPresentation +} + +func (h *Handler[P, R]) presentRecord(data []byte) (RecordPresentation, bool, error) { + presenter, ok := h.handler.(recordPresenter[R]) + if !ok { + return RecordPresentation{}, false, nil + } + var record R + if err := json.Unmarshal(data, &record); err != nil { + return RecordPresentation{}, true, err + } + return presenter.Present(record), true, nil +} diff --git a/pkg/tracing/presentation_test.go b/pkg/tracing/presentation_test.go new file mode 100644 index 0000000..90c26c4 --- /dev/null +++ b/pkg/tracing/presentation_test.go @@ -0,0 +1,42 @@ +package tracing_test + +import ( + dbcontext "github.com/flanksource/commons-db/context" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons-db/recordstore/recordresults" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/target" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +type bodyRecord struct { + Nested struct { + Body string `json:"body"` + } `json:"nested"` +} +type bodyPresenter struct{} + +func (bodyPresenter) Params() struct{} { return struct{}{} } +func (bodyPresenter) Schema() recordresults.ResultType[bodyRecord] { + return recordresults.ResultType[bodyRecord]{Title: "JSON bodies"} +} +func (bodyPresenter) Handle(dbcontext.Context, struct{}, tracing.Emitter[bodyRecord], tracing.Records[bodyRecord]) error { + return nil +} + +var _ = Describe("record presentation", func() { + It("ranks profile functions by weight and breaks ties by name", func() { + Expect(tracing.RankedValues(map[string]int64{"z": 1, "b": 4, "a": 4})).To(Equal([]map[string]any{{"function": "a", "value": int64(4)}, {"function": "b", "value": int64(4)}, {"function": "z", "value": int64(1)}})) + }) + It("restores nested JSON text without changing the native stored payload", func() { + kinds := tracing.NewKinds() + plugin := tracing.NewHandler[struct{}, bodyRecord](bodyPresenter{}, tracing.Capabilities{Live: true}, target.Self).WithJSONProcessor("nested.body") + Expect(kinds.RegisterKind("json_body", plugin)).To(Succeed()) + row := query.Row{"nested": map[string]any{"body": map[string]any{"answer": int64(7)}}} + presentation, err := kinds.Present("json_body", row) + Expect(err).NotTo(HaveOccurred()) + Expect(presentation.Detail).NotTo(BeNil()) + Expect(row).To(Equal(query.Row{"nested": map[string]any{"body": map[string]any{"answer": int64(7)}}})) + }) +}) diff --git a/pkg/tracing/pretty.go b/pkg/tracing/pretty.go new file mode 100644 index 0000000..4825b11 --- /dev/null +++ b/pkg/tracing/pretty.go @@ -0,0 +1,32 @@ +package tracing + +import ( + "strings" + "time" + + "github.com/flanksource/clicky/api" +) + +func SeverityStyle(level string) string { + switch strings.ToLower(level) { + case "error", "fatal", "panic", "failed", "down": + return "text-red-500 font-bold" + case "warn", "warning": + return "text-yellow-500 font-bold" + case "ok", "up", "info": + return "text-green-500" + default: + return "text-muted" + } +} + +func PrettySampleValue(value int64, unit string) api.Text { + switch unit { + case "bytes": + return api.HumanizeBytes(value).Styles("text-blue-500") + case "ns", "nanoseconds": + return api.Human(time.Duration(value), "text-yellow-500") + default: + return api.HumanNumber(value, "text-blue-500").Space().Append(unit, "text-muted") + } +} diff --git a/pkg/tracing/prometheus/pretty.go b/pkg/tracing/prometheus/pretty.go new file mode 100644 index 0000000..8a63d7d --- /dev/null +++ b/pkg/tracing/prometheus/pretty.go @@ -0,0 +1,21 @@ +package prometheus + +import ( + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing" +) + +func (r Scrape) Pretty() api.Text { + t := clicky.Text(r.Health, tracing.SeverityStyle(r.Health)).Space().Append(r.Endpoint, "text-blue-500"). + Space().Add(api.HumanNumber(r.Samples)).Append(" samples", "text-muted").Space(). + Add(api.Human(time.Duration(r.DurationMs*float64(time.Millisecond)), "text-muted")) + if r.Error != "" { + t = t.Space().Append(r.Error, "text-red-500") + } + return t +} + +func (r Scrape) PrettyFull() api.Textable { return r.Pretty() } diff --git a/pkg/tracing/prometheus/summary.go b/pkg/tracing/prometheus/summary.go new file mode 100644 index 0000000..8e0b85d --- /dev/null +++ b/pkg/tracing/prometheus/summary.go @@ -0,0 +1,25 @@ +package prometheus + +import "iter" + +func (kind) Summarize(rows iter.Seq[Scrape]) (map[string]any, error) { + latest := map[string]Scrape{} + for row := range rows { + if previous, ok := latest[row.Endpoint]; !ok || row.TakenAt.After(previous.TakenAt) { + latest[row.Endpoint] = row + } + } + up, down := 0, 0 + var samples int64 + duration := 0.0 + for _, row := range latest { + if row.Health == "up" { + up++ + } else { + down++ + } + samples += row.Samples + duration += row.DurationMs + } + return map[string]any{"targets": len(latest), "up": up, "down": down, "latestSamples": samples, "latestDurationMs": duration}, nil +} diff --git a/pkg/tracing/prometheus/summary_test.go b/pkg/tracing/prometheus/summary_test.go new file mode 100644 index 0000000..afb2220 --- /dev/null +++ b/pkg/tracing/prometheus/summary_test.go @@ -0,0 +1,17 @@ +package prometheus + +import ( + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "slices" + "time" +) + +var _ = Describe("scrape monitor summary", func() { + It("counts latest target health instead of summing historical gauges", func() { + rows := []Scrape{{Endpoint: "a", TakenAt: time.Unix(1, 0), Health: "down", Samples: 3}, {Endpoint: "a", TakenAt: time.Unix(2, 0), Health: "up", Samples: 7}, {Endpoint: "b", TakenAt: time.Unix(2, 0), Health: "down", Samples: 2}} + summary, err := (kind{}).Summarize(slices.Values(rows)) + Expect(err).NotTo(HaveOccurred()) + Expect(summary).To(Equal(map[string]any{"targets": 2, "up": 1, "down": 1, "latestSamples": int64(9), "latestDurationMs": float64(0)})) + }) +}) diff --git a/pkg/tracing/ranking.go b/pkg/tracing/ranking.go new file mode 100644 index 0000000..b531aba --- /dev/null +++ b/pkg/tracing/ranking.go @@ -0,0 +1,25 @@ +package tracing + +import ( + "cmp" + "slices" +) + +// RankedValues returns the largest weights within a single sample unit. +func RankedValues(values map[string]int64) []map[string]any { + names := make([]string, 0, len(values)) + for name := range values { + names = append(names, name) + } + slices.SortFunc(names, func(a, b string) int { + if order := cmp.Compare(values[b], values[a]); order != 0 { + return order + } + return cmp.Compare(a, b) + }) + rows := make([]map[string]any, 0, min(len(names), 10)) + for _, name := range names[:min(len(names), 10)] { + rows = append(rows, map[string]any{"function": name, "value": values[name]}) + } + return rows +} diff --git a/pkg/tracing/results.go b/pkg/tracing/results.go new file mode 100644 index 0000000..440e80d --- /dev/null +++ b/pkg/tracing/results.go @@ -0,0 +1,101 @@ +package tracing + +import ( + "context" + "fmt" + dbcontext "github.com/flanksource/commons-db/context" + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/commons-db/recordstore/recordresults" +) + +type captureBackendKey struct{} + +// CaptureBackend is the atomic writer of a capture with named result tables. +func CaptureBackend(ctx context.Context) (recordstore.BatchAppender, error) { + backend, ok := ctx.Value(captureBackendKey{}).(recordstore.BatchAppender) + if !ok { + return nil, fmt.Errorf("capture backend does not support atomic batches") + } + return backend, nil +} + +// ResultTable is a named, read-only result of a capture. It is advertised with +// its owning kind, and registered with the same query/export infrastructure. +type ResultTable struct { + Name string `json:"name"` + plugin TracePlugin +} + +type resultParams struct{} + +func (resultParams) Validate() error { + return fmt.Errorf("result tables cannot be started independently") +} + +type resultReader[R any] struct{ result recordresults.ResultType[R] } + +func (r resultReader[R]) Params() resultParams { return resultParams{} } +func (r resultReader[R]) Schema() recordresults.ResultType[R] { return r.result } +func (resultReader[R]) Handle(dbcontext.Context, resultParams, Emitter[R], Records[R]) error { + return fmt.Errorf("result tables cannot be started independently") +} + +func NewResultTable[R any](name string, result recordresults.ResultType[R]) ResultTable { + return ResultTable{Name: name, plugin: NewHandler[resultParams, R](resultReader[R]{result: result}, Capabilities{Live: true}, "self")} +} + +func (h *Handler[P, R]) WithResults(tables ...ResultTable) *Handler[P, R] { + h.tables = append(h.tables, tables...) + return h +} +func (h *Handler[P, R]) ResultTables() []ResultTable { return h.tables } + +// ResultOf identifies the capture and named result behind a storage kind. +func (k *Kinds) ResultOf(storage string) (kind, result string) { + k.mu.RLock() + defer k.mu.RUnlock() + for name, plugin := range k.plugins { + for _, table := range plugin.ResultTables() { + if storage == name+"_"+table.Name { + return name, table.Name + } + } + } + return storage, "" +} + +// CaptureRefs returns the primary and all named results of a capture. +func (k *Kinds) CaptureRefs(ref TraceRef) []TraceRef { + k.mu.RLock() + defer k.mu.RUnlock() + refs := []TraceRef{ref} + if plugin := k.plugins[ref.Kind]; plugin != nil { + for _, table := range plugin.ResultTables() { + refs = append(refs, TraceRef{Kind: ref.Kind + "_" + table.Name, Stream: ref.Stream + "-" + table.Name}) + } + } + return refs +} + +// Schemas includes each kind's primary table and its named result tables. +func (k *Kinds) Schemas() ([]recordstore.KindSchema, error) { + k.mu.RLock() + defer k.mu.RUnlock() + schemas := []recordstore.KindSchema{} + for _, name := range k.names() { + plugin := k.plugins[name] + schema, err := plugin.Schema(name) + if err != nil { + return nil, err + } + schemas = append(schemas, schema) + for _, result := range plugin.ResultTables() { + schema, err := result.plugin.Schema(name + "_" + result.Name) + if err != nil { + return nil, err + } + schemas = append(schemas, schema) + } + } + return schemas, nil +} diff --git a/pkg/tracing/spans/pretty.go b/pkg/tracing/spans/pretty.go new file mode 100644 index 0000000..fed50ea --- /dev/null +++ b/pkg/tracing/spans/pretty.go @@ -0,0 +1,27 @@ +package spans + +import ( + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing" + telltale "github.com/flanksource/telltale/sdk" +) + +type spanPresentation struct{ telltale.Span } + +func (r spanPresentation) Pretty() api.Text { + return clicky.Text(r.Service, "text-blue-500 font-bold").Space().Append(r.Operation, "font-bold"). + Space().Append(r.Status, tracing.SeverityStyle(r.Status)).Space(). + Add(api.Human(time.Duration(r.DurationMs*float64(time.Millisecond)), "text-muted")).Space().Append(r.TraceID, "text-muted") +} + +func (r spanPresentation) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.Map(r.Attributes)).NewLine().Add(clicky.Map(r.Resource)) +} + +func (capture) Present(record telltale.Span) tracing.RecordPresentation { + r := spanPresentation{record} + return tracing.RecordPresentation{Summary: r.Pretty(), Detail: r.PrettyFull()} +} diff --git a/pkg/tracing/spans/summary.go b/pkg/tracing/spans/summary.go new file mode 100644 index 0000000..6164915 --- /dev/null +++ b/pkg/tracing/spans/summary.go @@ -0,0 +1,18 @@ +package spans + +import ( + telltale "github.com/flanksource/telltale/sdk" + "iter" +) + +func (capture) Summarize(rows iter.Seq[telltale.Span]) (map[string]any, error) { + statuses := map[string]int{} + traces := map[string]bool{} + duration := 0.0 + for row := range rows { + statuses[row.Status]++ + traces[row.TraceID] = true + duration += row.DurationMs + } + return map[string]any{"traces": len(traces), "statuses": statuses, "durationMs": duration}, nil +} diff --git a/pkg/tracing/sql/pretty.go b/pkg/tracing/sql/pretty.go new file mode 100644 index 0000000..1c58ce3 --- /dev/null +++ b/pkg/tracing/sql/pretty.go @@ -0,0 +1,29 @@ +package sql + +import ( + "errors" + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + dbgorm "github.com/flanksource/commons-db/gorm" + "github.com/flanksource/commons/properties" +) + +func (r StatementRow) Pretty() api.Text { + duration := time.Duration(r.DurationMs * float64(time.Millisecond)) + threshold := properties.Duration(time.Second, "log.db.slowThreshold") + trace := dbgorm.SQLTrace{SQL: r.SQL, Duration: duration, Rows: r.Rows, Slow: threshold > 0 && duration > threshold} + if r.Error != "" { + trace.Err = errors.New(r.Error) + } + return trace.Pretty() +} + +func (r StatementRow) PrettyFull() api.Textable { + t := r.Pretty().NewLine().Add(clicky.CodeBlock("sql", r.SQL)) + if len(r.Args) > 0 { + t = t.NewLine().Add(clicky.Map(map[string]any{"Arguments": r.Args})) + } + return t +} diff --git a/pkg/tracing/sqlserver/history/pretty.go b/pkg/tracing/sqlserver/history/pretty.go new file mode 100644 index 0000000..f9ac04e --- /dev/null +++ b/pkg/tracing/sqlserver/history/pretty.go @@ -0,0 +1,21 @@ +package history + +import ( + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing/sqlserver/deadlocks" +) + +func (r Row) Pretty() api.Text { + shape := deadlocks.Shape(r.Shape) + return clicky.Text("deadlock", "text-red-500 font-bold").Space().Append(r.Database, "text-blue-500"). + Space().Append(shape.Label(), shape.Style()).Space().Append(participantsLabel(r.Participants, r.Victims)+" participants", "text-muted"). + Space().Add(victimStatement(r)) +} + +func (r Row) PrettyFull() api.Textable { + if r.DecodeError != "" { + return r.Pretty().NewLine().Add(clicky.CodeBlock("xml", r.XML)) + } + return r.Graph().Pretty() +} diff --git a/pkg/tracing/sqlserver/plancache/pretty.go b/pkg/tracing/sqlserver/plancache/pretty.go new file mode 100644 index 0000000..873bd6e --- /dev/null +++ b/pkg/tracing/sqlserver/plancache/pretty.go @@ -0,0 +1,32 @@ +package plancache + +import ( + "fmt" + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/commons-db/query/sqltext" +) + +func (r Sample) Pretty() api.Text { + duration := time.Duration(r.AvgElapsedMs * float64(time.Millisecond)) + t := clicky.Text(r.Database, "text-blue-500").Space().Append(fmt.Sprintf("%d executions", r.Executions), "text-muted"). + Space().Append("avg ", "text-muted").Add(api.Human(duration, sqltext.DurationStyle(duration))).Space().Append(r.SQL, "font-mono max-w-[200ch]") + if r.Recompiled { + t = t.Space().Append("recompiled", "text-yellow-500") + } + if r.Evicted { + t = t.Space().Append("evicted", "text-yellow-500") + } + return t +} + +func (r Sample) PrettyFull() api.Textable { + return r.Pretty().NewLine().Add(clicky.CodeBlock("sql", r.SQL)).NewLine().Add(clicky.Map(map[string]any{ + "CPU": api.Human(time.Duration(r.CPUMs * float64(time.Millisecond))), + "Elapsed": api.Human(time.Duration(r.ElapsedMs * float64(time.Millisecond))), + "Reads": r.LogicalReads, "Physical reads": r.PhysicalReads, "Writes": r.Writes, "Rows": r.Rows, + "Plan": r.PlanHandle, "Query hash": r.QueryHash, "Size": api.HumanizeBytes(r.SizeBytes), + })) +} diff --git a/pkg/tracing/sqlserver/xesession/pretty.go b/pkg/tracing/sqlserver/xesession/pretty.go new file mode 100644 index 0000000..287f965 --- /dev/null +++ b/pkg/tracing/sqlserver/xesession/pretty.go @@ -0,0 +1,25 @@ +package xesession + +import ( + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/tracing/sqlserver/xetrace" +) + +func (r EventRow) Pretty() api.Text { + return xetrace.StreamLine(r.Event(), xetrace.StreamLineOptions{ShowDatabase: true}) +} + +func (r EventRow) PrettyFull() api.Textable { + t := xetrace.StreamLine(r.Event(), xetrace.StreamLineOptions{ShowDatabase: true, Full: true}) + if r.SQL != "" { + t = t.NewLine().Add(clicky.CodeBlock("sql", r.SQL)) + } + if r.Deadlock != nil { + t = t.NewLine().Add(r.Deadlock.Pretty()) + } + for _, child := range r.Children { + t = t.NewLine().Add(child.PrettyFull()) + } + return t +} diff --git a/pkg/tracing/stacks/pretty.go b/pkg/tracing/stacks/pretty.go new file mode 100644 index 0000000..809db29 --- /dev/null +++ b/pkg/tracing/stacks/pretty.go @@ -0,0 +1,45 @@ +package stacks + +import ( + "fmt" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +func (r Stack) Pretty() api.Text { + t := clicky.Text(fmt.Sprintf("pid %d", r.PID), "text-muted") + if r.GoroutineID > 0 { + t = t.Space().Append(fmt.Sprintf("goroutine %d", r.GoroutineID), "text-blue-500") + } + t = t.Space().Append(r.State, "text-yellow-500") + if len(r.Frames) > 0 { + t = t.Space().Append(r.Frames[0].Func, "font-mono") + } + if r.Error != "" { + t = t.Space().Append(r.Error, "text-red-500") + } + return t +} + +func (r Stack) PrettyFull() api.Textable { + t := r.Pretty() + for _, frame := range r.Frames { + t = t.NewLine().Add(frame.Pretty()) + } + if r.Raw != "" { + t = t.NewLine().Add(clicky.CodeBlock("text", r.Raw)) + } + return t +} + +func (f Frame) Pretty() api.Text { + t := clicky.Text(f.Func, "font-mono") + if f.File != "" { + t = t.Space().Append(f.File, "text-muted") + if f.Line > 0 { + t = t.Append(fmt.Sprintf(":%d", f.Line), "text-muted") + } + } + return t +} diff --git a/pkg/tracing/terminal/pretty.go b/pkg/tracing/terminal/pretty.go new file mode 100644 index 0000000..e994c1b --- /dev/null +++ b/pkg/tracing/terminal/pretty.go @@ -0,0 +1,39 @@ +package terminal + +import ( + "fmt" + "strings" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +func (r Event) Pretty() api.Text { + t := clicky.Text(fmt.Sprintf("+%.3fs", r.Offset), "text-muted") + switch r.Kind { + case KindResize: + t = t.Space().Append("resize", "text-blue-500").Space().Append(fmt.Sprintf("%d × %d", r.Width, r.Height)) + case KindExit: + t = t.Space().Append(r.Command, "font-mono").Space().Append("exit", "text-muted") + if r.ExitCode != nil { + style := "text-green-500" + if *r.ExitCode != 0 { + style = "text-red-500" + } + t = t.Space().Append(*r.ExitCode, style) + } + case KindOutput, KindSnapshot: + t = t.Space().Append(r.Kind, "text-blue-500").Space().Append(strings.Join(strings.Fields(r.Data), " "), "max-w-[120ch]") + } + if r.Truncated { + t = t.Space().Append("(truncated)", "text-yellow-500") + } + return t +} + +func (r Event) PrettyFull() api.Textable { + if r.Data != "" { + return r.Pretty().NewLine().Append(r.Data) + } + return r.Pretty() +} From a35185f0b7abef7de66a9e1f74028d0723ffa30c Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:06:01 +0200 Subject: [PATCH 07/89] refactor(traces): consolidate process trace kinds into processcapture and compact run IDs Merge process_tree and process_samples into a single process kind backed by processcapture, and remove process_groups. Process traces now store identities, metrics and facets in separate streams, and follow reads sequences through the backend instead of the notification stream. Run IDs become a short hostname plus a compact UTC timestamp, and prune orders runs by manifest start time. BREAKING CHANGE: the process_tree, process_samples and process_groups kinds are removed in favour of process. Run IDs use the form , and collision suffixes use _N instead of -N. Recordings made with the old kinds need the build that produced them to be read. --- pkg/traces/builtin.go | 35 +-- pkg/traces/capture_internal_ginkgo_test.go | 3 +- pkg/traces/host.go | 21 +- pkg/traces/host_ginkgo_test.go | 27 ++- pkg/traces/params_schema_spec_test.go | 4 +- pkg/traces/pretty_records_test.go | 106 +++++++++ pkg/traces/pretty_variants_test.go | 48 ++++ pkg/traces/process.go | 40 ++-- pkg/traces/process_ginkgo_test.go | 14 +- pkg/traces/process_readings.go | 43 +++- pkg/traces/prune.go | 51 ++++- pkg/traces/read/feed.go | 230 ++++++++++++++++++++ pkg/traces/read/feed_follow.go | 42 ++++ pkg/traces/read/feed_test.go | 85 ++++++++ pkg/traces/read/follow.go | 112 +++------- pkg/traces/read/follow_backpressure_test.go | 58 +++++ pkg/traces/read/lifecycle_test.go | 12 +- pkg/traces/read/order.go | 47 ++++ pkg/traces/read/presentation.go | 23 ++ pkg/traces/read/read.go | 41 +++- pkg/traces/read/read_test.go | 1 + pkg/traces/read/refs.go | 36 +++ pkg/traces/read/request.go | 2 +- pkg/traces/read/rows.go | 3 + pkg/traces/read/runs.go | 67 ++++++ pkg/traces/registry_test.go | 13 +- pkg/traces/runid.go | 44 ++++ pkg/traces/runid_test.go | 23 ++ 28 files changed, 1041 insertions(+), 190 deletions(-) create mode 100644 pkg/traces/pretty_records_test.go create mode 100644 pkg/traces/pretty_variants_test.go create mode 100644 pkg/traces/read/feed.go create mode 100644 pkg/traces/read/feed_follow.go create mode 100644 pkg/traces/read/feed_test.go create mode 100644 pkg/traces/read/follow_backpressure_test.go create mode 100644 pkg/traces/read/order.go create mode 100644 pkg/traces/read/presentation.go create mode 100644 pkg/traces/read/refs.go create mode 100644 pkg/traces/read/runs.go create mode 100644 pkg/traces/runid.go create mode 100644 pkg/traces/runid_test.go diff --git a/pkg/traces/builtin.go b/pkg/traces/builtin.go index 09b924d..266fa45 100644 --- a/pkg/traces/builtin.go +++ b/pkg/traces/builtin.go @@ -6,10 +6,9 @@ import ( "github.com/flanksource/telltale/pkg/tracing" "github.com/flanksource/telltale/pkg/tracing/goprof" - "github.com/flanksource/telltale/pkg/tracing/groups" "github.com/flanksource/telltale/pkg/tracing/httpproxy" "github.com/flanksource/telltale/pkg/tracing/pgproxy" - "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" tracesql "github.com/flanksource/telltale/pkg/tracing/sql" "github.com/flanksource/telltale/pkg/tracing/stacks" "github.com/flanksource/telltale/pkg/tracing/target" @@ -23,41 +22,17 @@ import ( func init() { for _, registration := range []Registration{ { - Name: process.TreeKind, Title: "Process tree", Seams: []target.Seam{target.Process}, DefaultSeam: target.Process, - Summary: "Record every process of a tree as it starts, changes and exits", - Description: "Follows the process tree under its root: telltale's own tree, which holds the command, or the process --pid attaches to. " + - "Every run records this tree already; arm it again for another interval or to read each process's environment.", + Name: processcapture.Kind, Title: "Processes", Seams: []target.Seam{target.Process, target.Host}, DefaultSeam: target.Process, + Summary: "Record process identities, resource changes and numeric metrics", + Description: "Follows a process tree or the host. Stores startup metadata, environment and grouping tags once, files and receiving sockets as added/removed events, and numeric metrics in a separate wide table. TCP connections are unique peers per process, with inferred or unknown direction.", Examples: []Example{ {Args: "--environment-prefixes AWS_ -- make deploy", Says: "record the tree with each process's AWS_ variables"}, {Args: "--pid 1234 --duration 30s", Says: "follow process 1234's tree for 30 seconds"}, }, New: func(deps KindDeps) tracing.TracePlugin { - return process.NewTreeKind(deps.Sampler, process.TreeKindOptions{Dumpers: deps.Dumpers}) + return processcapture.NewKind(deps.Sampler, processcapture.KindOptions{Dumpers: deps.Dumpers}) }, }, - { - Name: process.SamplesKind, Title: "Process samples", Seams: []target.Seam{target.Process}, DefaultSeam: target.Process, - Summary: "Sample the CPU, memory, disk IO and open descriptors of every process of a tree", - Description: "Samples each process under its root at every interval: telltale's own tree, which holds the command, or the process --pid attaches to. " + - "Facets add each process's open files, sockets, listening ports or connections, read with lsof.", - Examples: []Example{ - {Args: "--facets ports,connections -- ./server", Says: "sample the server and the ports and connections it opens"}, - {Args: "--seam process --pid 1234 --interval 250ms --duration 1m", Says: "sample process 1234's tree four times a second for a minute"}, - }, - New: func(deps KindDeps) tracing.TracePlugin { return process.NewSamplesKind(deps.Sampler) }, - }, - { - Name: groups.Kind, Title: "Process groups", Seams: []target.Seam{target.Host}, DefaultSeam: target.Host, - Summary: "Record the CPU, memory, disk, sockets and network of each tool's processes on the host", - Description: "Sorts every process on the host into the tool that owns it — claude, codex, cmux, gavel, go test, vitest, agent-browser, chrome and more — " + - "as a tree of groups, each with its working directory, checkout, agent session and cmux workspace, and records what each group and those under it use. " + - "Rules come from the built-in catalog and groups.yaml in ./.telltale, else the global config dir. Network bytes are read with nettop on darwin only when asked for, as it costs over a core.", - Examples: []Example{ - {Args: "--duration 10m", Says: "record every tool's groups for ten minutes"}, - {Args: "--groups claude,vitest --net", Says: "record claude sessions and vitest runs with their network bytes"}, - }, - New: func(deps KindDeps) tracing.TracePlugin { return groups.NewKind(deps.Sampler) }, - }, { Name: stacks.Kind, Title: "Stacks", Seams: []target.Seam{target.Process, target.Agent, target.Self}, DefaultSeam: target.Process, Checkpoint: stacks.CheckpointParams{Reason: "interval"}, diff --git a/pkg/traces/capture_internal_ginkgo_test.go b/pkg/traces/capture_internal_ginkgo_test.go index ae890af..f2f0f1e 100644 --- a/pkg/traces/capture_internal_ginkgo_test.go +++ b/pkg/traces/capture_internal_ginkgo_test.go @@ -11,6 +11,7 @@ import ( "github.com/flanksource/commons-db/query" "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" "github.com/flanksource/telltale/pkg/tracing/target" ) @@ -19,7 +20,7 @@ var _ = Describe("marking a capture whose session failed", func() { host, err := Open(OpenOptions{DataDir: GinkgoT().TempDir(), RunID: RunID(time.Now())}) Expect(err).ToNot(HaveOccurred()) DeferCleanup(func() { Expect(host.Close(context.Background())).To(Succeed()) }) - capture, err := host.startWith(process.SamplesKind, process.SampleParams{SampleOptions: process.SampleOptions{Options: process.Options{Interval: time.Hour.String()}}, Target: target.Target{PID: os.Getpid()}}) + capture, err := host.startWith(processcapture.Kind, processcapture.Params{Options: processcapture.Options{Options: process.Options{Interval: time.Hour.String()}}, Target: target.Target{PID: os.Getpid()}}) Expect(err).ToNot(HaveOccurred()) cause := errors.New("read disk I/O for process 5675: operation not permitted") _, _ = capture.managed.Abort(cause) diff --git a/pkg/traces/host.go b/pkg/traces/host.go index e4dc480..c7620a1 100644 --- a/pkg/traces/host.go +++ b/pkg/traces/host.go @@ -59,23 +59,12 @@ type Host struct { releases []func(context.Context) error } -// RunPrefix and RunTimestampLayout name a run: run-, filesystem -// safe (no colons) and chronologically sortable. A run's trace store and its -// per-run snapshot (snapshots.SavePerRun) are both named so. -const ( - RunPrefix = "run-" - RunTimestampLayout = "2006-01-02T15-04-05Z" -) - -// RunID names a run started at started. -func RunID(started time.Time) string { - return RunPrefix + started.UTC().Format(RunTimestampLayout) -} - // OpenOptions name the run a Host is opened for. type OpenOptions struct { DataDir string RunID string + // MaxCaptures bounds simultaneous captures; zero uses the registry default. + MaxCaptures int // Connections answer the connection references its captures name, such // as sql_xevent's connection, before any connections table; nil answers // none. @@ -118,7 +107,7 @@ func runConnections(base *store.Store, dir string, defined []crd.Connection) (*s } // Open creates the run's store under DataDir/traces. A RunID already -// taken by an earlier run in the same second gets a -2, -3, … suffix, so a +// taken by an earlier run in the same second gets a _2, _3, … suffix, so a // run never writes into another's store; RunID reports the name used. func Open(options OpenOptions) (*Host, error) { if options.DataDir == "" || options.RunID == "" { @@ -148,7 +137,7 @@ func Open(options OpenOptions) (*Host, error) { } runtime.PollEvery = pollEvery runtime.Sessions = query.NewSessionRegistry(query.RegistryOptions{ - MaxDuration: maxDuration, BeforeRead: runtime.Results.Registry.BeforeRead, + MaxSessions: options.MaxCaptures, MaxDuration: maxDuration, BeforeRead: runtime.Results.Registry.BeforeRead, }) ctx := dbcontext.New() if connections != nil { @@ -237,7 +226,7 @@ func claimRunDir(root, runID string) (string, string, error) { for i := 1; i < 1000; i++ { name := runID if i > 1 { - name = fmt.Sprintf("%s-%d", runID, i) + name = fmt.Sprintf("%s_%d", runID, i) } dir := filepath.Join(root, name) err := os.Mkdir(dir, 0o755) diff --git a/pkg/traces/host_ginkgo_test.go b/pkg/traces/host_ginkgo_test.go index d4965ec..cccf257 100644 --- a/pkg/traces/host_ginkgo_test.go +++ b/pkg/traces/host_ginkgo_test.go @@ -9,6 +9,7 @@ import ( "net/url" "os" "path/filepath" + "strings" "time" . "github.com/onsi/ginkgo/v2" @@ -36,6 +37,14 @@ func getThrough(capture *traces.Capture, target string) { } var _ = Describe("trace host", func() { + It("names a run with at most nine hostname characters and a compact UTC timestamp", func() { + hostname, err := os.Hostname() + Expect(err).NotTo(HaveOccurred()) + prefix := strings.ReplaceAll(strings.Split(hostname, ".")[0], "-", "") + prefix = prefix[:min(9, len(prefix))] + started := time.Date(2026, 10, 15, 11, 30, 0, 0, time.FixedZone("example", 2*60*60)) + Expect(traces.RunID(started)).To(Equal(prefix + "20261015T093000Z")) + }) var server *httptest.Server BeforeEach(func() { server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { @@ -54,7 +63,7 @@ var _ = Describe("trace host", func() { Expect(err).ToNot(HaveOccurred()) DeferCleanup(func() { Expect(second.Close(context.Background())).To(Succeed()) }) - Expect([]string{first.RunID(), second.RunID()}).To(Equal([]string{"run-2026-10-15T09-30-00Z", "run-2026-10-15T09-30-00Z-2"})) + Expect([]string{first.RunID(), second.RunID()}).To(Equal([]string{runID, runID + "_2"})) Expect(first.Dir()).To(Equal(filepath.Join(dataDir, "traces", first.RunID()))) }) @@ -131,6 +140,22 @@ var _ = Describe("trace host", func() { }) var _ = Describe("Prune", func() { + It("retains the newest start times across hostnames and old IDs", func() { + dataDir := GinkgoT().TempDir() + runs := []string{"zworker20261105T000000Z", "run-2026-11-06T00-00-00Z", "aworker20261107T000000Z"} + for index, run := range runs { + dir := traces.StoreDir(dataDir, run) + Expect(os.MkdirAll(dir, 0o755)).To(Succeed()) + data, err := json.Marshal(map[string]any{"startedAt": time.Date(2026, 11, 5+index, 0, 0, 0, 0, time.UTC)}) + Expect(err).NotTo(HaveOccurred()) + Expect(os.WriteFile(filepath.Join(dir, traces.ManifestFile), data, 0o600)).To(Succeed()) + } + Expect(traces.Prune(dataDir, 2)).To(Succeed()) + Expect(os.Stat(traces.StoreDir(dataDir, runs[0]))).Error().To(MatchError(os.ErrNotExist)) + for _, id := range runs[1:] { + Expect(os.Stat(traces.StoreDir(dataDir, id))).Error().NotTo(HaveOccurred()) + } + }) It("keeps only the newest runs' stores", func() { dataDir := GinkgoT().TempDir() runs := []string{"run-2026-10-13T00-00-00Z", "run-2026-10-14T00-00-00Z", "run-2026-10-15T00-00-00Z"} diff --git a/pkg/traces/params_schema_spec_test.go b/pkg/traces/params_schema_spec_test.go index 1f4c643..5df2e3e 100644 --- a/pkg/traces/params_schema_spec_test.go +++ b/pkg/traces/params_schema_spec_test.go @@ -15,8 +15,8 @@ import ( // kinds split their params into Options and a target; added are the // properties each kind gained since, which may differ from the golden. var schemaGoldens = map[string][]string{ - "exec": nil, "goprof": nil, "jvm_jfr": nil, "llm": nil, "process_groups": nil, "process_samples": nil, - "process_tree": nil, "prometheus": nil, "spans": nil, "sql_deadlock": nil, "sql_plancache": nil, + "exec": nil, "goprof": nil, "jvm_jfr": nil, "llm": nil, + "prometheus": nil, "spans": nil, "sql_deadlock": nil, "sql_plancache": nil, "sql_xevent": nil, "stacks": nil, "terminal": nil, "http": {"listen", "export"}, "sql": {"listen", "export"}, diff --git a/pkg/traces/pretty_records_test.go b/pkg/traces/pretty_records_test.go new file mode 100644 index 0000000..2bd411a --- /dev/null +++ b/pkg/traces/pretty_records_test.go @@ -0,0 +1,106 @@ +package traces_test + +import ( + "encoding/json" + "slices" + "time" + + "github.com/flanksource/clicky/api" + clickyexec "github.com/flanksource/clicky/exec" + dbgorm "github.com/flanksource/commons-db/gorm" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons/har" + "github.com/flanksource/commons/har/harpretty" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/tracing/sqlserver/xetrace" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("styled trace records", func() { + type example struct { + kind string + row query.Row + contains []string + } + examples := []example{ + {"http", query.Row{"request": map[string]any{"method": "GET", "url": "https://example.test/orders"}, "response": map[string]any{"status": 200}, "time": 12.0}, []string{"GET", "https://example.test/orders", "200"}}, + {"sql", query.Row{"sql": "SELECT id FROM orders", "durationMs": 1500.0, "rows": 3}, []string{"SLOW SQL", "[1500ms]", "[rows:3]", "SELECT id FROM orders"}}, + {"sql_xevent", query.Row{"name": "sql_statement_completed", "sql": "SELECT id FROM orders", "durationMs": 12.0, "rowCount": 3}, []string{"SELECT id FROM orders", "rows"}}, + {"sql_plancache", query.Row{"sql": "SELECT id FROM orders", "executions": 4, "avgElapsedMs": 12.0, "database": "checkout"}, []string{"SELECT id FROM orders", "4", "checkout"}}, + {"sql_deadlock", query.Row{"database": "checkout", "victims": 1, "participants": 2, "victimStatement": "UPDATE orders SET total = 1"}, []string{"deadlock", "checkout", "UPDATE orders"}}, + {"exec", query.Row{"name": "git", "args": []string{"status"}, "exitCode": 0}, []string{"git", "status"}}, + {"terminal", query.Row{"kind": "r", "width": 120, "height": 40}, []string{"resize", "120", "40"}}, + {"llm", query.Row{"phase": "response", "model": "example-model", "usage": map[string]any{"inputTokens": 12, "outputTokens": 3}, "cost": 0.004}, []string{"response", "example-model", "12", "3", "$0.004"}}, + {"logs", query.Row{"severity": "error", "logger": "checkout", "message": "payment declined"}, []string{"ERROR", "checkout", "payment declined"}}, + {"spans", query.Row{"service": "checkout", "operation": "orders.submit", "status": "error", "durationMs": 12.0}, []string{"checkout", "orders.submit", "error"}}, + {"goprof", query.Row{"pid": 123, "profile": "heap", "value": 4096, "unit": "bytes", "frames": []map[string]any{{"func": "checkout.allocate"}}}, []string{"123", "heap", "checkout.allocate"}}, + {"stacks", query.Row{"pid": 123, "goroutineId": 7, "state": "IO wait", "frames": []map[string]any{{"func": "checkout.read"}}}, []string{"123", "7", "IO wait", "checkout.read"}}, + {"jvm_jfr", query.Row{"event": "alloc", "thread": "worker", "frame": "Checkout.allocate", "value": 4096, "unit": "bytes"}, []string{"alloc", "worker", "Checkout.allocate"}}, + {"prometheus", query.Row{"endpoint": "http://localhost/metrics", "health": "up", "samples": 42, "durationMs": 12.0}, []string{"http://localhost/metrics", "up", "42"}}, + {"query", query.Row{"profile": "request-rate", "provider": "prometheus", "row": map[string]any{"value": 7}}, []string{"request-rate", "prometheus", "7"}}, + {"process", query.Row{"pid": 123, "name": "checkout", "command": "checkout serve"}, []string{"123", "checkout", "serve"}}, + {"process_metrics", query.Row{"entity": "123@started", "cpuPercent": 12.5, "rssBytes": 4096}, []string{"123@started", "12.5", "CPU"}}, + {"process_facets", query.Row{"process": "123@started", "facet": "files", "operation": "open", "entity": "/orders.db"}, []string{"123@started", "files", "open", "/orders.db"}}, + } + + DescribeTableSubtree("presents native fields with a typed formatter", func(e example) { + It("keeps meaningful content and semantic styles", func() { + kinds, err := traces.Kinds() + Expect(err).NotTo(HaveOccurred()) + before, err := json.Marshal(e.row) + Expect(err).NotTo(HaveOccurred()) + p, err := kinds.Present(e.kind, e.row) + Expect(err).NotTo(HaveOccurred()) + for _, content := range e.contains { + Expect(p.Summary.String()).To(ContainSubstring(content)) + } + Expect(p.Summary.HTML()).To(ContainSubstring("color:")) + after, err := json.Marshal(e.row) + Expect(err).NotTo(HaveOccurred()) + Expect(after).To(Equal(before)) + }) + }, func() []TableEntry { + entries := []TableEntry{} + for _, e := range examples { + entries = append(entries, Entry(e.kind, e)) + } + return entries + }()) + + It("covers every registered built-in record and named result", func() { + kinds, err := traces.Kinds() + Expect(err).NotTo(HaveOccurred()) + infos, err := kinds.List() + Expect(err).NotTo(HaveOccurred()) + var actual, expected []string + for _, e := range examples { + actual = append(actual, e.kind) + } + for _, info := range infos { + if slices.Contains(registrationNames(), info.Name) { + expected = append(expected, info.Name) + plugin, ok := kinds.Get(info.Name) + Expect(ok).To(BeTrue()) + for _, table := range plugin.ResultTables() { + expected = append(expected, info.Name+"_"+table.Name) + } + } + } + Expect(actual).To(ConsistOf(expected)) + }) + + DescribeTable("reuses established formatting without changing its styles", func(kind string, row query.Row, expected api.Text) { + kinds, err := traces.Kinds() + Expect(err).NotTo(HaveOccurred()) + p, err := kinds.Present(kind, row) + Expect(err).NotTo(HaveOccurred()) + Expect(p.Summary).To(Equal(expected)) + }, + Entry("HTTP HAR", "http", query.Row{"request": map[string]any{"method": "GET", "url": "https://example.test"}, "response": map[string]any{"status": 200}, "time": 12.0}, harpretty.Entry(har.Entry{Request: har.Request{Method: "GET", URL: "https://example.test"}, Response: har.Response{Status: 200}, Time: 12}).Pretty()), + Entry("SQL slow log", "sql", query.Row{"sql": "SELECT 1", "durationMs": 1500.0, "rows": 3}, dbgorm.SQLTrace{SQL: "SELECT 1", Duration: 1500 * time.Millisecond, Rows: 3, Slow: true}.Pretty()), + Entry("execution", "exec", query.Row{"name": "git", "args": []string{"status"}, "exitCode": 0}, clickyexec.ExecResult{Command: "git", Args: []string{"status"}, ExitCode: 0}.Pretty()), + Entry("SQL extended event", "sql_xevent", query.Row{"name": "sql_statement_completed", "sql": "SELECT 1", "durationMs": 12.0}, xetrace.StreamLine(xetrace.Event{Name: "sql_statement_completed", SQL: "SELECT 1", Duration: 12 * time.Millisecond}, xetrace.StreamLineOptions{ShowDatabase: true})), + ) +}) diff --git a/pkg/traces/pretty_variants_test.go b/pkg/traces/pretty_variants_test.go new file mode 100644 index 0000000..8957cb6 --- /dev/null +++ b/pkg/traces/pretty_variants_test.go @@ -0,0 +1,48 @@ +package traces_test + +import ( + "strings" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale/pkg/traces" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("styled trace variants", func() { + DescribeTable("preserves status and failure semantics", func(kind string, row query.Row, content, color string) { + kinds, err := traces.Kinds() + Expect(err).NotTo(HaveOccurred()) + p, err := kinds.Present(kind, row) + Expect(err).NotTo(HaveOccurred()) + Expect(strings.Join(strings.Fields(p.Summary.String()), " ")).To(ContainSubstring(content)) + Expect(strings.ToLower(p.Summary.HTML())).To(ContainSubstring(color)) + }, + Entry("HTTP success", "http", query.Row{"request": map[string]any{"method": "GET"}, "response": map[string]any{"status": 200}}, "200", "#22c55e"), + Entry("HTTP redirect", "http", query.Row{"request": map[string]any{"method": "GET"}, "response": map[string]any{"status": 302}}, "302", "#3b82f6"), + Entry("HTTP client error", "http", query.Row{"request": map[string]any{"method": "GET"}, "response": map[string]any{"status": 404}}, "404", "#eab308"), + Entry("HTTP server error", "http", query.Row{"request": map[string]any{"method": "GET"}, "response": map[string]any{"status": 503}}, "503", "#ef4444"), + Entry("HTTP transport failure", "http", query.Row{"error": "connection refused"}, "connection refused", "#ef4444"), + Entry("SQL normal", "sql", query.Row{"sql": "SELECT 1", "rows": -1, "durationMs": 2.0}, "[rows:-1]", "#3b82f6"), + Entry("SQL error", "sql", query.Row{"sql": "SELECT missing", "error": "missing table"}, "missing table", "#ef4444"), + Entry("exec error", "exec", query.Row{"name": "git", "exitCode": 1, "error": "permission denied"}, "permission denied", "#ef4444"), + Entry("terminal output", "terminal", query.Row{"kind": "o", "data": "git version\n"}, "git version", "#3b82f6"), + Entry("terminal snapshot", "terminal", query.Row{"kind": "snapshot", "data": "ready"}, "snapshot", "#3b82f6"), + Entry("terminal failed exit", "terminal", query.Row{"kind": "exit", "exitCode": 1}, "exit 1", "#ef4444"), + Entry("LLM request", "llm", query.Row{"phase": "request", "model": "example-model", "prompt": "private prompt"}, "request", "#3b82f6"), + ) + + DescribeTable("keeps expanded payloads out of the compact row", func(kind string, row query.Row, detail string) { + kinds, err := traces.Kinds() + Expect(err).NotTo(HaveOccurred()) + p, err := kinds.Present(kind, row) + Expect(err).NotTo(HaveOccurred()) + Expect(p.Summary.String()).NotTo(ContainSubstring(detail)) + Expect(p.Detail.String()).To(ContainSubstring(detail)) + }, + Entry("HTTP response body", "http", query.Row{"request": map[string]any{"method": "GET"}, "response": map[string]any{"status": 200, "content": map[string]any{"mimeType": "application/json", "text": map[string]any{"result": "recorded-response"}}}}, "recorded-response"), + Entry("execution stdout", "exec", query.Row{"name": "git", "exitCode": 0, "stdoutTail": "recorded-stdout"}, "recorded-stdout"), + Entry("LLM prompt", "llm", query.Row{"phase": "request", "model": "example-model", "prompt": "recorded-prompt"}, "recorded-prompt"), + ) +}) diff --git a/pkg/traces/process.go b/pkg/traces/process.go index fa8bbe0..1821737 100644 --- a/pkg/traces/process.go +++ b/pkg/traces/process.go @@ -10,23 +10,23 @@ import ( "github.com/flanksource/commons-db/query" "github.com/flanksource/telltale/pkg/tracing" "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" "github.com/flanksource/telltale/pkg/tracing/stacks" "github.com/flanksource/telltale/pkg/tracing/target" ) -// ProcessTrace is the run-scope capture of the process kinds over one root: -// its tree, its samples and its stacks, the streams the Processes tab reads -// through the query mount. +// ProcessTrace captures a root's identities, metrics and resource changes, +// with independent stack checkpoints. type ProcessTrace struct { host *Host interval time.Duration tree *Capture - samples *Capture stacks *Capture } // ProcessTraceOptions choose what a process trace reads. type ProcessTraceOptions struct { + Capture *Capture // RootPID is the process whose tree is traced. RootPID int // Interval is how often the tree is sampled; zero is a second. @@ -35,10 +35,9 @@ type ProcessTraceOptions struct { Tree TreeOptions } -// TreeOptions choose what the run-wide process tree reads of each process: -// the same environment params a process_tree capture takes, and the facets. +// TreeOptions choose the environment and resource facets read by the process capture. type TreeOptions struct { - // Facets arms every process_samples facet and, unless Environment narrows + // Facets arms every process facet and, unless Environment narrows // it, reads each process's whole environment onto its node, as a run // watched in a UI does. Facets bool `json:"facets,omitempty" clicky:"title=Process facets,desc=Read every process's open files sockets and environment into the process tree"` @@ -52,6 +51,7 @@ type TreeOptions struct { type ProcessRefs struct { Tree tracing.TraceRef `json:"tree"` Samples tracing.TraceRef `json:"samples"` + Facets tracing.TraceRef `json:"facets"` Stacks tracing.TraceRef `json:"stacks"` } @@ -70,26 +70,32 @@ func (h *Host) StartProcessTrace(options ProcessTraceOptions) (*ProcessTrace, er if options.Interval == 0 { options.Interval = time.Second } - root, interval := target.Target{PID: options.RootPID}, process.Options{Interval: options.Interval.String()} - tree := process.TreeParams{TreeOptions: process.TreeOptions{Options: interval}, Target: root} - samples := process.SampleParams{SampleOptions: process.SampleOptions{Options: interval}, Target: root} + params := processcapture.Params{Options: processcapture.Options{Options: process.Options{Interval: options.Interval.String()}}, Target: target.Target{PID: options.RootPID}} if options.Tree.Facets { - tree.Environment, samples.Facets = &process.EnvironmentParams{}, process.Facets + params.Environment, params.Facets = &process.EnvironmentParams{}, []string{processcapture.Files, processcapture.Sockets, "connections"} } if options.Tree.Environment != nil { - tree.Environment = options.Tree.Environment + params.Environment = options.Tree.Environment } trace := &ProcessTrace{host: h, interval: options.Interval} + if options.Capture != nil { + if options.Capture.host != h || options.Capture.Kind() != processcapture.Kind { + return nil, fmt.Errorf("process trace requires a process capture from the same host") + } + trace.tree = options.Capture + } var err error for _, start := range []struct { capture **Capture kind string params any }{ - {&trace.tree, process.TreeKind, tree}, - {&trace.samples, process.SamplesKind, samples}, + {&trace.tree, processcapture.Kind, params}, {&trace.stacks, stacks.Kind, stacks.Params{Target: target.Target{PID: options.RootPID}}}, } { + if *start.capture != nil { + continue + } if *start.capture, err = h.startWith(start.kind, start.params); err != nil { return nil, errors.Join(err, trace.Stop(context.Background())) } @@ -110,13 +116,13 @@ func (p *ProcessTrace) Interval() time.Duration { return p.interval } // Refs are the whole tree, samples and stacks streams. func (p *ProcessTrace) Refs() ProcessRefs { - return ProcessRefs{Tree: p.tree.Ref(0, 0), Samples: p.samples.Ref(0, 0), Stacks: p.stacks.Ref(0, 0)} + return ProcessRefs{Tree: p.tree.Ref(0, 0), Samples: tracing.TraceRef{Kind: processcapture.MetricsTable, Stream: p.tree.Stream() + "-metrics"}, Facets: tracing.TraceRef{Kind: processcapture.FacetsTable, Stream: p.tree.Stream() + "-facets"}, Stacks: p.stacks.Ref(0, 0)} } // Sessions are the captures' sessions. func (p *ProcessTrace) Sessions() ProcessSessions { return ProcessSessions{ - Tree: p.tree.managed.Session().ID(), Samples: p.samples.managed.Session().ID(), Stacks: p.stacks.managed.Session().ID(), + Tree: p.tree.managed.Session().ID(), Samples: p.tree.managed.Session().ID(), Stacks: p.stacks.managed.Session().ID(), } } @@ -146,7 +152,7 @@ func (p *ProcessTrace) CheckpointStacks(ctx context.Context, params stacks.Check // Stop ends the captures; their streams stay in the run's store. func (p *ProcessTrace) Stop(ctx context.Context) error { var errs []error - for _, capture := range []*Capture{p.tree, p.samples, p.stacks} { + for _, capture := range []*Capture{p.tree, p.stacks} { if capture != nil { _, err := capture.Stop(ctx) errs = append(errs, err) diff --git a/pkg/traces/process_ginkgo_test.go b/pkg/traces/process_ginkgo_test.go index 237ac3c..b409201 100644 --- a/pkg/traces/process_ginkgo_test.go +++ b/pkg/traces/process_ginkgo_test.go @@ -18,6 +18,7 @@ import ( "github.com/flanksource/telltale/pkg/traceserve" "github.com/flanksource/telltale/pkg/tracing" "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" "github.com/flanksource/telltale/pkg/tracing/stacks" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" @@ -117,7 +118,7 @@ var _ = Describe("process trace", func() { host := openHost(GinkgoT().TempDir()) trace := startTrace(host, traces.ProcessTraceOptions{RootPID: root}) refs := trace.Refs() - Expect([]string{refs.Tree.Kind, refs.Samples.Kind, refs.Stacks.Kind}).To(Equal([]string{process.TreeKind, process.SamplesKind, stacks.Kind})) + Expect([]string{refs.Tree.Kind, refs.Samples.Kind, refs.Facets.Kind, refs.Stacks.Kind}).To(Equal([]string{processcapture.Kind, processcapture.MetricsTable, processcapture.FacetsTable, stacks.Kind})) store := serveHost(host) Eventually(func() map[string]map[string]any { return byCommand(store.records(refs.Tree)) }).WithTimeout(5 * time.Second). @@ -125,7 +126,7 @@ var _ = Describe("process trace", func() { sleep := byCommand(store.records(refs.Tree))["sleep 30"] Expect(sleep).To(HaveKeyWithValue("environment", BeNil())) Eventually(func() []map[string]any { return store.records(refs.Samples) }).WithTimeout(5 * time.Second). - Should(ContainElement(HaveKeyWithValue("key", sleep["key"]))) + Should(ContainElement(HaveKeyWithValue("entity", sleep["key"]))) Expect(store.records(refs.Samples)).To(HaveEach(HaveKeyWithValue("openFiles", BeNil()))) }) @@ -137,11 +138,10 @@ var _ = Describe("process trace", func() { Eventually(func() map[string]map[string]any { return byCommand(store.records(trace.Refs().Tree)) }).WithTimeout(5 * time.Second). Should(HaveKeyWithValue("sleep 30", HaveKeyWithValue("environment", HaveKeyWithValue("TELLTALE_TRACE_PROBE", "1")))) - Eventually(func() []map[string]any { return store.records(trace.Refs().Samples) }).WithTimeout(5 * time.Second). - Should(ContainElement(And( - HaveKeyWithValue("openFiles", BeNumerically(">", 0)), HaveKeyWithValue("openFileList", Not(BeEmpty())), - HaveKeyWithValue("sockets", Not(BeNil())), HaveKeyWithValue("ports", Not(BeNil())), HaveKeyWithValue("connections", Not(BeNil())), - ))) + Eventually(func() []map[string]any { return store.records(trace.Refs().Samples) }).WithTimeout(5*time.Second). + Should(ContainElement(And(HaveKeyWithValue("openFiles", BeNumerically(">", 0)), HaveKeyWithValue("receivingSockets", Not(BeNil())), HaveKeyWithValue("connectionsUnknown", Not(BeNil()))))) + Expect(store.records(trace.Refs().Samples)).To(HaveEach(Not(HaveKey("openFileList")))) + Expect(store.records(trace.Refs().Facets)).To(ContainElement(And(HaveKeyWithValue("facet", "files"), HaveKeyWithValue("operation", "added"), HaveKey("resource")))) }) It("reads only the environment its tree options name onto each process, arming no facet", func() { diff --git a/pkg/traces/process_readings.go b/pkg/traces/process_readings.go index aceff82..ce7d86f 100644 --- a/pkg/traces/process_readings.go +++ b/pkg/traces/process_readings.go @@ -6,6 +6,7 @@ import ( "github.com/flanksource/telltale/pkg/tracing" "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" ) // ProcessMark is where a span of the run begins in its samples stream. @@ -14,7 +15,10 @@ type ProcessMark struct{ Samples int64 } // Mark commits the samples taken so far and returns where the next span // begins. func (p *ProcessTrace) Mark(ctx context.Context) (ProcessMark, error) { - seq, err := p.samples.Mark(ctx) + if err := p.CheckpointTree(ctx); err != nil { + return ProcessMark{}, err + } + seq, err := p.host.highSeq(ctx, p.Refs().Samples.Stream) return ProcessMark{Samples: seq}, err } @@ -27,27 +31,44 @@ type ProcessReadings struct { // Readings are the samples taken after mark through now, and the tree. func (p *ProcessTrace) Readings(ctx context.Context, after ProcessMark) (ProcessReadings, error) { - to, err := p.samples.Mark(ctx) + mark, err := p.Mark(ctx) if err != nil { return ProcessReadings{}, err } var readings ProcessReadings - if to > after.Samples { - if readings.Samples, err = readAll[process.Sample](ctx, p.host, p.samples.Ref(after.Samples, to)); err != nil { - return ProcessReadings{}, err - } + refs := p.Refs() + identities, err := readAll[processcapture.Identity](ctx, p.host, refs.Tree) + if err != nil { + return readings, err + } + refs.Samples.AfterSeq, refs.Samples.ToSeq = after.Samples, mark.Samples + if mark.Samples <= after.Samples { + readings.Nodes = processcapture.Nodes(identities, nil) + return readings, nil + } + metrics, err := readAll[processcapture.MetricRow](ctx, p.host, refs.Samples) + if err != nil { + return readings, err } - readings.Nodes, err = p.Nodes(ctx) - return readings, err + readings.Nodes, readings.Samples = processcapture.Nodes(identities, metrics), processcapture.Samples(identities, metrics) + return readings, nil } // Nodes are every process of the tree as last seen, after re-observing it. func (p *ProcessTrace) Nodes(ctx context.Context) ([]process.Node, error) { - to, err := p.tree.Mark(ctx) - if err != nil || to == 0 { + if err := p.CheckpointTree(ctx); err != nil { + return nil, err + } + refs := p.Refs() + identities, err := readAll[processcapture.Identity](ctx, p.host, refs.Tree) + if err != nil { + return nil, err + } + metrics, err := readAll[processcapture.MetricRow](ctx, p.host, refs.Samples) + if err != nil { return nil, err } - return readAll[process.Node](ctx, p.host, p.tree.Ref(0, to)) + return processcapture.Nodes(identities, metrics), nil } func readAll[R any](ctx context.Context, host *Host, ref tracing.TraceRef) ([]R, error) { diff --git a/pkg/traces/prune.go b/pkg/traces/prune.go index c616f79..2a72456 100644 --- a/pkg/traces/prune.go +++ b/pkg/traces/prune.go @@ -1,11 +1,14 @@ package traces import ( + "cmp" + "encoding/json" "errors" "fmt" "os" "path/filepath" "slices" + "time" "github.com/flanksource/telltale/internal/safefs" ) @@ -14,7 +17,8 @@ import ( const KeepRuns = 20 // Prune removes every run store under dataDir/traces but the newest -// keep, newest by run id (a run id is its start time). A data dir that has +// keep, newest by recorded start time. A store without a manifest uses its +// directory modification time. A data dir that has // never traced a run has nothing to prune. func Prune(dataDir string, keep int) error { if keep < 1 { @@ -28,19 +32,56 @@ func Prune(dataDir string, keep int) error { if err != nil { return fmt.Errorf("prune trace stores: %w", err) } - var runs []string + type storedRun struct { + name string + started time.Time + } + var runs []storedRun for _, entry := range entries { if entry.IsDir() { - runs = append(runs, entry.Name()) + started, err := storeStartedAt(filepath.Join(root, entry.Name()), entry) + if err != nil { + return err + } + runs = append(runs, storedRun{entry.Name(), started}) } } if len(runs) <= keep { return nil } - slices.Sort(runs) + slices.SortFunc(runs, func(a, b storedRun) int { + if compared := a.started.Compare(b.started); compared != 0 { + return compared + } + return cmp.Compare(a.name, b.name) + }) var errs []error for _, run := range runs[:len(runs)-keep] { - errs = append(errs, safefs.SafeRemove(filepath.Join(root, run), safefs.RemoveContext{AllowedRoot: root})) + errs = append(errs, safefs.SafeRemove(filepath.Join(root, run.name), safefs.RemoveContext{AllowedRoot: root})) } return errors.Join(errs...) } + +func storeStartedAt(dir string, entry os.DirEntry) (time.Time, error) { + data, err := os.ReadFile(filepath.Join(dir, ManifestFile)) + if errors.Is(err, os.ErrNotExist) { + info, err := entry.Info() + if err != nil { + return time.Time{}, err + } + return info.ModTime(), nil + } + if err != nil { + return time.Time{}, err + } + var manifest struct { + StartedAt time.Time `json:"startedAt"` + } + if err := json.Unmarshal(data, &manifest); err != nil { + return time.Time{}, fmt.Errorf("prune trace store %s: %w", dir, err) + } + if manifest.StartedAt.IsZero() { + return time.Time{}, fmt.Errorf("prune trace store %s: manifest has no start time", dir) + } + return manifest.StartedAt, nil +} diff --git a/pkg/traces/read/feed.go b/pkg/traces/read/feed.go new file mode 100644 index 0000000..4617564 --- /dev/null +++ b/pkg/traces/read/feed.go @@ -0,0 +1,230 @@ +package read + +import ( + "context" + "encoding/base64" + "encoding/json" + "fmt" + "maps" + + "github.com/flanksource/telltale/pkg/tracing" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons-db/query/profilestore" + sqlpages "github.com/flanksource/commons-db/query/providers/sqlite" +) + +type Record struct { + presentation tracing.RecordPresentation + Summary string `json:"summary"` + RunID string `json:"runId"` + Kind string `json:"kind"` + Result string `json:"result,omitempty"` + Stream string `json:"stream"` + Seq int64 `json:"seq"` + Timestamp any `json:"timestamp"` + Record query.Row `json:"record"` +} + +type FeedQuery struct { + Query + Sort string `json:"sort"` +} + +type FeedResult struct { + Rows []Record `json:"rows"` + NextCursor string `json:"nextCursor"` +} + +type feedWindow struct { + Generation string `json:"g"` + High int64 `json:"h"` + Low int64 `json:"l"` + Compactions int64 `json:"c"` +} + +type feedPosition struct { + Scope string `json:"scope"` + Windows []feedWindow `json:"windows"` + Keys json.RawMessage `json:"keys"` + State map[string][]byte `json:"state"` +} + +func recordOf(ref Ref, row query.Row) (Record, error) { + seq, ok := row["seq"].(int64) + if !ok || seq < 1 { + return Record{}, fmt.Errorf("%s/%s: invalid sequence %v", ref.Kind, ref.Stream, row["seq"]) + } + plugin, ok := ref.Runtime.Kinds.Get(ref.Kind) + if !ok { + return Record{}, fmt.Errorf("unknown kind %s", ref.Kind) + } + schema, err := plugin.Schema(ref.Kind) + if err != nil { + return Record{}, err + } + presentation, err := ref.Runtime.Kinds.Present(ref.Kind, row) + if err != nil { + return Record{}, err + } + kind, result := ref.Runtime.Kinds.ResultOf(ref.Kind) + return Record{presentation: presentation, Summary: presentation.Summary.String(), RunID: ref.RunID, Kind: kind, Result: result, Stream: ref.Stream, Seq: seq, Timestamp: row[schema.Options.TimeColumn], Record: maps.Clone(row)}, nil +} + +// FeedPage reads one frozen window over every selected capture, through each +// kind's native profile and SQLite's common ordered-page merger. +func FeedPage(ctx context.Context, refs []Ref, q FeedQuery) (FeedResult, error) { + result := FeedResult{Rows: []Record{}} + if q.Sort == "" { + q.Sort = "seq" + } + if q.Sort != "seq" && q.Sort != "timestamp" { + return result, fmt.Errorf("unknown record sort %q", q.Sort) + } + if err := q.Validate(); err != nil { + return result, err + } + if q.Where != "" || q.All { + return result, fmt.Errorf("feed pages do not support CEL or unbounded reads") + } + if len(q.Cursor) > query.MaxCursorBytes { + return result, fmt.Errorf("feed cursor exceeds maximum size") + } + if q.Limit == 0 { + q.Limit = 100 + } + if q.Limit > 500 { + return result, fmt.Errorf("record page limit exceeds 500") + } + scope, err := cursorScope(refs, q.Query) + if err != nil { + return result, err + } + scope += ":" + q.Sort + // Scope binds the exact ordered refs, so windows need no repeated stream names. + saved := feedPosition{Scope: scope, Windows: make([]feedWindow, len(refs))} + if q.Cursor != "" { + data, err := base64.RawURLEncoding.DecodeString(q.Cursor) + if err != nil { + return result, fmt.Errorf("invalid feed cursor: %w", err) + } + if err := json.Unmarshal(data, &saved); err != nil { + return result, err + } + if saved.Scope != scope || len(saved.Windows) != len(refs) { + return result, fmt.Errorf("feed cursor no longer matches selection or sort") + } + } + order := query.Order{{Column: "seq", Unique: true}} + if q.Sort == "timestamp" { + order = append(query.Order{{Column: "timestamp"}}, order...) + } + members := []sqlpages.SQLMember{} + for index, ref := range refs { + key := ref.RunID + "/" + ref.Kind + "/" + ref.Stream + meta, err := ref.Runtime.Results.Backend.Meta(ctx, ref.Stream) + if err != nil { + return result, err + } + if q.Cursor == "" { + saved.Windows[index] = feedWindow{Generation: meta.Generation, High: meta.HighSeq, Low: meta.LowSeq, Compactions: meta.Compactions} + } + window := saved.Windows[index] + if window.Generation != meta.Generation { + return result, fmt.Errorf("feed stream %s changed generation", key) + } + if window.High > 0 && (window.Low != meta.LowSeq || window.Compactions != meta.Compactions) { + return result, fmt.Errorf("feed stream %s changed retained records", key) + } + if window.High == 0 { + continue + } + ref.ToSeq = window.High + member, err := feedMember(ctx, ref, q, order) + if err != nil { + return result, err + } + members = append(members, member) + } + if len(members) == 0 { + return result, nil + } + position := query.CursorPosition{State: saved.State} + if len(saved.Keys) > 0 { + position.Keys, err = query.UnmarshalCursorKeys(saved.Keys) + if err != nil { + return result, err + } + } + request := sqlpages.SQLMergeRequest{Members: members, Read: sqlpages.SQLPageRequest{Order: order, Position: position, Page: query.PageRequest{Limit: q.Limit, Strategy: query.PagingCursor, SkipTotal: true}}} + for page, err := range sqlpages.MergeSQLPages(ctx, request) { + if err != nil { + return result, err + } + for _, row := range page.Rows { + result.Rows = append(result.Rows, row["envelope"].(Record)) + } + if page.HasMore { + saved.Keys, err = query.MarshalCursorKeys(page.NextKeys) + if err != nil { + return result, err + } + saved.State = page.State + encoded, err := json.Marshal(saved) + if err != nil { + return result, err + } + result.NextCursor = base64.RawURLEncoding.EncodeToString(encoded) + if len(result.NextCursor) > query.MaxCursorBytes { + return result, fmt.Errorf("feed cursor exceeds maximum size") + } + } + break + } + return result, nil +} + +func feedMember(ctx context.Context, ref Ref, q FeedQuery, order query.Order) (sqlpages.SQLMember, error) { + dbctx, profile, err := ref.profile(ctx, "") + if err != nil { + return sqlpages.SQLMember{}, err + } + plugin, _ := ref.Runtime.Kinds.Get(ref.Kind) + schema, err := plugin.Schema(ref.Kind) + if err != nil { + return sqlpages.SQLMember{}, err + } + profile.Order = query.Order{{Column: "seq", Unique: true}} + if q.Sort == "timestamp" { + if schema.Options.TimeColumn == "" { + return sqlpages.SQLMember{}, fmt.Errorf("kind %s has no timestamp column", ref.Kind) + } + profile.Order = append(query.Order{{Column: schema.Options.TimeColumn}}, profile.Order...) + } + params, err := q.params(ref, profile) + if err != nil { + return sqlpages.SQLMember{}, err + } + return sqlpages.SQLMember{Name: ref.RunID + "/" + ref.Kind + "/" + ref.Stream, ReadPage: func(ctx context.Context, request sqlpages.SQLPageRequest) (sqlpages.SQLPageResult, error) { + release, err := ref.Runtime.Results.Registry.BeforeExecute(ctx, []profilestore.ReadRequest{{Profile: profile, Params: params}}) + if err != nil { + return sqlpages.SQLPageResult{}, err + } + defer release() + for page, err := range query.ExecutePages(dbctx.Wrap(ctx), profile, query.PageRequest{Limit: request.Page.Limit, Strategy: query.PagingCursor, After: request.Position.Keys}, params) { + if err != nil { + return sqlpages.SQLPageResult{}, err + } + rows := make([]query.Row, 0, len(page.Rows)) + for _, row := range page.Rows { + record, err := recordOf(ref, row) + if err != nil { + return sqlpages.SQLPageResult{}, err + } + rows = append(rows, query.Row{"seq": record.Seq, "timestamp": record.Timestamp, "envelope": record}) + } + return sqlpages.SQLPageResult{Rows: rows, HasMore: page.HasMore, Total: page.Total}, nil + } + return sqlpages.SQLPageResult{}, fmt.Errorf("profile %s returned no page", profile.Name) + }}, nil +} diff --git a/pkg/traces/read/feed_follow.go b/pkg/traces/read/feed_follow.go new file mode 100644 index 0000000..68e9036 --- /dev/null +++ b/pkg/traces/read/feed_follow.go @@ -0,0 +1,42 @@ +package read + +import ( + "context" + "errors" + "github.com/flanksource/commons-db/query" + "sync" +) + +// Feed follows native sequences independently. A callback is never concurrent +// with another callback, and cancellation waits for every reader to release. +func Feed(ctx context.Context, refs []Ref, q Query, fn func(Record) error) error { + ctx, cancel := context.WithCancel(ctx) + defer cancel() + var group sync.WaitGroup + var output sync.Mutex + errs := make(chan error, len(refs)) + for _, ref := range refs { + group.Go(func() { + err := Follow(ctx, ref, q, func(row query.Row) error { + record, err := recordOf(ref, row) + if err != nil { + return err + } + output.Lock() + defer output.Unlock() + return fn(record) + }) + if err != nil && !errors.Is(err, context.Canceled) { + errs <- err + cancel() + } + }) + } + group.Wait() + close(errs) + var err error + for failure := range errs { + err = errors.Join(err, failure) + } + return err +} diff --git a/pkg/traces/read/feed_test.go b/pkg/traces/read/feed_test.go new file mode 100644 index 0000000..fb8dc20 --- /dev/null +++ b/pkg/traces/read/feed_test.go @@ -0,0 +1,85 @@ +package read_test + +import ( + "context" + "fmt" + "time" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/traces/read" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("unified record feed", func() { + BeforeEach(func() { feeding = &feed{rows: make(chan reading), ack: make(chan error, 1)} }) + It("keeps identical stream names from different runs separate across pages", func() { + host, capture := fixture(GinkgoT().TempDir(), "run-shared-stream") + appendRow(capture, reading{At: time.Now().UTC(), Label: "recorded"}) + refs := []read.Ref{ + {RunID: "first", Runtime: host.Runtime(), TraceRef: capture.Ref(0, 0)}, + {RunID: "second", Runtime: host.Runtime(), TraceRef: capture.Ref(0, 0)}, + } + first, err := read.FeedPage(context.Background(), refs, read.FeedQuery{Limit: 1}) + Expect(err).NotTo(HaveOccurred()) + Expect(first.Rows).To(HaveLen(1)) + Expect(first.Rows[0].RunID).To(Equal("first")) + second, err := read.FeedPage(context.Background(), refs, read.FeedQuery{Limit: 1, Cursor: first.NextCursor}) + Expect(err).NotTo(HaveOccurred()) + Expect(second.Rows).To(HaveLen(1)) + Expect(second.Rows[0].RunID).To(Equal("second")) + Expect(second.NextCursor).To(BeEmpty()) + }) + It("pages eighteen captures without exceeding the cursor size limit", func() { + host, capture := fixture(GinkgoT().TempDir(), "run-feed-capacity") + base := time.Now().UTC() + for range 3 { + appendRow(capture, reading{At: base, Label: "recorded"}) + } + refs := make([]read.Ref, 18) + for i := range refs { + refs[i] = read.Ref{RunID: fmt.Sprintf("demo-host20261107T205920Z_%02d", i), Runtime: host.Runtime(), TraceRef: capture.Ref(0, 0)} + } + cursor, count := "", 0 + for { + page, err := read.FeedPage(context.Background(), refs, read.FeedQuery{Sort: "timestamp", Limit: 1, Cursor: cursor}) + Expect(err).NotTo(HaveOccurred()) + Expect(len(page.NextCursor)).To(BeNumerically("<=", query.MaxCursorBytes)) + count += len(page.Rows) + cursor = page.NextCursor + if cursor == "" { + break + } + } + Expect(count).To(Equal(54)) + }) + It("pages overlapping sequences from distinct captures and freezes the read window", func() { + host, first := fixture(GinkgoT().TempDir(), "run-feed") + base := time.Now().UTC().Truncate(time.Second) + appendRow(first, reading{At: base.Add(time.Second), Label: "first", Kind: "stdout"}) + _, err := first.Stop(context.Background()) + Expect(err).NotTo(HaveOccurred()) + second, err := host.Start(traces.StartOptions{Kind: "read_static"}) + Expect(err).NotTo(HaveOccurred()) + appendRow(second, reading{At: base, Label: "second"}) + refs := []read.Ref{{RunID: host.RunID(), Runtime: host.Runtime(), TraceRef: first.Ref(0, 0)}, {RunID: host.RunID(), Runtime: host.Runtime(), TraceRef: second.Ref(0, 0)}} + page, err := read.FeedPage(context.Background(), refs, read.FeedQuery{Limit: 1}) + Expect(err).NotTo(HaveOccurred()) + Expect(page.Rows).To(HaveLen(1)) + Expect(page.Rows[0].Kind).To(Equal("read_fixture")) + Expect(page.Rows[0].Record).To(HaveKeyWithValue("kind", "stdout")) + Expect(page.NextCursor).NotTo(BeEmpty()) + appendRow(second, reading{At: base, Label: "later"}) + next, err := read.FeedPage(context.Background(), refs, read.FeedQuery{Limit: 1, Cursor: page.NextCursor}) + Expect(err).NotTo(HaveOccurred()) + Expect(next.Rows).To(HaveLen(1)) + Expect(next.Rows[0].Record).To(HaveKeyWithValue("label", "second")) + Expect(next.NextCursor).To(BeEmpty()) + sorted, err := read.FeedPage(context.Background(), refs, read.FeedQuery{Sort: "timestamp"}) + Expect(err).NotTo(HaveOccurred()) + Expect(sorted.Rows[0].Kind).To(Equal("read_static")) + _, err = read.FeedPage(context.Background(), refs, read.FeedQuery{Sort: "timestamp", Cursor: page.NextCursor}) + Expect(err).To(HaveOccurred()) + }) +}) diff --git a/pkg/traces/read/follow.go b/pkg/traces/read/follow.go index 2da66fd..bcac7e2 100644 --- a/pkg/traces/read/follow.go +++ b/pkg/traces/read/follow.go @@ -7,7 +7,6 @@ import ( "sync" "github.com/flanksource/commons-db/query" - "github.com/flanksource/commons-db/recordstore" "github.com/flanksource/telltale" "github.com/flanksource/telltale/pkg/traces" ) @@ -21,7 +20,7 @@ func Follow(ctx context.Context, ref Ref, q Query, fn func(query.Row) error) err if q.Cursor != "" { return fmt.Errorf("--follow cannot use a page cursor; use --after-seq") } - dbctx, p, err := ref.profile(ctx, "") + _, p, err := ref.profile(ctx, "") if err != nil { return err } @@ -35,92 +34,52 @@ func Follow(ctx context.Context, ref Ref, q Query, fn func(query.Row) error) err if through > 0 && max(ref.AfterSeq, q.AfterSeq) >= through { return nil } - count := 0 - // Query every notified seq through the original profile, preserving closing - // time/filter edges that query.Follow deliberately opens for rolling views. - deliver := func(seq int64) error { - if through > 0 && seq > through { - return errFollowLimit - } + count, last := 0, max(ref.AfterSeq, q.AfterSeq) + // Finish each native profile read before rendering; output holds no SQLite reader. + deliver := func(high int64) error { window := q - window.AfterSeq = seq - 1 - window.ToSeq = seq - window.All = true + window.AfterSeq, window.ToSeq = last, high + window.All, window.seqOrder = false, true + window.Limit = 500 window.Cursor = "" window.NextCursor = nil - for row, err := range Rows(ctx, []Ref{ref}, window) { - if err != nil { - return err - } + rows, err := query.CollectRows(Rows(ctx, []Ref{ref}, window)) + if err != nil { + return err + } + for _, row := range rows { if err := fn(row); err != nil { return err } + last = row["seq"].(int64) count++ if q.Limit > 0 && count >= q.Limit { return errFollowLimit } } - if through > 0 && seq >= through { - return errFollowLimit + if len(rows) < window.Limit { + last = high } return nil } - if !query.SupportsStreaming(p.Provider.Type) { - err = ref.Runtime.Results.Backend.Tail(ctx, ref.Stream, max(ref.AfterSeq, q.AfterSeq), func(seq int64, _ recordstore.Row) error { return deliver(seq) }) - } else { - followCtx, cancel := dbctx.WithCancel() - defer cancel() - // The notification stream carries every seq; filtering stays in deliver. - window := Query{AfterSeq: q.AfterSeq, ToSeq: q.ToSeq} - params, paramsErr := window.params(ref, p) - if paramsErr != nil { - return paramsErr - } - p = query.Follow(p) - p.Trace.Buffer = nil - session, startErr := query.ExecuteStream(followCtx, ref.Runtime.Sessions, p, params) - if startErr != nil { - return startErr - } - defer func() { cancel(); <-session.Done() }() - replay, live, unsubscribe := session.Subscribe() - defer unsubscribe() - var previous int64 - consume := func(event query.Event) error { - if event.Sequence != previous+1 { - return fmt.Errorf("follow subscriber lost events after %d (received %d)", previous, event.Sequence) - } - previous = event.Sequence - if event.Error != "" { - return errors.New(event.Error) - } - if event.Row == nil { - return nil - } - seq, ok := event.Row["seq"].(int64) - if !ok { - return fmt.Errorf("follow %s: expected int64 seq, got %T", ref.Kind, event.Row["seq"]) - } - return deliver(seq) - } - for _, event := range replay { - if err = consume(event); err != nil { - break - } - } - if err == nil { - for event := range live { - if err = consume(event); err != nil { - break - } - } + backend := ref.Runtime.Results.Backend + meta, err := backend.Meta(ctx, ref.Stream) + if err != nil { + return err + } + for err == nil { + high := meta.HighSeq + if through > 0 { + high = min(high, through) } - if err == nil && session.Snapshot().Error != "" { - err = errors.New(session.Snapshot().Error) + if last < high { + err = deliver(high) + continue } - if err == nil && session.Snapshot().EventCount != previous { - err = fmt.Errorf("follow subscriber lost trailing events after %d (produced %d)", previous, session.Snapshot().EventCount) + if meta.Sealed || through > 0 && last >= through { + return nil } + meta, err = backend.Wait(ctx, ref.Stream, last, meta.Generation) } if errors.Is(err, errFollowLimit) { return nil @@ -133,7 +92,7 @@ func Follow(ctx context.Context, ref Ref, q Query, fn func(query.Row) error) err // Wait follows every armed capture while Wait performs the run's usual stop, // summary and manifest write. Callbacks are serialized across captures. -func Wait(ctx context.Context, run *telltale.Run, follow bool, fn func(query.Row) error) (_ *telltale.Result, err error) { +func Wait(ctx context.Context, run *telltale.Run, follow bool, fn func(Record) error) (_ *telltale.Result, err error) { if !follow { return run.Wait() } @@ -144,7 +103,7 @@ func Wait(ctx context.Context, run *telltale.Run, follow bool, fn func(query.Row } defer func() { err = errors.Join(err, closeStore()) }() runContext := ctx - ctx, cancel := context.WithCancel(ctx) + ctx, cancel := context.WithCancel(context.WithoutCancel(ctx)) defer cancel() var group sync.WaitGroup var output sync.Mutex @@ -155,10 +114,11 @@ func Wait(ctx context.Context, run *telltale.Run, follow bool, fn func(query.Row followErr := Follow(ctx, ref, Query{}, func(row query.Row) error { output.Lock() defer output.Unlock() - if len(info.Captures) > 1 { - row["kind"] = ref.Kind + record, err := recordOf(ref, row) + if err != nil { + return err } - return fn(row) + return fn(record) }) if runContext.Err() != nil && errors.Is(followErr, runContext.Err()) { return diff --git a/pkg/traces/read/follow_backpressure_test.go b/pkg/traces/read/follow_backpressure_test.go new file mode 100644 index 0000000..a02023c --- /dev/null +++ b/pkg/traces/read/follow_backpressure_test.go @@ -0,0 +1,58 @@ +package read_test + +import ( + "context" + "fmt" + "time" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale/pkg/traces/read" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("following with a slow output", func() { + BeforeEach(func() { feeding = &feed{rows: make(chan reading), ack: make(chan error, 1)} }) + It("drains a sealed capture without dropping records while rendering is slower than reading", func() { + const count = 600 + host, capture := fixture(GinkgoT().TempDir(), "run-slow-output") + for range count { + appendRow(capture, reading{At: time.Now().UTC(), Label: "recorded"}) + } + end, err := capture.Stop(context.Background()) + Expect(err).NotTo(HaveOccurred()) + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + got := 0 + err = read.Follow(ctx, read.Ref{RunID: host.RunID(), Runtime: host.Runtime(), TraceRef: capture.Ref(0, end)}, read.Query{}, func(query.Row) error { + time.Sleep(2 * time.Millisecond) + got++ + return nil + }) + Expect(err).NotTo(HaveOccurred()) + Expect(got).To(Equal(count)) + }) + It("follows eighteen captures sharing a SQLite store without exhausting reader connections", func() { + host, capture := fixture(GinkgoT().TempDir(), "run-many-followers") + for range 3 { + appendRow(capture, reading{At: time.Now().UTC(), Label: "recorded"}) + } + end, err := capture.Stop(context.Background()) + Expect(err).NotTo(HaveOccurred()) + refs := make([]read.Ref, 18) + for i := range refs { + refs[i] = read.Ref{RunID: fmt.Sprint(i), Runtime: host.Runtime(), TraceRef: capture.Ref(0, end)} + } + ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) + defer cancel() + got := 0 + err = read.Feed(ctx, refs, read.Query{}, func(read.Record) error { + time.Sleep(time.Millisecond) + got++ + return nil + }) + Expect(err).NotTo(HaveOccurred()) + Expect(ctx.Err()).NotTo(HaveOccurred()) + Expect(got).To(Equal(54)) + }) +}) diff --git a/pkg/traces/read/lifecycle_test.go b/pkg/traces/read/lifecycle_test.go index 0424442..ea34813 100644 --- a/pkg/traces/read/lifecycle_test.go +++ b/pkg/traces/read/lifecycle_test.go @@ -7,7 +7,6 @@ import ( "path/filepath" "time" - "github.com/flanksource/commons-db/query" "github.com/flanksource/telltale" "github.com/flanksource/telltale/pkg/traces/read" . "github.com/onsi/ginkgo/v2" @@ -18,16 +17,16 @@ var _ = Describe("live run manifest", func() { It("still returns the final result after the run context is cancelled", func() { ctx, cancel := context.WithCancel(context.Background()) defer cancel() - run, err := telltale.Start(ctx, telltale.StartOptions{DataDir: GinkgoT().TempDir(), PID: os.Getpid(), Duration: 5 * time.Second, Traces: []telltale.TraceSpec{{Kind: "process_samples"}}}) + run, err := telltale.Start(ctx, telltale.StartOptions{DataDir: GinkgoT().TempDir(), PID: os.Getpid(), Duration: 5 * time.Second, Traces: []telltale.TraceSpec{{Kind: "process"}}}) Expect(err).NotTo(HaveOccurred()) DeferCleanup(func() { Expect(run.Stop()).To(Succeed()); _, err := run.Wait(); Expect(err).NotTo(HaveOccurred()) }) - result, err := read.Wait(ctx, run, true, func(query.Row) error { cancel(); return nil }) + result, err := read.Wait(ctx, run, true, func(read.Record) error { cancel(); return nil }) Expect(err).NotTo(HaveOccurred()) Expect(result).NotTo(BeNil()) - Expect(result.Captures).To(ConsistOf(HaveField("Kind", "process_samples"))) + Expect(result.Captures).To(ConsistOf(HaveField("Kind", "process"))) }) It("publishes seq-zero refs at start and replaces them with the compatible final result", func() { - run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: GinkgoT().TempDir(), PID: os.Getpid(), Duration: time.Second, Traces: []telltale.TraceSpec{{Kind: "process_samples"}}}) + run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: GinkgoT().TempDir(), PID: os.Getpid(), Duration: time.Second, Traces: []telltale.TraceSpec{{Kind: "process"}}}) Expect(err).NotTo(HaveOccurred()) DeferCleanup(func() { Expect(run.Stop()).To(Succeed()); _, err := run.Wait(); Expect(err).NotTo(HaveOccurred()) }) data, err := os.ReadFile(filepath.Join(run.Dir(), telltale.ManifestFile)) @@ -37,7 +36,8 @@ var _ = Describe("live run manifest", func() { Expect(live.Status).To(Equal(telltale.StatusRunning)) Expect(live.EndedAt.IsZero()).To(BeTrue()) Expect(live.ExitCode).To(BeNil()) - Expect(live.Captures).To(ConsistOf(And(HaveField("Kind", "process_samples"), HaveField("Ref.AfterSeq", int64(0)), HaveField("Ref.ToSeq", int64(0)), HaveField("Ref.Stream", Not(BeEmpty()))))) + Expect(live.Captures).To(ConsistOf(And(HaveField("Kind", "process"), HaveField("Ref.AfterSeq", int64(0)), HaveField("Ref.ToSeq", int64(0)), HaveField("Ref.Stream", Not(BeEmpty()))))) + Expect(live.Process.Tree.Stream).To(Equal(live.Captures[0].Ref.Stream), "reuse the configured process capture") result, err := run.Wait() Expect(err).NotTo(HaveOccurred()) final, err := telltale.ReadManifest(run.Dir()) diff --git a/pkg/traces/read/order.go b/pkg/traces/read/order.go new file mode 100644 index 0000000..e2df26d --- /dev/null +++ b/pkg/traces/read/order.go @@ -0,0 +1,47 @@ +package read + +import ( + "cmp" + "fmt" + sqlpages "github.com/flanksource/commons-db/query/providers/sqlite" + "slices" +) + +func OrderRecords(records []Record, order string) ([]Record, error) { + if order != "seq" && order != "timestamp" { + return nil, fmt.Errorf("unknown record sort %q", order) + } + rows := slices.Clone(records) + var err error + slices.SortStableFunc(rows, func(a, b Record) int { + if order == "timestamp" && a.Timestamp != nil && b.Timestamp != nil { + compared, compareErr := sqlpages.CompareSQLite(a.Timestamp, b.Timestamp) + if compareErr != nil { + err = compareErr + return 0 + } + if compared != 0 { + return compared + } + } + if order == "timestamp" { + if a.Timestamp == nil && b.Timestamp != nil { + return 1 + } + if b.Timestamp == nil && a.Timestamp != nil { + return -1 + } + } + if compared := cmp.Compare(a.Seq, b.Seq); compared != 0 { + return compared + } + if compared := cmp.Compare(a.Kind, b.Kind); compared != 0 { + return compared + } + if compared := cmp.Compare(a.RunID, b.RunID); compared != 0 { + return compared + } + return cmp.Compare(a.Stream, b.Stream) + }) + return rows, err +} diff --git a/pkg/traces/read/presentation.go b/pkg/traces/read/presentation.go new file mode 100644 index 0000000..b088045 --- /dev/null +++ b/pkg/traces/read/presentation.go @@ -0,0 +1,23 @@ +package read + +import ( + "fmt" + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +func (r Record) Pretty() api.Text { + return api.Text{}.Add(r.prefix()).Space().Add(r.presentation.Summary) +} + +func (r Record) PrettyFull() api.Textable { + return api.Text{}.Add(r.prefix()).Space().Add(r.presentation.Detail) +} + +func (r Record) prefix() api.Textable { + kind := r.Kind + if r.Result != "" { + kind += "/" + r.Result + } + return clicky.Text(fmt.Sprintf("%s #%d", kind, r.Seq), "text-muted") +} diff --git a/pkg/traces/read/read.go b/pkg/traces/read/read.go index 07dd81d..46f9ba8 100644 --- a/pkg/traces/read/read.go +++ b/pkg/traces/read/read.go @@ -18,6 +18,7 @@ type Scope struct { Run string Runs []string Since time.Time + Result string } type Ref struct { @@ -27,10 +28,14 @@ type Ref struct { } type Selection struct { + Runs []telltale.RunInfo Refs []Ref closers []func() error } +// AddCloser transfers the lifetime of a constituent selection to this one. +func (s *Selection) AddCloser(close func() error) { s.closers = append(s.closers, close) } + func (s *Selection) Close() error { var errs []error for _, closeStore := range s.closers { @@ -48,6 +53,7 @@ type Query struct { Cursor string All bool NextCursor func(string) `json:"-"` + seqOrder bool } func Resolve(kind string, scope Scope) (_ *Selection, err error) { @@ -58,6 +64,14 @@ func Resolve(kind string, scope Scope) (_ *Selection, err error) { if _, err := traces.Lookup(kinds, kind); err != nil { return nil, err } + if scope.Result != "" { + storage := kind + "_" + scope.Result + owner, result := kinds.ResultOf(storage) + if owner != kind || result == "" { + return nil, fmt.Errorf("kind %s has no result %q", kind, scope.Result) + } + kind = storage + } if scope.Run != "" && len(scope.Runs) > 0 { return nil, fmt.Errorf("--run and --runs are mutually exclusive") } @@ -74,7 +88,8 @@ func Resolve(kind string, scope Scope) (_ *Selection, err error) { if !scope.Since.IsZero() { limit = 0 } - runs, err = telltale.List(telltale.ListOptions{DataDir: scope.DataDir, Kind: kind, Since: scope.Since, Limit: limit}) + owner, _ := kinds.ResultOf(kind) + runs, err = telltale.List(telltale.ListOptions{DataDir: scope.DataDir, Kind: owner, Since: scope.Since, Limit: limit}) if err != nil { return nil, err } @@ -105,25 +120,27 @@ func Resolve(kind string, scope Scope) (_ *Selection, err error) { } }() for _, run := range runs { - var refs []tracing.TraceRef - for _, capture := range run.Captures { - if capture.Kind == kind { - refs = append(refs, capture.Ref) - } - } - if len(refs) == 0 { - return nil, fmt.Errorf("run %s has no %s capture", run.RunID, kind) + if run.Unavailable != "" { + return nil, fmt.Errorf("read %s: %s", run.RunID, run.Unavailable) } runtime, closeStore, err := telltale.Reopen(scope.DataDir, run.RunID) if err != nil { return nil, err } selected.closers = append(selected.closers, closeStore) + refs, err := RunRefs(run, runtime) + if err != nil { + return nil, err + } + found := false for _, ref := range refs { - if err := ref.Validate(); err != nil { - return nil, err + if ref.Kind == kind { + selected.Refs = append(selected.Refs, ref) + found = true } - selected.Refs = append(selected.Refs, Ref{RunID: run.RunID, Runtime: runtime, TraceRef: ref}) + } + if !found { + return nil, fmt.Errorf("run %s has no %s capture", run.RunID, kind) } } return selected, nil diff --git a/pkg/traces/read/read_test.go b/pkg/traces/read/read_test.go index 88a1e94..6cde7c3 100644 --- a/pkg/traces/read/read_test.go +++ b/pkg/traces/read/read_test.go @@ -23,6 +23,7 @@ import ( func TestRead(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Trace read") } type reading struct { + Kind string `json:"kind,omitempty"` At time.Time `json:"at"` Value float64 `json:"value" filter:"range"` Label string `json:"label" filter:"text"` diff --git a/pkg/traces/read/refs.go b/pkg/traces/read/refs.go new file mode 100644 index 0000000..438a9de --- /dev/null +++ b/pkg/traces/read/refs.go @@ -0,0 +1,36 @@ +package read + +import ( + "fmt" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/tracing" +) + +// RunRefs enumerates a run's captures and named tables, including its process trace. +func RunRefs(info telltale.RunInfo, runtime *tracing.Runtime) ([]Ref, error) { + refs := []Ref{} + seen := map[string]bool{} + primary := []tracing.TraceRef{} + for _, capture := range info.Captures { + primary = append(primary, capture.Ref) + } + if info.Process != nil { + primary = append(primary, info.Process.Tree, info.Process.Stacks) + } + for _, ref := range primary { + if _, exists := runtime.Kinds.Get(ref.Kind); !exists { + return nil, fmt.Errorf("run %s uses unsupported trace kind %q; recordings with process_tree, process_samples or process_groups require the build that recorded them", info.RunID, ref.Kind) + } + for _, result := range runtime.Kinds.CaptureRefs(ref) { + if err := result.Validate(); err != nil { + return nil, err + } + if seen[result.Stream] { + continue + } + seen[result.Stream] = true + refs = append(refs, Ref{RunID: info.RunID, Runtime: runtime, TraceRef: result}) + } + } + return refs, nil +} diff --git a/pkg/traces/read/request.go b/pkg/traces/read/request.go index a09e2cf..5bf0fed 100644 --- a/pkg/traces/read/request.go +++ b/pkg/traces/read/request.go @@ -25,7 +25,7 @@ func ParseRequest(dataDir string, values url.Values) (scope Scope, q Query, aggr if err != nil { return } - scope = Scope{DataDir: dataDir, Run: values.Get("run"), Runs: requestList(values["runs"])} + scope = Scope{DataDir: dataDir, Run: values.Get("run"), Runs: requestList(values["runs"]), Result: values.Get("result")} q = Query{Filters: values["filter"], Search: values.Get("q"), Where: values.Get("where"), Cursor: values.Get("cursor")} aggregate = Aggregate{Columns: requestList(values["stats"]), GroupBy: values.Get("groupBy"), View: values.Get("view")} if err = parseRequestTimes(values, &scope, &q); err != nil { diff --git a/pkg/traces/read/rows.go b/pkg/traces/read/rows.go index f72efb6..2807531 100644 --- a/pkg/traces/read/rows.go +++ b/pkg/traces/read/rows.go @@ -154,6 +154,9 @@ func Rows(ctx context.Context, refs []Ref, q Query) iter.Seq2[query.Row, error] yield(nil, err) return } + if q.seqOrder { + p.Order = query.Order{{Column: "seq", Unique: true}} + } params, err := q.params(ref, p) if err != nil { yield(nil, err) diff --git a/pkg/traces/read/runs.go b/pkg/traces/read/runs.go new file mode 100644 index 0000000..e720c8c --- /dev/null +++ b/pkg/traces/read/runs.go @@ -0,0 +1,67 @@ +package read + +import ( + "errors" + "fmt" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/tracing" +) + +// ResolveRuns opens every armed capture of explicitly selected runs. +func ResolveRuns(scope Scope) (_ *Selection, err error) { + if scope.DataDir == "" || scope.Run == "" && len(scope.Runs) == 0 { + return nil, fmt.Errorf("replay requires a data dir and at least one run ID") + } + if scope.Run != "" && len(scope.Runs) > 0 { + return nil, fmt.Errorf("--run and --runs are mutually exclusive") + } + ids := scope.Runs + if scope.Run != "" { + ids = []string{scope.Run} + } + selected := &Selection{} + defer func() { + if err != nil { + err = errors.Join(err, selected.Close()) + } + }() + seen := map[string]bool{} + for _, id := range ids { + if seen[id] { + return nil, fmt.Errorf("run %q selected twice", id) + } + seen[id] = true + info, err := telltale.Get(telltale.GetOptions{DataDir: scope.DataDir, RunID: id}) + if err != nil { + return nil, err + } + if info.Unavailable != "" { + return nil, fmt.Errorf("replay %s: %s", id, info.Unavailable) + } + selected.Runs = append(selected.Runs, info) + } + for _, info := range selected.Runs { + run, live, err := telltale.Live(scope.DataDir, info.RunID) + if err != nil { + return nil, err + } + var runtime *tracing.Runtime + if live { + runtime = run.Runtime() + } else { + var closeStore func() error + runtime, closeStore, err = telltale.Reopen(scope.DataDir, info.RunID) + if err != nil { + return nil, err + } + selected.AddCloser(closeStore) + } + refs, err := RunRefs(info, runtime) + if err != nil { + return nil, err + } + selected.Refs = append(selected.Refs, refs...) + } + return selected, nil +} diff --git a/pkg/traces/registry_test.go b/pkg/traces/registry_test.go index 68f71dd..95da1b2 100644 --- a/pkg/traces/registry_test.go +++ b/pkg/traces/registry_test.go @@ -21,7 +21,7 @@ func registrationNames() []string { } var _ = Describe("the trace kind registry", func() { - builtins := []string{"goprof", "http", "process_samples", "process_tree", "sql", "stacks", "terminal"} + builtins := []string{"goprof", "http", "process", "sql", "stacks", "terminal"} valid := func(name string) traces.Registration { return traces.Registration{ Name: name, Title: "Registered for a test", Summary: "Records nothing", Seams: []target.Seam{target.Self}, DefaultSeam: target.Self, @@ -43,13 +43,16 @@ var _ = Describe("the trace kind registry", func() { It("registers the supported seam and default for each builtin", func() { for kind, seam := range map[string]target.Seam{ - "process_tree": target.Process, "process_samples": target.Process, - "stacks": target.Process, "goprof": target.Process, - "process_groups": target.Host, "http": target.Self, "sql": target.Self, "terminal": target.Self, + "process": target.Process, + "stacks": target.Process, "goprof": target.Process, + "http": target.Self, "sql": target.Self, "terminal": target.Self, } { registration, err := traces.Registered(kind) Expect(err).NotTo(HaveOccurred()) seams := []target.Seam{seam} + if kind == "process" { + seams = append(seams, target.Host) + } if kind == "stacks" || kind == "goprof" { seams = append(seams, target.Agent, target.Self) } @@ -63,7 +66,7 @@ var _ = Describe("the trace kind registry", func() { It("rejects an unsupported seam before starting a capture", func() { kinds, err := traces.Kinds() Expect(err).NotTo(HaveOccurred()) - err = traces.Validate(kinds, "process_tree", []byte(`{"target":{"seam":"proxy"}}`)) + err = traces.Validate(kinds, "process", []byte(`{"target":{"seam":"proxy"}}`)) Expect(err).To(MatchError(ContainSubstring("unsupported seam"))) Expect(err).To(MatchError(ContainSubstring("process"))) }) diff --git a/pkg/traces/runid.go b/pkg/traces/runid.go new file mode 100644 index 0000000..88901d5 --- /dev/null +++ b/pkg/traces/runid.go @@ -0,0 +1,44 @@ +package traces + +import ( + "fmt" + "os" + "regexp" + "strings" + "time" +) + +const RunTimestampLayout = "20060102T150405Z" + +const ManifestFile = "run.json" + +var runIDPattern = regexp.MustCompile(`^[A-Za-z0-9]{1,9}[0-9]{8}T[0-9]{6}Z(?:_[2-9][0-9]*|_1[0-9]+)?$`) + +// IsRunID identifies compact generated IDs, including collision suffixes. +func IsRunID(id string) bool { return runIDPattern.MatchString(id) } + +// RunID names a run by its short hostname and UTC start time. +func RunID(started time.Time) string { + hostname, err := os.Hostname() + if err != nil { + panic(fmt.Errorf("name trace run: hostname: %w", err)) + } + prefix, err := hostnamePrefix(hostname) + if err != nil { + panic(err) + } + return prefix + started.UTC().Format(RunTimestampLayout) +} + +func hostnamePrefix(hostname string) (string, error) { + prefix := strings.ReplaceAll(strings.Split(hostname, ".")[0], "-", "") + if prefix == "" { + return "", fmt.Errorf("name trace run: hostname %q has no short name", hostname) + } + for _, char := range prefix { + if (char < 'a' || char > 'z') && (char < 'A' || char > 'Z') && (char < '0' || char > '9') { + return "", fmt.Errorf("name trace run: hostname %q contains an invalid character", hostname) + } + } + return prefix[:min(9, len(prefix))], nil +} diff --git a/pkg/traces/runid_test.go b/pkg/traces/runid_test.go new file mode 100644 index 0000000..1bf4536 --- /dev/null +++ b/pkg/traces/runid_test.go @@ -0,0 +1,23 @@ +package traces + +import ( + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("run hostname prefix", func() { + DescribeTable("uses up to nine dash-free characters of the short hostname", func(hostname, expected string) { + prefix, err := hostnamePrefix(hostname) + Expect(err).NotTo(HaveOccurred()) + Expect(prefix).To(Equal(expected)) + }, + Entry("short", "dev", "dev"), + Entry("long", "buildworker12", "buildwork"), + Entry("qualified", "worker.example.com", "worker"), + Entry("dashes", "build-worker-12.local", "buildwork"), + ) + DescribeTable("refuses unusable hostnames", func(hostname string) { + _, err := hostnamePrefix(hostname) + Expect(err).To(HaveOccurred()) + }, Entry("empty", ""), Entry("dashes alone", "---"), Entry("path", "../escape")) +}) From bd47275eadb09a77fb47f154468637329a0d5e05 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:06:17 +0200 Subject: [PATCH 08/89] feat(trace): add trace explain and replay commands with a run viewer --- internal/cli/explain.go | 95 ++++++++ internal/cli/explain_test.go | 52 +++++ internal/cli/follow.go | 118 ++++++++++ internal/cli/help_pages.go | 2 +- internal/cli/kindflags_internal_test.go | 14 +- internal/cli/records.go | 11 +- internal/cli/records_test.go | 28 ++- internal/cli/replay.go | 106 +++++++++ internal/cli/replay_test.go | 68 ++++++ internal/cli/root.go | 2 +- internal/cli/run.go | 59 ++++- internal/cli/run_test.go | 12 +- internal/cli/styled_replay_test.go | 41 ++++ internal/cli/top.go | 14 +- internal/cli/trace.go | 4 +- internal/protocol/gitwire/decoder.go | 2 +- internal/server/feed_openapi.go | 30 +++ internal/server/handler.go | 4 +- internal/server/viewer.go | 111 ++++++++++ internal/server/viewer_test.go | 55 +++++ internal/terminalui/styles.go | 8 + internal/topui/actions.go | 13 ++ internal/topui/grouping_test.go | 3 + internal/topui/memory_test.go | 48 ++++ internal/topui/model.go | 220 ++++++++++++++++--- internal/topui/model_test.go | 109 ++++++++- internal/topui/source.go | 7 +- internal/topui/view.go | 114 ++++++---- internal/traceui/model.go | 279 ++++++++++++++++++++++++ internal/traceui/model_test.go | 38 ++++ internal/traceui/source.go | 208 ++++++++++++++++++ internal/traceui/source_test.go | 56 +++++ internal/traceui/view.go | 116 ++++++++++ internal/traceui/view_test.go | 57 +++++ 34 files changed, 1986 insertions(+), 118 deletions(-) create mode 100644 internal/cli/explain.go create mode 100644 internal/cli/explain_test.go create mode 100644 internal/cli/follow.go create mode 100644 internal/cli/replay.go create mode 100644 internal/cli/replay_test.go create mode 100644 internal/cli/styled_replay_test.go create mode 100644 internal/server/feed_openapi.go create mode 100644 internal/server/viewer.go create mode 100644 internal/server/viewer_test.go create mode 100644 internal/terminalui/styles.go create mode 100644 internal/topui/memory_test.go create mode 100644 internal/traceui/model.go create mode 100644 internal/traceui/model_test.go create mode 100644 internal/traceui/source.go create mode 100644 internal/traceui/source_test.go create mode 100644 internal/traceui/view.go create mode 100644 internal/traceui/view_test.go diff --git a/internal/cli/explain.go b/internal/cli/explain.go new file mode 100644 index 0000000..46cb1f9 --- /dev/null +++ b/internal/cli/explain.go @@ -0,0 +1,95 @@ +package cli + +import ( + "encoding/json" + "fmt" + "strings" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/target" + "github.com/spf13/cobra" +) + +type kindExplanation struct { + tracing.KindInfo + Summary string `json:"summary"` + Description string `json:"description"` + Seams []target.Seam `json:"seams"` + DefaultSeam target.Seam `json:"defaultSeam"` +} + +func (e kindExplanation) Pretty() api.Text { + t := clicky.Text(e.Name, "font-bold").Append(" — " + e.Summary).NewLine() + if e.Description != "" { + t = t.Append(e.Description).NewLine() + } + seams := make([]string, 0, len(e.Seams)) + for _, seam := range e.Seams { + seams = append(seams, string(seam)) + } + t = t.Append("Targets: " + strings.Join(seams, ", ") + " (default: " + string(e.DefaultSeam) + ")").NewLine() + data, err := json.MarshalIndent(e.Params, "", " ") + if err != nil { + panic(fmt.Errorf("marshal %s parameter schema: %w", e.Name, err)) + } + t = t.Append("Parameters", "font-bold").NewLine().Add(clicky.CodeBlock("application/json", string(data))).NewLine() + t = t.Append("Record schema", "font-bold").NewLine() + for _, column := range e.Columns { + t = t.Append(fmt.Sprintf("%s %s %s", column.Name, column.Type, column.Label)).NewLine() + } + return t +} + +func newExplainCommand() *cobra.Command { + return &cobra.Command{ + Use: "explain [kind]", Short: "Describe trace kinds and their schemas", Args: cobra.MaximumNArgs(1), + ValidArgsFunction: func(_ *cobra.Command, _ []string, prefix string) ([]string, cobra.ShellCompDirective) { + var names []string + for _, registration := range traces.Registrations() { + if strings.HasPrefix(registration.Name, prefix) { + names = append(names, registration.Name) + } + } + return names, cobra.ShellCompDirectiveNoFileComp + }, + RunE: func(cmd *cobra.Command, args []string) error { + if len(args) == 0 { + var list []struct { + Name string `json:"name"` + Summary string `json:"summary"` + } + for _, registration := range traces.Registrations() { + list = append(list, struct { + Name string `json:"name"` + Summary string `json:"summary"` + }{registration.Name, registration.Summary}) + } + return printRecords(cmd, list) + } + kinds, err := traces.Kinds() + if err != nil { + return err + } + if _, err := traces.Lookup(kinds, args[0]); err != nil { + return err + } + registration, err := traces.Registered(args[0]) + if err != nil { + return err + } + list, err := kinds.List() + if err != nil { + return err + } + for _, info := range list { + if info.Name == args[0] { + return printRecords(cmd, kindExplanation{info, registration.Summary, registration.Description, registration.Seams, registration.DefaultSeam}) + } + } + return fmt.Errorf("trace kind %q is missing from catalog", args[0]) + }, + } +} diff --git a/internal/cli/explain_test.go b/internal/cli/explain_test.go new file mode 100644 index 0000000..a9763f1 --- /dev/null +++ b/internal/cli/explain_test.go @@ -0,0 +1,52 @@ +package cli_test + +import ( + "bytes" + "encoding/json" + + "github.com/flanksource/telltale/internal/cli" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("explain", func() { + It("lists registered kinds and rejects excess arguments", func() { + root := cli.NewRoot("test") + out := &bytes.Buffer{} + root.SetOut(out) + root.SetArgs([]string{"explain", "--json"}) + Expect(root.Execute()).To(Succeed()) + var kinds []map[string]any + Expect(json.Unmarshal(out.Bytes(), &kinds)).To(Succeed()) + Expect(kinds).To(ContainElement(HaveKeyWithValue("name", "http"))) + root = cli.NewRoot("test") + root.SetArgs([]string{"explain", "http", "sql"}) + Expect(root.Execute()).To(HaveOccurred()) + }) + It("returns the HTTP parameter schema and record columns as JSON", func() { + root := cli.NewRoot("test") + out := &bytes.Buffer{} + root.SetOut(out) + root.SetArgs([]string{"explain", "http", "--json"}) + Expect(root.Execute()).To(Succeed()) + var result map[string]any + Expect(json.Unmarshal(out.Bytes(), &result)).To(Succeed()) + Expect(result).To(HaveKey("params")) + Expect(result).To(HaveKey("columns")) + Expect(result["name"]).To(Equal("http")) + params := result["params"].(map[string]any)["properties"].(map[string]any) + Expect(params["mode"].(map[string]any)["enum"]).To(Equal([]any{"connect", "mitm"})) + }) + It("rejects unknown kinds", func() { + root := cli.NewRoot("test") + root.SetArgs([]string{"explain", "missing"}) + Expect(root.Execute()).To(MatchError(ContainSubstring("unknown trace kind"))) + }) + It("completes registered kind names", func() { + root := cli.NewRoot("test") + cmd, _, err := root.Find([]string{"explain"}) + Expect(err).NotTo(HaveOccurred()) + names, _ := cmd.ValidArgsFunction(cmd, nil, "htt") + Expect(names).To(ContainElement("http")) + }) +}) diff --git a/internal/cli/follow.go b/internal/cli/follow.go new file mode 100644 index 0000000..a620b06 --- /dev/null +++ b/internal/cli/follow.go @@ -0,0 +1,118 @@ +package cli + +import ( + "context" + "errors" + "fmt" + "github.com/flanksource/clicky/rpc" + "os" + "os/signal" + "syscall" + "time" + + tea "charm.land/bubbletea/v2" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/internal/server" + "github.com/flanksource/telltale/internal/traceui" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/spf13/cobra" + "golang.org/x/term" +) + +func bindFollow(cmd *cobra.Command) { + cmd.Flags().Bool("follow", false, "Print every armed capture's records while recording") + cmd.Flags().Bool("tui", false, "Follow records in an interactive terminal") + cmd.Flags().Bool("ui", false, "Open this run's traces in a local web viewer; keep serving until Ctrl+C") + cmd.Flags().String("sort", "seq", "Record order: seq or timestamp") +} + +func followOptions(cmd *cobra.Command) (bool, bool, bool, string, error) { + follow, err := cmd.Flags().GetBool("follow") + if err != nil { + return false, false, false, "", err + } + tui, err := cmd.Flags().GetBool("tui") + if err != nil { + return false, false, false, "", err + } + ui, err := cmd.Flags().GetBool("ui") + if err != nil { + return false, false, false, "", err + } + sort, err := cmd.Flags().GetString("sort") + if err != nil { + return false, false, false, "", err + } + if sort != "seq" && sort != "timestamp" { + return false, false, false, "", fmt.Errorf("unknown record sort %q", sort) + } + if tui && (!term.IsTerminal(int(os.Stdin.Fd())) || !term.IsTerminal(int(os.Stdout.Fd()))) { + return false, false, false, "", errors.New("--tui requires a terminal") + } + return follow || tui, tui, ui, sort, nil +} + +func openRunViewer(cmd *cobra.Command, options server.ViewerOptions) (*server.Viewer, error) { + viewer, err := server.StartViewer(options) + if err != nil { + return nil, err + } + order, err := cmd.Flags().GetString("sort") + if err != nil { + return nil, err + } + viewer.URL += "&feedSort=" + order + if _, err := fmt.Fprintln(cmd.ErrOrStderr(), viewer.URL); err != nil { + return nil, err + } + // Opening the browser is an output action; readiness is established by the listener. + if err := rpc.OpenBrowser(viewer.URL); err != nil { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + return nil, errors.Join(err, viewer.Close(ctx)) + } + return viewer, nil +} + +func waitViewer(viewer *server.Viewer) error { + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + <-ctx.Done() + closeCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + return viewer.Close(closeCtx) +} + +func showTraceTUI(ctx context.Context, run *telltale.Run, sort string) (_ *telltale.Result, err error) { + runtime, closeStore, err := traces.Reopen(run.Dir()) + if err != nil { + return nil, errors.Join(err, run.Stop()) + } + defer func() { err = errors.Join(err, closeStore()) }() + info := run.Info() + refs, err := read.RunRefs(info, runtime) + if err != nil { + return nil, err + } + feedCtx, cancel := context.WithCancel(context.WithoutCancel(ctx)) + defer cancel() + program := tea.NewProgram(traceui.New(feedCtx, traceui.Options{Refs: refs, Runs: []telltale.RunInfo{info}, Sort: sort}), tea.WithContext(ctx)) + go func() { + select { + case <-run.Done(): + info := run.Info() + program.Send(traceui.End{Info: &info}) + case <-feedCtx.Done(): + } + }() + final, runErr := program.Run() + err = runErr + if model, ok := final.(traceui.Model); ok { + err = errors.Join(err, model.Err()) + } + stopErr := run.Stop() + result, waitErr := run.Wait() + cancel() + return result, errors.Join(err, stopErr, waitErr) +} diff --git a/internal/cli/help_pages.go b/internal/cli/help_pages.go index 40484ba..c68c3f0 100644 --- a/internal/cli/help_pages.go +++ b/internal/cli/help_pages.go @@ -74,7 +74,7 @@ func runHelp(cmd *cobra.Command) helpText { } return h.section("Examples"). command("telltale run http --seam proxy --mode mitm -- curl -sS https://example.com", "decrypt and record a request"). - command("telltale run process_samples --pid 1234 --facets ports --duration 1m", "sample a running process for a minute"). + command("telltale run process --pid 1234 --facets sockets --duration 1m", "sample a running process for a minute"). command("telltale run stacks --every 10s -- ./server", "dump a server's stacks every 10 seconds"). section("See also"). command("telltale run --help", "a kind's params, exports and examples"). diff --git a/internal/cli/kindflags_internal_test.go b/internal/cli/kindflags_internal_test.go index 81f6846..b56b922 100644 --- a/internal/cli/kindflags_internal_test.go +++ b/internal/cli/kindflags_internal_test.go @@ -5,7 +5,7 @@ import ( "github.com/flanksource/telltale/pkg/traces" "github.com/flanksource/telltale/pkg/tracing/goprof" "github.com/flanksource/telltale/pkg/tracing/httpproxy" - "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" "github.com/flanksource/telltale/pkg/tracing/target" . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" @@ -51,7 +51,7 @@ var _ = Describe("a kind's params as flags", func() { It("shows the supported seam but does not offer unimplemented agent targeting", func() { flags := pflag.NewFlagSet("test", pflag.ContinueOnError) - _, err := bindParamFlags(flags, kindSchema(process.SamplesKind)) + _, err := bindParamFlags(flags, kindSchema(processcapture.Kind)) Expect(err).NotTo(HaveOccurred()) Expect(flags.Lookup("seam").Usage).To(ContainSubstring("process")) Expect(flags.Lookup("agent")).To(BeNil()) @@ -59,20 +59,20 @@ var _ = Describe("a kind's params as flags", func() { Expect(flags.Lookup("wait")).To(BeNil()) }) It("names the selector flag when its value is malformed", func() { - schema := kindSchema(process.SamplesKind) + schema := kindSchema(processcapture.Kind) schema.Properties["target"].Extensions["x-telltale-seams"] = []target.Seam{target.Agent, target.Process} _, err := parsed(schema, "--selector", "invalid") Expect(err).To(MatchError(ContainSubstring("--selector:"))) }) It("keeps a run PID separate from an explicit agent", func() { - schema := kindSchema(process.SamplesKind) + schema := kindSchema(processcapture.Kind) schema.Properties["target"].Extensions["x-telltale-seams"] = []target.Seam{target.Agent, target.Process} params, err := parsed(schema, "--pid", "123", "--agent", "worker") Expect(err).NotTo(HaveOccurred()) Expect(params).To(MatchJSON(`{"target":{"agent":"worker"}}`)) }) It("passes mutation consent in the common target", func() { - schema := kindSchema(process.SamplesKind) + schema := kindSchema(processcapture.Kind) schema.Properties["target"].Extensions["x-telltale-seams"] = []target.Seam{target.Agent, target.Process} params, err := parsed(schema, "--allow-mutation") Expect(err).NotTo(HaveOccurred()) @@ -101,8 +101,8 @@ var _ = Describe("a kind's params as flags", func() { Entry("a choice and a list", httpproxy.Kind, []string{"--mode", "mitm", "--hosts", "a.example,b.example"}, `{"mode": "mitm", "hosts": ["a.example", "b.example"]}`), Entry("a repeated list flag", httpproxy.Kind, []string{"--redact", "X-One", "--redact", "X-Two"}, `{"redact": ["X-One", "X-Two"]}`), Entry("a boolean and an integer", "sql", []string{"--params", "--max-statements", "10"}, `{"params": true, "maxStatements": 10}`), - Entry("an object's params, nested", process.TreeKind, []string{"--environment-keys", "PATH", "--interval", "2s"}, `{"environment": {"keys": ["PATH"]}, "interval": "2s"}`), - Entry("a run PID and an embedded struct's params", process.SamplesKind, []string{"--pid", "7", "--facets", "ports"}, `{"facets": ["ports"]}`), + Entry("an object's params, nested", processcapture.Kind, []string{"--environment-keys", "PATH", "--interval", "2s"}, `{"environment": {"keys": ["PATH"]}, "interval": "2s"}`), + Entry("a run PID and an embedded struct's params", processcapture.Kind, []string{"--pid", "7", "--facets", "sockets"}, `{"facets": ["sockets"]}`), ) It("refuses a value outside a param's choices, naming its flag and the choices", func() { diff --git a/internal/cli/records.go b/internal/cli/records.go index 9e73ee4..ea281f8 100644 --- a/internal/cli/records.go +++ b/internal/cli/records.go @@ -28,11 +28,11 @@ func newRecordsCommand() *cobra.Command { --filter uses profile column grammar, e.g. pid=123 or rssBytes=>=1048576. --where uses CEL with a row binding, e.g. row.cpuPercent != null && row.cpuPercent > 10. --limit applies after CEL; --all reads every matching row. A continuation cursor is printed to stderr when more rows remain. --stats aggregates all matching rows unless --limit is explicitly set. Nulls are skipped. Percentiles use nearest rank, exact through 8192 values per column/group, then an 8192-value reservoir; approximate=true identifies sampling. At most 1024 groups, 64 columns, and 1024 column/group pairs are allowed (64 MiB of reservoir values). --group-by alone counts rows. --view runs a named kind view over the seq window; row filters and time bounds require --stats instead.`, - Example: ` telltale records process_samples --json - telltale records process_samples --since 2h --filter 'rssBytes=>=1048576' --where 'row.cpuPercent > 10' --all - telltale records process_samples --run run-2026-10-28T09-00-00Z --follow --format ndjson - telltale records process_samples --stats cpuPercent,rssBytes --group-by pid - telltale records process_samples --group-by pid --format csv + Example: ` telltale records process --json + telltale records process --result metrics --since 2h --filter 'rssBytes=>=1048576' --where 'row.cpuPercent > 10' --all + telltale records process --result facets --run --follow --format ndjson + telltale records process --result metrics --stats cpuPercent,rssBytes --group-by entity + telltale records process --result metrics --group-by entity --format csv telltale records spans --run receiver --filter service=checkout --limit 5 telltale records spans --run receiver --stats durationMs --group-by operation telltale records spans --run receiver --follow @@ -102,6 +102,7 @@ func newRecordsCommand() *cobra.Command { f := cmd.Flags() bindDataDir(f, &scope.DataDir) f.StringVar(&scope.Run, "run", "", "Run id (default: newest containing the kind)") + f.StringVar(&scope.Result, "result", "", "Named result table, e.g. process --result metrics or --result facets") f.StringSliceVar(&scope.Runs, "runs", nil, "Comma-separated run ids") f.StringVar(&since, "since", "", "Run-start cutoff and default row-time start: duration or RFC3339") f.StringVar(&from, "from", "", "Inclusive row-time start (RFC3339); overrides --since's row window") diff --git a/internal/cli/records_test.go b/internal/cli/records_test.go index 8ebec90..d4a9cf7 100644 --- a/internal/cli/records_test.go +++ b/internal/cli/records_test.go @@ -2,6 +2,9 @@ package cli_test import ( "context" + "encoding/json" + "net/http" + "net/http/httptest" "path/filepath" "strings" "time" @@ -14,9 +17,28 @@ import ( ) var _ = Describe("records command", func() { + It("keeps followed NDJSON free of command output and final summaries", func() { + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + _, err := w.Write([]byte("command-output")) + Expect(err).NotTo(HaveOccurred()) + })) + defer upstream.Close() + stdout, stderr, err := execute("trace", "run", "--data-dir", GinkgoT().TempDir(), "--follow", "--format", "ndjson", "--", "curl", "-sS", upstream.URL) + Expect(err).NotTo(HaveOccurred(), stderr) + lines := strings.Split(strings.TrimSpace(stdout), "\n") + Expect(lines).To(HaveLen(1)) + var record struct { + Kind string `json:"kind"` + Record map[string]any `json:"record"` + } + Expect(json.Unmarshal([]byte(lines[0]), &record)).To(Succeed()) + Expect(record.Kind).To(Equal("http")) + Expect(record.Record).To(HaveKey("request")) + Expect(stderr).To(ContainSubstring("command-output")) + }) It("registers follow on both run command forms", func() { root := cli.NewRoot("test") - for _, args := range [][]string{{"run", "process_samples"}, {"trace", "run"}} { + for _, args := range [][]string{{"run", "process"}, {"trace", "run"}} { cmd, _, err := root.Find(args) Expect(err).NotTo(HaveOccurred()) Expect(cmd.Flags().Lookup("follow")).NotTo(BeNil()) @@ -24,7 +46,7 @@ var _ = Describe("records command", func() { } }) DescribeTable("refuses invalid selections before opening stores", func(args []string, message string) { - _, _, err := execute(append([]string{"records", "process_samples", "--data-dir", GinkgoT().TempDir()}, args...)...) + _, _, err := execute(append([]string{"records", "process", "--data-dir", GinkgoT().TempDir()}, args...)...) Expect(err).To(MatchError(ContainSubstring(message))) }, Entry("follow across runs", []string{"--runs", "one,two", "--follow"}, "--follow requires a single run"), @@ -68,7 +90,7 @@ var _ = Describe("records command", func() { }) It("includes runnable examples and window semantics in help", func() { page := help("records") - Expect(page).To(ContainSubstring("telltale records process_samples")) + Expect(page).To(ContainSubstring("telltale records process --result metrics")) Expect(page).To(ContainSubstring("--from overrides")) }) }) diff --git a/internal/cli/replay.go b/internal/cli/replay.go new file mode 100644 index 0000000..6d63a31 --- /dev/null +++ b/internal/cli/replay.go @@ -0,0 +1,106 @@ +package cli + +import ( + "encoding/json" + "errors" + "fmt" + + tea "charm.land/bubbletea/v2" + "github.com/flanksource/clicky" + "github.com/flanksource/telltale/internal/server" + "github.com/flanksource/telltale/internal/traceui" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/spf13/cobra" +) + +func newTraceReplayCommand() *cobra.Command { + var dataDir string + cmd := &cobra.Command{ + Use: "replay [run-id...]", Short: "Replay recorded captures without rerunning their commands", Args: cobra.MinimumNArgs(1), + Long: "Read the saved captures of one or more trace/run IDs. Records are merged in sequence or timestamp order. --ui opens a local viewer with a run selector; --tui opens the interactive terminal. Replay never executes recorded commands.", + Example: " telltale trace replay buildhost20261107T123000Z\n telltale trace replay --ui\n telltale trace replay --format ndjson --sort timestamp", + RunE: func(cmd *cobra.Command, ids []string) (err error) { + follow, tui, ui, order, err := followOptions(cmd) + if err != nil { + return err + } + if tui && ui { + return fmt.Errorf("replay: --ui and --tui are mutually exclusive") + } + explicitFollow, err := cmd.Flags().GetBool("follow") + if err != nil { + return err + } + if explicitFollow && tui { + return fmt.Errorf("replay: --follow cannot combine with --tui") + } + if tui && clicky.Flags.ResolveFormat() == "ndjson" { + return fmt.Errorf("--tui cannot combine with ndjson") + } + format := clicky.Flags.ResolveFormat() + if format != "ndjson" && format != "pretty" && format != "ansi" { + return fmt.Errorf("replay supports ndjson, ansi or pretty output") + } + selected, err := read.ResolveRuns(read.Scope{DataDir: dataDir, Runs: ids}) + if err != nil { + return err + } + defer func() { err = errors.Join(err, selected.Close()) }() + if ui { + viewer, err := openRunViewer(cmd, server.ViewerOptions{DataDir: dataDir, RunIDs: ids}) + if err != nil { + return err + } + return waitViewer(viewer) + } + if tui { + final, err := tea.NewProgram(traceui.New(cmd.Context(), traceui.Options{Refs: selected.Refs, Runs: selected.Runs, Sort: order, Replay: true}), tea.WithContext(cmd.Context())).Run() + if model, ok := final.(traceui.Model); ok { + err = errors.Join(err, model.Err()) + } + return err + } + if follow { + return read.Feed(cmd.Context(), selected.Refs, read.Query{}, func(record read.Record) error { return printTraceRecord(cmd, record) }) + } + return replayRecords(cmd, selected.Refs, order) + }, + } + bindDataDir(cmd.Flags(), &dataDir) + cmd.Flags().Bool("follow", false, "Follow selected captures until their streams seal") + cmd.Flags().Bool("ui", false, "Open a local web viewer for the selected runs until Ctrl+C") + cmd.Flags().Bool("tui", false, "Replay records in an interactive terminal") + cmd.Flags().String("sort", "seq", "Record order: seq or timestamp") + return cmd +} + +func replayRecords(cmd *cobra.Command, refs []read.Ref, order string) error { + query := read.FeedQuery{Sort: order} + for { + page, err := read.FeedPage(cmd.Context(), refs, query) + if err != nil { + return err + } + for _, record := range page.Rows { + if err := printTraceRecord(cmd, record); err != nil { + return err + } + } + if page.NextCursor == "" { + return nil + } + query.Cursor = page.NextCursor + } +} + +func printTraceRecord(cmd *cobra.Command, record read.Record) error { + if clicky.Flags.ResolveFormat() == "ndjson" { + return json.NewEncoder(cmd.OutOrStdout()).Encode(record) + } + output, err := clicky.Format(record.Pretty(), clicky.FormatOptions{Format: "pretty"}) + if err != nil { + return err + } + _, err = fmt.Fprintln(cmd.OutOrStdout(), output) + return err +} diff --git a/internal/cli/replay_test.go b/internal/cli/replay_test.go new file mode 100644 index 0000000..d8b6f85 --- /dev/null +++ b/internal/cli/replay_test.go @@ -0,0 +1,68 @@ +package cli_test + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "sync/atomic" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces/read" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("trace replay", func() { + It("reads every selected run without executing its command again", func() { + var requests atomic.Int64 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + requests.Add(1) + _, _ = w.Write([]byte("recorded")) + })) + DeferCleanup(upstream.Close) + targetURL := upstream.URL + "/recorded" + dataDir := GinkgoT().TempDir() + ids := []string{} + for range 2 { + run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: dataDir, Command: []string{"curl", "--noproxy", "", "-sS", targetURL}, Traces: []telltale.TraceSpec{{Kind: "http", Params: json.RawMessage(`{"target":{"seam":"proxy"}}`)}}}) + Expect(err).NotTo(HaveOccurred()) + _, err = run.Wait() + Expect(err).NotTo(HaveOccurred()) + ids = append(ids, run.ID()) + } + for _, selected := range [][]string{ids[:1], ids} { + args := append([]string{"trace", "replay", "--data-dir", dataDir, "--format", "ndjson"}, selected...) + stdout, stderr, err := execute(args...) + Expect(err).NotTo(HaveOccurred(), stderr) + rows := []read.Record{} + for _, line := range strings.Split(strings.TrimSpace(stdout), "\n") { + var record read.Record + Expect(json.Unmarshal([]byte(line), &record)).To(Succeed()) + rows = append(rows, record) + } + for _, id := range selected { + Expect(rows).To(ContainElement(And(HaveField("RunID", id), HaveField("Kind", "http"), HaveField("Record", HaveKeyWithValue("url", targetURL))))) + Expect(rows).To(ContainElement(And(HaveField("RunID", id), HaveField("Kind", "process"), HaveField("Result", "metrics")))) + } + Expect(rows).To(HaveEach(HaveField("RunID", BeElementOf(selected)))) + } + Expect(requests.Load()).To(Equal(int64(2))) + stdout, _, err := execute("trace", "replay", "--data-dir", dataDir, ids[0], "missing") + Expect(err).To(HaveOccurred()) + Expect(stdout).To(BeEmpty()) + _, _, err = execute("trace", "replay", "--data-dir", dataDir, ids[0], ids[0]) + Expect(err).To(MatchError(ContainSubstring("selected twice"))) + }) + + DescribeTable("rejects invalid replay requests", func(args []string, message string) { + _, _, err := execute(append([]string{"trace", "replay", "--data-dir", GinkgoT().TempDir()}, args...)...) + Expect(err).To(MatchError(ContainSubstring(message))) + }, + Entry("no IDs", nil, "at least 1 arg"), + Entry("unknown ID", []string{"missing"}, "get run missing"), + Entry("path traversal", []string{"../escape"}, "not a run id"), + Entry("bad sort", []string{"missing", "--sort", "invalid"}, "sort"), + ) +}) diff --git a/internal/cli/root.go b/internal/cli/root.go index 720c761..a5b0e18 100644 --- a/internal/cli/root.go +++ b/internal/cli/root.go @@ -50,7 +50,7 @@ func NewRoot(version string) *cobra.Command { serve.Flags().IntVar(&options.OTLP.MaxSpans, "otlp-max-spans", options.OTLP.MaxSpans, "Maximum spans per OTLP request") serve.Flags().IntVar(&options.OTLP.MaxInflight, "otlp-max-inflight", options.OTLP.MaxInflight, "Maximum concurrent OTLP exports across both transports") root.AddCommand(serve, newTraceCommand(), newConnectionCommand(), newRunCommand(), newTopCommand(), newRulesCommand(), newAgentsCommand()) - root.AddCommand(newRecordsCommand(), newDefinitionsCommand()) + root.AddCommand(newRecordsCommand(), newDefinitionsCommand(), newExplainCommand()) builtins, err := definition.Builtins() if err != nil { panic(err) diff --git a/internal/cli/run.go b/internal/cli/run.go index 68c98e3..29d2bda 100644 --- a/internal/cli/run.go +++ b/internal/cli/run.go @@ -2,13 +2,16 @@ package cli import ( "context" + "errors" "fmt" "strconv" "strings" + "time" "github.com/flanksource/clicky" "github.com/flanksource/clicky/api" "github.com/flanksource/telltale" + "github.com/flanksource/telltale/internal/server" "github.com/flanksource/telltale/pkg/traces" "github.com/flanksource/telltale/pkg/traces/read" "github.com/flanksource/telltale/pkg/tracing" @@ -31,7 +34,7 @@ func (f *runFlags) bind(cmd *cobra.Command, checkpointed bool) { if checkpointed { cmd.Flags().DurationVar(&f.options.Every, "every", 0, "Read the checkpointed captures this often, e.g. 10s") } - cmd.Flags().Bool("follow", false, "Print each capture's rows while recording") + bindFollow(cmd) } // newRunCommand is `run` with one subcommand per registered trace kind, each @@ -129,8 +132,25 @@ func newRunKindCommand(registration traces.Registration, plugin tracing.TracePlu // runTraced starts a run with start, waits for it and prints what it // recorded; a command that failed or a checkpoint that did is an error. func runTraced(cmd *cobra.Command, options telltale.StartOptions, start func(context.Context, telltale.StartOptions) (*telltale.Run, error)) error { + follow, tui, ui, sort, err := followOptions(cmd) + if err != nil { + return err + } + format := clicky.Flags.ResolveFormat() + if tui && format == "ndjson" { + return fmt.Errorf("--tui cannot combine with ndjson") + } + if follow && format != "ndjson" && format != "pretty" && format != "ansi" { + return fmt.Errorf("follow supports ndjson, ansi or pretty output") + } if options.Stdin == nil && options.Stdout == nil && options.Stderr == nil && options.PID == 0 { options.Stdin, options.Stdout, options.Stderr = cmd.InOrStdin(), cmd.OutOrStdout(), cmd.ErrOrStderr() + if follow && format == "ndjson" { + options.Stdout = cmd.ErrOrStderr() + } + } + if tui { + options.Stdin, options.Stdout, options.Stderr = nil, nil, nil } connections, err := telltale.OpenConnections() if err != nil { @@ -141,18 +161,49 @@ func runTraced(cmd *cobra.Command, options telltale.StartOptions, start func(con if err != nil { return err } + var viewer *server.Viewer + if ui { + viewer, err = openRunViewer(cmd, server.ViewerOptions{DataDir: options.DataDir, RunIDs: []string{started.ID()}}) + if err != nil { + return errors.Join(err, started.Stop()) + } + defer func() { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + _ = viewer.Close(ctx) + }() + } switch { case options.PID != 0: _, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Tracing pid %d into %s; Ctrl+C stops\n", options.PID, started.Dir()) // a lost notice loses nothing recorded case len(options.Command) == 0: _, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Recording the host into %s; Ctrl+C stops\n", started.Dir()) } - follow := cmd.Flags().Lookup("follow") != nil && cmd.Flags().Lookup("follow").Value.String() == "true" - result, err := read.Wait(cmd.Context(), started, follow, recordPrinter(cmd)) + var result *telltale.Result + if tui { + result, err = showTraceTUI(cmd.Context(), started, sort) + } else { + result, err = read.Wait(cmd.Context(), started, follow, func(record read.Record) error { return printTraceRecord(cmd, record) }) + } if err != nil { return err } - clicky.MustPrint(result) + if follow { + output, err := clicky.Format(result, clicky.FormatOptions{Format: "pretty"}) + if err != nil { + return err + } + if _, err := fmt.Fprintln(cmd.ErrOrStderr(), output); err != nil { + return err + } + } else { + clicky.MustPrint(result) + } + if viewer != nil { + if err := waitViewer(viewer); err != nil { + return err + } + } switch { case result.ExitCode != 0: return fmt.Errorf("%s exited with code %d", options.Command[0], result.ExitCode) diff --git a/internal/cli/run_test.go b/internal/cli/run_test.go index bd79fae..1ccb991 100644 --- a/internal/cli/run_test.go +++ b/internal/cli/run_test.go @@ -125,12 +125,12 @@ var _ = Describe("telltale run ", func() { _ = target.Wait() }) dataDir := GinkgoT().TempDir() - _, stderr, err := execute("run", "process_samples", "--data-dir", dataDir, "--pid", strconv.Itoa(target.Process.Pid), "--duration", "1s") + _, stderr, err := execute("run", "process", "--data-dir", dataDir, "--pid", strconv.Itoa(target.Process.Pid), "--duration", "1s") Expect(err).ToNot(HaveOccurred(), stderr) Expect(stderr).To(ContainSubstring("Tracing pid " + strconv.Itoa(target.Process.Pid))) result := manifest(dataDir) Expect(result.PID).To(Equal(target.Process.Pid)) - Expect(result.Captures).To(ConsistOf(HaveField("Kind", "process_samples"))) + Expect(result.Captures).To(ConsistOf(HaveField("Kind", "process"))) }) It("runs goprof and stacks against a child through the agent seam", func() { @@ -156,7 +156,7 @@ var _ = Describe("telltale run ", func() { Expect(manifest(dataDir).PID).To(Equal(os.Getpid())) }, Entry("self", "http", []string{"--seam", "self", "--features", "http"}), - Entry("host", "process_groups", nil), + Entry("host", "process", []string{"--seam", "host"}), ) DescribeTable("reports the same refusal for CLI and library runs", func(kind string, args []string, options telltale.StartOptions) { _, _, cliErr := execute(append([]string{"run", kind}, args...)...) @@ -171,11 +171,11 @@ var _ = Describe("telltale run ", func() { Entry("a command and PID", "stacks", []string{"--pid", strconv.Itoa(os.Getpid()), "--", "true"}, telltale.StartOptions{PID: os.Getpid(), Command: []string{"true"}}), ) It("shows supported seams and run attachment in help", func() { - page := help("run", "process_groups") + page := help("run", "process") Expect(page).To(ContainSubstring("--pid PID")) - Expect(page).To(ContainSubstring("supported seams: [host]")) + Expect(page).To(ContainSubstring("Supported seams: process, host")) Expect(page).NotTo(ContainSubstring("--agent")) - Expect(help("run", "process_samples")).To(ContainSubstring("--seam process")) + Expect(page).To(ContainSubstring("--seam string")) }) }) diff --git a/internal/cli/styled_replay_test.go b/internal/cli/styled_replay_test.go new file mode 100644 index 0000000..4c3462a --- /dev/null +++ b/internal/cli/styled_replay_test.go @@ -0,0 +1,41 @@ +package cli_test + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + + "github.com/flanksource/clicky" + "github.com/flanksource/telltale" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("styled replay output", func() { + It("keeps HTTP pretty-printing colors and honors no-color", func() { + GinkgoT().Setenv("CLICKY_FORCE_INTERACTIVE", "1") + GinkgoT().Setenv("TERM", "xterm-256color") + GinkgoT().Setenv("NO_COLOR", "") + GinkgoT().Setenv("COLOR", "true") + saved := *clicky.Flags + DeferCleanup(func() { *clicky.Flags = saved; clicky.UseFormatter(saved.FormatOptions) }) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { _, _ = w.Write([]byte("recorded")) })) + DeferCleanup(server.Close) + dataDir := GinkgoT().TempDir() + run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: dataDir, Command: []string{"curl", "--noproxy", "", "-sS", server.URL + "/orders"}, + Traces: []telltale.TraceSpec{{Kind: "http", Params: json.RawMessage(`{"target":{"seam":"proxy"}}`)}}}) + Expect(err).NotTo(HaveOccurred()) + _, err = run.Wait() + Expect(err).NotTo(HaveOccurred()) + stdout, stderr, err := execute("trace", "replay", run.ID(), "--data-dir", dataDir, "--format", "ansi") + Expect(err).NotTo(HaveOccurred(), stderr) + Expect(clicky.Flags.NoColor).To(BeFalse(), "explicit color environment should keep colors") + Expect(stdout).To(ContainSubstring("\x1b[")) + Expect(stdout).To(ContainSubstring("GET")) + stdout, stderr, err = execute("trace", "replay", run.ID(), "--data-dir", dataDir, "--format", "ansi", "--no-color") + Expect(err).NotTo(HaveOccurred(), stderr) + Expect(stdout).NotTo(ContainSubstring("\x1b[")) + Expect(stdout).To(ContainSubstring("GET")) + }) +}) diff --git a/internal/cli/top.go b/internal/cli/top.go index 7355b0f..0bc5377 100644 --- a/internal/cli/top.go +++ b/internal/cli/top.go @@ -16,6 +16,8 @@ import ( "github.com/flanksource/telltale/internal/topui" "github.com/flanksource/telltale/pkg/tracing/groups" "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" + "github.com/flanksource/telltale/pkg/tracing/target" "github.com/spf13/cobra" "golang.org/x/term" ) @@ -41,8 +43,8 @@ func newTopCommand() *cobra.Command { Long: "Sorts every process on the host into the tool that owns it — claude, codex, cmux, gavel, go test, vitest, agent-browser, chrome, " + "brew services and more — as a tree of groups, each with its checkout, agent session, cmux workspace and what started it, " + "and shows what each group and those under it use, full screen. The processes no tool holds are kept under other (the user's) " + - "and system (root's and the role accounts'), by program.\n\n" + - "Keys: ↑↓ move, ←→ fold, enter lists the selected group's processes, s sorts, S reverses, / filters, o shows other processes, " + + "and system (root's and the role accounts'), by program. Gavel groups add the test and lint progress and slots their process publishes.\n\n" + + "Keys: ↑↓ move, ←→ fold, enter lists the selected group's processes in the tree, f opens the process pane, s sorts, S reverses, / filters, o shows other processes, " + "b cycles grouping, n reads network bytes, q quits.\n\n" + "Nothing is kept unless --record records a run into the data dir, which `telltale trace list` and `telltale serve` show. " + "Rules come from the built-in catalog and groups.yaml in ./.telltale, else the global config dir (or --catalog).", @@ -170,9 +172,9 @@ func (f topFlags) printOnce(ctx context.Context, top *groups.Top) error { // store commits until it is stopped or its duration passes, then what it // recorded. func (f topFlags) recordRun(ctx context.Context) error { - raw, err := json.Marshal(f.params) + raw, err := json.Marshal(processcapture.Params{Options: processcapture.Options{Options: process.Options{Interval: f.params.Interval}, Catalog: f.params.Catalog, Net: f.params.Net, Facets: []string{processcapture.Files, processcapture.Sockets, "connections"}}, Target: target.Target{Seam: target.Host}}) if err != nil { - return fmt.Errorf("encode %s params: %w", groups.Kind, err) + return fmt.Errorf("encode %s params: %w", processcapture.Kind, err) } connections, err := telltale.OpenConnections() if err != nil { @@ -180,13 +182,13 @@ func (f topFlags) recordRun(ctx context.Context) error { } run, err := telltale.Start(ctx, telltale.StartOptions{ DataDir: f.dataDir, Duration: f.duration, Connections: connections, - Traces: []telltale.TraceSpec{{Kind: groups.Kind, Params: raw}}, + Traces: []telltale.TraceSpec{{Kind: processcapture.Kind, Params: raw}}, }) if err != nil { return err } if interactive() { - follower, err := groups.NewFollower(run.Runtime(), run.Info().Captures[0].Ref) + follower, err := processcapture.NewFollower(run.Runtime(), run.Info().Captures[0].Ref) if err != nil { return errors.Join(err, run.Stop()) } diff --git a/internal/cli/trace.go b/internal/cli/trace.go index 6b9e7be..2c9602b 100644 --- a/internal/cli/trace.go +++ b/internal/cli/trace.go @@ -13,7 +13,7 @@ import ( func newTraceCommand() *cobra.Command { trace := &cobra.Command{Use: "trace", Short: "Record what a command does"} - trace.AddCommand(newTraceRunCommand(), newTraceListCommand()) + trace.AddCommand(newTraceRunCommand(), newTraceListCommand(), newTraceReplayCommand()) return trace } @@ -38,7 +38,7 @@ func newTraceRunCommand() *cobra.Command { bindDataDir(run.Flags(), &options.DataDir) run.Flags().DurationVar(&options.Duration, "duration", 0, "Stop the command after this long, e.g. 30s") run.Flags().DurationVar(&options.Every, "every", 0, "Read the checkpointed captures this often, e.g. 10s") - run.Flags().Bool("follow", false, "Print each capture's rows while recording") + bindFollow(run) setHelp(run, func(cmd *cobra.Command) api.Text { return traceRunHelp(cmd).Text }) return run } diff --git a/internal/protocol/gitwire/decoder.go b/internal/protocol/gitwire/decoder.go index 777adc9..c0ea1c0 100644 --- a/internal/protocol/gitwire/decoder.go +++ b/internal/protocol/gitwire/decoder.go @@ -153,7 +153,7 @@ func objectID(s string) bool { return false } for _, c := range s { - if !(c >= '0' && c <= '9' || c >= 'a' && c <= 'f') { + if (c < '0' || c > '9') && (c < 'a' || c > 'f') { return false } } diff --git a/internal/server/feed_openapi.go b/internal/server/feed_openapi.go new file mode 100644 index 0000000..bee6d26 --- /dev/null +++ b/internal/server/feed_openapi.go @@ -0,0 +1,30 @@ +package server + +import ( + "github.com/flanksource/clicky/rpc" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/flanksource/telltale/pkg/tracing/processcapture" +) + +func addFeedPaths(spec *rpc.OpenAPISpec) { + if spec.Paths == nil { + spec.Paths = map[string]rpc.OpenAPIPath{} + } + operation := rpc.OpenAPIOperation{Summary: "Read or follow every armed capture of a run", Tags: []string{"Traces"}, Responses: map[string]rpc.OpenAPIResponse{ + "200": {Description: "Paged records, or a resumable live stream", Content: map[string]rpc.OpenAPIMediaType{ + "application/json": {Schema: rpc.SchemaForStruct(read.FeedResult{})}, + "application/x-ndjson": {Schema: &rpc.OpenAPISchema{Type: "string"}}, + "text/event-stream": {Schema: &rpc.OpenAPISchema{Type: "string"}}, + }}, "400": {Description: "Invalid selection, ordering or cursor"}, + }} + operation.Parameters = append(operation.Parameters, rpc.OpenAPIParameter{Name: "run", In: "path", Required: true, Schema: &rpc.OpenAPISchema{Type: "string"}}) + for _, name := range []string{"kind", "stream", "sort", "limit", "cursor", "follow", "format", "resume", "from", "until"} { + operation.Parameters = append(operation.Parameters, rpc.OpenAPIParameter{Name: name, In: "query", Schema: &rpc.OpenAPISchema{Type: "string"}}) + } + spec.Paths[TracesMount+"/{run}/records"] = rpc.OpenAPIPath{"get": operation} + spec.Paths[TracesMount+"/{run}/process/groups"] = rpc.OpenAPIPath{"get": rpc.OpenAPIOperation{OperationID: "recordedProcessGroups", Summary: "Derive complete process group frames from numeric observations", Parameters: []rpc.OpenAPIParameter{ + {Name: "run", In: "path", Required: true, Schema: &rpc.OpenAPISchema{Type: "string"}}, + {Name: "stream", In: "query", Required: true, Schema: &rpc.OpenAPISchema{Type: "string"}}, + {Name: "afterSeq", In: "query", Schema: &rpc.OpenAPISchema{Type: "integer"}}, + }, Responses: map[string]rpc.OpenAPIResponse{"200": {Description: "Group frames derived from one atomic process metrics stream", Content: map[string]rpc.OpenAPIMediaType{"application/json": {Schema: rpc.SchemaForStruct(processcapture.Frames{})}}}, "400": {Description: "Invalid process capture or sequence"}}}} +} diff --git a/internal/server/handler.go b/internal/server/handler.go index 14cce0e..55e9fe2 100644 --- a/internal/server/handler.go +++ b/internal/server/handler.go @@ -63,7 +63,7 @@ func routes(options HandlerOptions, ui http.Handler) (http.Handler, error) { } api := http.NewServeMux() rpc.NewSwaggerServer(&rpc.ServeConfig{Version: options.Version}, options.Root, - &rpc.OpenAPIConfig{Title: "Telltale", Version: options.Version, Extensions: []func(*rpc.OpenAPISpec){addRulesPaths, connections.AddConnectionsOpenAPI, addConnectionPaths, addOtelPaths, addReceiverPath}}).RegisterRoutes(route.NewRouter(api)) + &rpc.OpenAPIConfig{Title: "Telltale", Version: options.Version, Extensions: []func(*rpc.OpenAPISpec){addRulesPaths, connections.AddConnectionsOpenAPI, addConnectionPaths, addOtelPaths, addReceiverPath, addFeedPaths}}).RegisterRoutes(route.NewRouter(api)) root := http.NewServeMux() if options.OTLP == nil { options.OTLP = http.NotFoundHandler() @@ -85,6 +85,8 @@ func routes(options HandlerOptions, ui http.Handler) (http.Handler, error) { root.Handle(TracesMount, options.Traces) root.Handle(TracesMount+"/", options.Traces) root.Handle("GET "+TracesMount+"/{run}/traces/{kind}/records", records.Handler(options.DataDir)) + root.Handle("GET "+TracesMount+"/{run}/records", records.FeedHandler(options.DataDir)) + root.Handle("GET "+TracesMount+"/{run}/process/groups", records.ProcessGroupsHandler(options.DataDir)) root.Handle(TopMount, options.Top) root.Handle(TopProcessesPath, options.Top) root.Handle(TopFacetsPath, options.Top) diff --git a/internal/server/viewer.go b/internal/server/viewer.go new file mode 100644 index 0000000..20c5b1e --- /dev/null +++ b/internal/server/viewer.go @@ -0,0 +1,111 @@ +package server + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io/fs" + "net" + "net/http" + "net/url" + "sync" + "time" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traceserve/records" + "github.com/flanksource/telltale/webapp" +) + +type Viewer struct { + closeOnce sync.Once + closeErr error + URL string + listener net.Listener + server *http.Server + done chan error +} + +type ViewerOptions struct { + DataDir string + RunIDs []string +} + +// StartViewer exposes only the selected runs' records and the shared frontend. +func StartViewer(options ViewerOptions) (*Viewer, error) { + if len(options.RunIDs) == 0 { + return nil, fmt.Errorf("trace viewer requires at least one run ID") + } + allowed := map[string]bool{} + for _, id := range options.RunIDs { + if allowed[id] { + return nil, fmt.Errorf("run %q selected twice", id) + } + info, err := telltale.Get(telltale.GetOptions{DataDir: options.DataDir, RunID: id}) + if err != nil { + return nil, err + } + if info.Unavailable != "" { + return nil, fmt.Errorf("view run %s: %s", id, info.Unavailable) + } + allowed[id] = true + } + assets, err := webapp.Assets() + if err != nil { + return nil, err + } + if _, err := fs.ReadFile(assets, "index.html"); err != nil { + return nil, err + } + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + return nil, err + } + mux := http.NewServeMux() + feed := records.FeedHandler(options.DataDir) + mux.HandleFunc("GET /api/traces/{run}/records", func(w http.ResponseWriter, r *http.Request) { + if !allowed[r.PathValue("run")] { + http.NotFound(w, r) + return + } + feed.ServeHTTP(w, r) + }) + mux.HandleFunc("GET /api/traces", func(w http.ResponseWriter, r *http.Request) { + runs := []telltale.MountedRun{} + for _, id := range options.RunIDs { + info, err := telltale.Get(telltale.GetOptions{DataDir: options.DataDir, RunID: id}) + if err != nil { + http.Error(w, err.Error(), 500) + return + } + runs = append(runs, telltale.MountedRun{RunInfo: info, Mount: TracesMount + "/" + id}) + } + w.Header().Set("Content-Type", "application/json") + if err := json.NewEncoder(w).Encode(telltale.RunsList{Runs: runs}); err != nil { + panic(http.ErrAbortHandler) + } + }) + mux.HandleFunc("/api/", http.NotFound) + mux.Handle("/", assetHandler(assets)) + params := url.Values{"viewer": {"1"}, "run": {options.RunIDs[0]}} + viewer := &Viewer{URL: "http://" + listener.Addr().String() + "/?" + params.Encode(), listener: listener, server: &http.Server{Handler: mux, ReadHeaderTimeout: 10 * time.Second, ReadTimeout: 30 * time.Second, IdleTimeout: time.Minute}, done: make(chan error, 1)} + go func() { + err := viewer.server.Serve(listener) + if errors.Is(err, http.ErrServerClosed) { + err = nil + } + viewer.done <- err + }() + return viewer, nil +} + +func (v *Viewer) Close(ctx context.Context) error { + v.closeOnce.Do(func() { + v.closeErr = v.server.Shutdown(ctx) + if v.closeErr != nil { + v.closeErr = errors.Join(v.closeErr, v.server.Close()) + } + v.closeErr = errors.Join(v.closeErr, <-v.done) + }) + return v.closeErr +} diff --git a/internal/server/viewer_test.go b/internal/server/viewer_test.go new file mode 100644 index 0000000..8927bea --- /dev/null +++ b/internal/server/viewer_test.go @@ -0,0 +1,55 @@ +package server_test + +import ( + "context" + "encoding/json" + "net/http" + "net/url" + "os" + "path/filepath" + "time" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/internal/server" + "github.com/flanksource/telltale/pkg/traces" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("trace replay viewer", func() { + It("lists and serves only the selected runs", func() { + dataDir := GinkgoT().TempDir() + ids := []string{"first", "second", "unselected"} + for _, id := range ids { + dir := traces.StoreDir(dataDir, id) + Expect(os.MkdirAll(dir, 0o755)).To(Succeed()) + data, err := json.Marshal(telltale.Result{RunID: id, Dir: dir, StartedAt: time.Now(), EndedAt: time.Now()}) + Expect(err).NotTo(HaveOccurred()) + Expect(os.WriteFile(filepath.Join(dir, telltale.ManifestFile), data, 0o600)).To(Succeed()) + } + viewer, err := server.StartViewer(server.ViewerOptions{DataDir: dataDir, RunIDs: ids[:2]}) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(func() { Expect(viewer.Close(context.Background())).To(Succeed()) }) + address, err := url.Parse(viewer.URL) + Expect(err).NotTo(HaveOccurred()) + base := address.Scheme + "://" + address.Host + response, err := http.Get(base + "/api/traces") + Expect(err).NotTo(HaveOccurred()) + var listed telltale.RunsList + Expect(json.NewDecoder(response.Body).Decode(&listed)).To(Succeed()) + Expect(response.Body.Close()).To(Succeed()) + Expect(listed.Runs).To(HaveExactElements(HaveField("RunID", ids[0]), HaveField("RunID", ids[1]))) + for _, path := range []string{"/api/traces/unselected/records", "/api/traces/start", "/api/v1/trace/run"} { + response, err := http.Get(base + path) + Expect(err).NotTo(HaveOccurred()) + Expect(response.StatusCode).To(Equal(http.StatusNotFound), path) + Expect(response.Body.Close()).To(Succeed()) + } + for _, id := range ids[:2] { + response, err := http.Get(base + "/api/traces/" + id + "/records") + Expect(err).NotTo(HaveOccurred()) + Expect(response.StatusCode).To(Equal(http.StatusOK)) + Expect(response.Body.Close()).To(Succeed()) + } + }) +}) diff --git a/internal/terminalui/styles.go b/internal/terminalui/styles.go new file mode 100644 index 0000000..636bdd4 --- /dev/null +++ b/internal/terminalui/styles.go @@ -0,0 +1,8 @@ +// Package terminalui holds the common visual language of Telltale's terminal monitors. +package terminalui + +import "charm.land/lipgloss/v2" + +var Title = lipgloss.NewStyle().Bold(true) +var Muted = lipgloss.NewStyle().Foreground(lipgloss.Color("244")) +var Selected = lipgloss.NewStyle().Reverse(true) diff --git a/internal/topui/actions.go b/internal/topui/actions.go index b2999a7..221c2c6 100644 --- a/internal/topui/actions.go +++ b/internal/topui/actions.go @@ -23,6 +23,19 @@ func (m Model) cpuHog(cpu *float64) bool { return cpu != nil && m.frame != nil && m.frame.Host != nil && m.frame.Host.Cores > 0 && *cpu > 25*float64(m.frame.Host.Cores) } +func (m Model) hogLabel(usage groups.Usage) string { + if m.frame == nil { + return "" + } + if label := usage.Hogs.Label(m.frame.SampledAt); label != "" { + return label + } + if m.cpuHog(usage.CPUPercent) { + return "CPU hog" + } + return "" +} + func (m *Model) cycleProcess(key string) { processes, _ := m.selectedProcesses() if len(processes) == 0 { diff --git a/internal/topui/grouping_test.go b/internal/topui/grouping_test.go index 2929d12..21ab431 100644 --- a/internal/topui/grouping_test.go +++ b/internal/topui/grouping_test.go @@ -41,6 +41,9 @@ var _ = Describe("Model grouping", func() { m = press(m, "left") Expect(shown(m)).NotTo(ContainElement("agent-a")) m = press(m, "right", "b", "b", "b") + Expect(m.groupBy).To(Equal(groups.GroupSlots)) + m = press(m, "b") + Expect(m.groupBy).To(Equal(groups.GroupTree)) Expect(m.frame.Groups).To(HaveLen(len(fixture.Frame.Groups))) Expect(m.frame.Groups).NotTo(ContainElement(HaveField("Kind", groups.KindBucket))) }) diff --git a/internal/topui/memory_test.go b/internal/topui/memory_test.go new file mode 100644 index 0000000..1955688 --- /dev/null +++ b/internal/topui/memory_test.go @@ -0,0 +1,48 @@ +package topui + +import ( + "context" + "time" + + "github.com/flanksource/telltale/pkg/tracing/groups" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("memory columns and pins", func() { + It("shows compressed memory separately from unavailable swap and pins a quiet recent hog", func() { + frame := testFrame + hogs := groups.Hogs{"memory": frame.SampledAt.Add(groups.HogRetention)} + frame.Groups = []groups.GroupSample{ + sample("busy", "", "busy", groups.KindTool, 100, 100<<20), + {Key: "hog", Name: "worker", Kind: groups.KindTool, Total: groups.Usage{Processes: 1, CompressedBytes: new(uint64(512 << 20)), Hogs: hogs}}, + } + m := New(context.Background(), Options{Source: &fakeSource{}, Every: time.Second, Order: groups.Order{By: groups.SortCPU}}) + m.width, m.height = 200, 40 + next, _ := m.Update(frameMsg{frame: frame, ok: true}) + m = next.(Model) + Expect(m.rows()[0].group.Key).To(Equal("hog")) + Expect(m.render()).To(SatisfyAll(ContainSubstring("CMPRS"), ContainSubstring("SWAP"), ContainSubstring("512.0M"), ContainSubstring("memory hog"))) + m = press(m, "S") + Expect(m.rows()[0].group.Key).To(Equal("hog")) + frame.SampledAt = frame.SampledAt.Add(120 * time.Second) + next, _ = m.Update(frameMsg{frame: frame, ok: true}) + m = press(next.(Model), "S") + Expect(m.rows()[0].group.Key).To(Equal("busy")) + }) + + It("orders the selected group's recent hog before a busier process", func() { + m := New(context.Background(), Options{Every: time.Second, Order: groups.Order{By: groups.SortCPU}}) + m.width, m.height = 200, 40 + m.source = &fakeSource{keeps: true, processes: map[string][]groups.ProcessSample{ + "10": { + {Key: "busy@1", Usage: groups.Usage{CPUPercent: percent(100)}}, + {Key: "hog@1", Usage: groups.Usage{Hogs: groups.Hogs{"swap": testFrame.SampledAt.Add(groups.HogRetention)}}}, + }, + }} + next, _ := m.Update(frameMsg{frame: testFrame, ok: true}) + processes, kept := next.(Model).selectedProcesses() + Expect(kept).To(BeTrue()) + Expect(processes[0].Key).To(Equal("hog@1")) + }) +}) diff --git a/internal/topui/model.go b/internal/topui/model.go index f5456af..aee1fa9 100644 --- a/internal/topui/model.go +++ b/internal/topui/model.go @@ -41,20 +41,22 @@ type Options struct { // Model is the view's state: the latest frame, the selected group and how // the tree is folded, filtered and sorted. type Model struct { - ctx context.Context - options Options - source Source - toggles Toggles - order groups.Order - gen int - frame *groups.Frame - raw *groups.Frame - groupBy groups.GroupBy - width int - height int - selected string - offset int - folded map[string]bool + ctx context.Context + options Options + source Source + toggles Toggles + order groups.Order + gen int + frame *groups.Frame + raw *groups.Frame + groupBy groups.GroupBy + width int + height int + selected string + offset int + folded map[string]bool + // expanded are the groups whose member processes the tree lists. + expanded map[string]bool query string typing bool detail bool @@ -74,7 +76,7 @@ func New(ctx context.Context, options Options) Model { return Model{ ctx: ctx, options: options, source: options.Source, toggles: options.Toggles, order: options.Order, groupBy: options.GroupBy, - folded: map[string]bool{}, + folded: map[string]bool{}, expanded: map[string]bool{}, } } @@ -203,7 +205,9 @@ func (m Model) pressed(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) { m.fold(rows, index, !rows[index].folded) } case tea.KeyEnter: - m.detail = !m.detail + if index >= 0 { + m.toggleExpanded(rows[index]) + } case tea.KeyEscape: m.detail, m.query = false, "" default: @@ -218,6 +222,8 @@ func (m Model) command(key string) (tea.Model, tea.Cmd) { switch key { case "q": return m, tea.Quit + case "f": + m.detail = !m.detail case "[", "]": m.cycleProcess(key) case "x", "r": @@ -260,7 +266,7 @@ func (m Model) typed(msg tea.KeyPressMsg) Model { m.query += msg.Text } if rows := m.rows(); m.selectedIndex(rows) < 0 && len(rows) > 0 { - m.selected = rows[0].group.Key + m.selected = rows[0].key } m.scroll() return m @@ -275,14 +281,14 @@ func (m *Model) resort() { m.err, m.status = err, err.Error() return } - sorted, err := projected.Sorted(m.order) + sorted, err := projected.WithGavelTasks().Sorted(m.order) if err != nil { m.err, m.status = err, err.Error() return } m.frame = &sorted if rows := m.rows(); m.selectedIndex(rows) < 0 && len(rows) > 0 { - m.selected = rows[0].group.Key + m.selected = rows[0].key } } @@ -308,14 +314,23 @@ func (m Model) reopen(toggles Toggles) (tea.Model, tea.Cmd) { return m, m.read() } -// row is a group as the tree shows it. +// row is a group, or one of an expanded group's processes, as the tree +// shows it. key and parentKey are the tree's: a group's own, or +// proc: under the row its process nests in. type row struct { - group groups.GroupSample - depth int - parent bool - folded bool + group groups.GroupSample + // process is set on a process row; group is then the group it belongs to. + process *groups.ProcessSample + // detached marks a process whose parent is outside its group. + detached bool + key, parentKey string + depth int + parent bool + folded bool } +const processPrefix = "proc:" + func (m Model) matchingGroups() []groups.GroupSample { if m.frame == nil { return nil @@ -360,6 +375,7 @@ func (m Model) rows() []row { for _, group := range displayed { parents[group.ParentKey] = true } + under := m.processesUnder(displayed) var rows []row depth := map[string]int{} hidden := map[string]bool{} @@ -369,25 +385,138 @@ func (m Model) rows() []row { level++ } depth[group.Key] = level - folded := m.isFolded(group, parents[group.Key]) if hidden[group.ParentKey] { hidden[group.Key] = true continue } + processes := under[group.Key] + parent := parents[group.Key] || len(processes) > 0 + folded := m.isFolded(group.Key, group, parent) hidden[group.Key] = folded - rows = append(rows, row{group: group, depth: level, parent: parents[group.Key], folded: folded}) + rows = append(rows, row{group: group, key: group.Key, parentKey: group.ParentKey, depth: level, parent: parent, folded: folded}) + if !folded { + for _, process := range m.foldProcesses(processes) { + process.depth += level + 1 + rows = append(rows, process) + } + } } return rows } -func (m Model) isFolded(group groups.GroupSample, parent bool) bool { +// foldProcesses drops the process rows under a folded process row. +func (m Model) foldProcesses(processes []row) []row { + var shown []row + hidden := map[string]bool{} + for _, r := range processes { + if hidden[r.parentKey] { + hidden[r.key] = true + continue + } + r.folded = m.isFolded(r.key, r.group, r.parent) + hidden[r.key] = r.folded + shown = append(shown, r) + } + return shown +} + +func (m Model) isFolded(key string, group groups.GroupSample, parent bool) bool { if !parent || m.query != "" { return false } - if folded, ok := m.folded[group.Key]; ok { + if folded, ok := m.folded[key]; ok { return folded } - return group.Kind == groups.KindOther + return group.Kind == groups.KindOther && !group.Total.Hogs.Pinned(m.frame.SampledAt) +} + +// toggleExpanded lists or hides the member processes of r's group, or of +// the group a process row belongs to. +func (m *Model) toggleExpanded(r row) { + key := r.group.Key + if r.group.Task != nil || r.group.Kind == groups.KindBucket { + m.status = "enter lists a group's processes; f shows them all below" + return + } + if _, kept := m.source.Processes(groups.ProcessFilter{GroupKey: key}); !kept { + m.status = "A recording keeps each group's use, not its processes." + return + } + m.expanded[key] = !m.expanded[key] + if !m.expanded[key] && r.process != nil { + m.selected = key + } +} + +// processesUnder are the expanded groups' member processes as rows, by the +// key of the row each subtree nests under, their depths counted from it. +// A group's anchor is the group's own row; a member a gavel task runs, and +// the members under it, nest under that task's row. +func (m Model) processesUnder(displayed []groups.GroupSample) map[string][]row { + under := map[string][]row{} + for _, group := range displayed { + if !m.expanded[group.Key] || group.Task != nil || group.Kind == groups.KindBucket { + continue + } + members, _ := m.source.Processes(groups.ProcessFilter{GroupKey: group.Key}) + claims := map[int]string{} + for _, task := range displayed { + if task.Task != nil && task.Task.Item != nil && task.Task.Item.PID > 0 && strings.HasPrefix(task.Key, group.Key+"/") { + claims[task.Task.Item.PID] = task.Key + } + } + for key, rows := range processRows(group, members, claims) { + under[key] = append(under[key], rows...) + } + } + return under +} + +// processRows nests members by parent pid: the anchor's children under the +// group, a claimed process (and those under it) under its task's row, and a +// process whose parent is outside the group directly under it, detached. +// Siblings come busiest first. +func processRows(group groups.GroupSample, members []groups.ProcessSample, claims map[int]string) map[string][]row { + byPID := map[int]groups.ProcessSample{} + for _, p := range members { + if p.PID != group.PID { + byPID[p.PID] = p + } + } + children := map[int][]groups.ProcessSample{} + var roots []groups.ProcessSample + for _, p := range byPID { + if _, ok := byPID[p.PPID]; ok && claims[p.PID] == "" { + children[p.PPID] = append(children[p.PPID], p) + } else { + roots = append(roots, p) + } + } + busiest := func(processes []groups.ProcessSample) { + slices.SortFunc(processes, func(a, b groups.ProcessSample) int { + return cmp.Or(cmp.Compare(cpuOf(b.Usage), cpuOf(a.Usage)), cmp.Compare(a.PID, b.PID)) + }) + } + under := map[string][]row{} + var walk func(owner string, p groups.ProcessSample, parentKey string, depth int, detached bool) + walk = func(owner string, p groups.ProcessSample, parentKey string, depth int, detached bool) { + process := p + key := processPrefix + p.Key + under[owner] = append(under[owner], row{group: group, process: &process, detached: detached, key: key, parentKey: parentKey, depth: depth, parent: len(children[p.PID]) > 0}) + busiest(children[p.PID]) + for _, child := range children[p.PID] { + walk(owner, child, key, depth+1, false) + } + } + busiest(roots) + for _, p := range roots { + if task := claims[p.PID]; task != "" { + walk(task, p, task, 0, false) + continue + } + walk(group.Key, p, group.Key, 0, p.PPID != group.PID) + } + return under } func matches(group groups.GroupSample, query string) bool { @@ -400,14 +529,20 @@ func matches(group groups.GroupSample, query string) bool { } func (m Model) selectedIndex(rows []row) int { - return slices.IndexFunc(rows, func(r row) bool { return r.group.Key == m.selected }) + return slices.IndexFunc(rows, func(r row) bool { return r.key == m.selected }) } +// selectAt selects the row at index; a process row also chooses its +// process for x and r. func (m *Model) selectAt(rows []row, index int) { if len(rows) == 0 { return } - m.selected = rows[max(0, min(index, len(rows)-1))].group.Key + r := rows[max(0, min(index, len(rows)-1))] + m.selected = r.key + if r.process != nil { + m.processKey = r.process.Key + } } // fold folds or unfolds the selected group; folding a group that holds @@ -418,11 +553,11 @@ func (m *Model) fold(rows []row, index int, fold bool) { } current := rows[index] if current.parent && current.folded != fold { - m.folded[current.group.Key] = fold + m.folded[current.key] = fold return } - if fold && current.group.ParentKey != "" && slices.ContainsFunc(rows, func(r row) bool { return r.group.Key == current.group.ParentKey }) { - m.selected = current.group.ParentKey + if fold && current.parentKey != "" && slices.ContainsFunc(rows, func(r row) bool { return r.key == current.parentKey }) { + m.selected = current.parentKey } } @@ -446,6 +581,13 @@ func (m Model) selectedProcesses() ([]groups.ProcessSample, bool) { if m.frame == nil || m.selected == "" { return nil, true } + if strings.HasPrefix(m.selected, processPrefix) { + rows := m.rows() + if index := m.selectedIndex(rows); index >= 0 { + return []groups.ProcessSample{*rows[index].process}, true + } + return nil, true + } under := map[string]bool{m.selected: true} var processes []groups.ProcessSample for _, group := range m.matchingGroups() { @@ -462,7 +604,15 @@ func (m Model) selectedProcesses() ([]groups.ProcessSample, bool) { } processes = append(processes, read...) } - slices.SortStableFunc(processes, func(a, b groups.ProcessSample) int { return cmp.Compare(cpuOf(b.Usage), cpuOf(a.Usage)) }) + slices.SortStableFunc(processes, func(a, b groups.ProcessSample) int { + if a.Hogs.Pinned(m.frame.SampledAt) != b.Hogs.Pinned(m.frame.SampledAt) { + if a.Hogs.Pinned(m.frame.SampledAt) { + return -1 + } + return 1 + } + return cmp.Compare(cpuOf(b.Usage), cpuOf(a.Usage)) + }) return processes, true } diff --git a/internal/topui/model_test.go b/internal/topui/model_test.go index 9acb721..8e40e8d 100644 --- a/internal/topui/model_test.go +++ b/internal/topui/model_test.go @@ -3,11 +3,14 @@ package topui import ( "context" "errors" + "fmt" + "slices" "strings" "time" tea "charm.land/bubbletea/v2" "charm.land/lipgloss/v2" + "github.com/flanksource/gavel/sdk/status" "github.com/flanksource/telltale/pkg/tracing/groups" "github.com/flanksource/telltale/pkg/tracing/process" . "github.com/onsi/ginkgo/v2" @@ -123,8 +126,8 @@ var _ = Describe("Model", func() { newModel := func(width, height int) Model { GinkgoHelper() source = &fakeSource{keeps: true, processes: map[string][]groups.ProcessSample{ - "11": {{PID: 1101, Name: "gavel", Command: "gavel test ./...", Usage: groups.Usage{Processes: 1, CPUPercent: percent(30)}}}, - "12": {{PID: 1201, Name: "node", Command: "node vitest", Usage: groups.Usage{Processes: 1, CPUPercent: percent(5)}}}, + "11": {{Key: "1101@1", PID: 1101, Name: "gavel", Command: "gavel test ./...", Usage: groups.Usage{Processes: 1, CPUPercent: percent(30)}}}, + "12": {{Key: "1201@1", PID: 1201, Name: "node", Command: "node vitest", Usage: groups.Usage{Processes: 1, CPUPercent: percent(5)}}}, }} reopened = nil m := New(context.Background(), Options{ @@ -195,14 +198,110 @@ var _ = Describe("Model", func() { Expect(shown(m)).To(HaveLen(5)) }) - It("lists the processes of the selected group and those under it, busiest first", func() { - m := press(newModel(160, 40), "enter") + It("lists the processes of the selected group and those under it, busiest first, in the pane f opens", func() { + m := press(newModel(160, 40), "f") processes, kept := m.selectedProcesses() Expect(kept).To(BeTrue()) Expect(processes).To(HaveLen(2)) Expect(processes[0].PID).To(Equal(1101)) - Expect(m.render()).To(ContainSubstring("gavel test ./...")) + screen := m.render() + Expect(screen).To(ContainSubstring("gavel test ./...")) + Expect(screen).To(ContainSubstring("── claude · 2 processes ─")) + Expect(screen).NotTo(ContainSubstring("─…"), "the pane's rule fits the width") + }) + + It("lists a group's member processes in the tree on enter, nested by parent, a detached one under the group", func() { + m := newModel(200, 40) + frame := *m.raw + frame.Groups = append([]groups.GroupSample(nil), frame.Groups...) + frame.Groups[2].PID = 1200 + source.processes["12"] = []groups.ProcessSample{ + {Key: "1200@1", PID: 1200, PPID: 1100, Command: "/usr/local/bin/vitest run", Usage: groups.Usage{Processes: 1}}, + {Key: "1201@1", PID: 1201, PPID: 1200, Command: "/opt/node/bin/node worker.js", Usage: groups.Usage{Processes: 1, CPUPercent: percent(4)}}, + {Key: "1202@1", PID: 1202, PPID: 1201, Command: "/opt/node/bin/node esbuild", Usage: groups.Usage{Processes: 1}}, + {Key: "1203@1", PID: 1203, PPID: 1, Command: "/Applications/Acme.app/Contents/MacOS/Acme Helper (Renderer) --type=renderer", Usage: groups.Usage{Processes: 1}}, + } + next, _ := m.Update(frameMsg{frame: frame, ok: true}) + m = press(next.(Model), "down", "down", "enter") + Expect(m.selected).To(Equal("12")) + + var tree []string + for _, r := range m.rows() { + if r.process != nil { + tree = append(tree, fmt.Sprintf("%d:%d:%t", r.process.PID, r.depth, r.detached)) + } + } + Expect(tree).To(Equal([]string{"1201:2:false", "1202:3:false", "1203:2:true"}), "the anchor is the group's own row") + Expect(m.render()).To(SatisfyAll( + ContainSubstring("1201 node worker.js"), + ContainSubstring("↰ 1203 Acme Helper (Renderer) --type=renderer"), + )) + Expect(m.detail).To(BeFalse(), "enter lists processes in the tree, not the pane") + + m = press(m, "enter") + Expect(slices.ContainsFunc(m.rows(), func(r row) bool { return r.process != nil })).To(BeFalse()) + }) + + It("chooses a process row's process for x", func() { + m := press(newModel(200, 40), "down", "enter", "down") + Expect(m.rows()[m.selectedIndex(m.rows())].process).NotTo(BeNil()) + Expect(m.processKey).To(Equal("1101@1"), "selecting the row chooses its process") + processes, _ := m.selectedProcesses() + Expect(processes).To(ConsistOf(HaveField("PID", 1101))) + }) + + It("nests a gavel's task groups and running tasks under it, and the process a task runs under its task", func() { + frame := testFrame + frame.Groups = append([]groups.GroupSample(nil), testFrame.Groups...) + frame.Groups[1].SkipAncestry, frame.Groups[1].PID = true, 1100 + frame.Groups[1].Gavel = &status.Status{ + Groups: []status.Group{{Name: "Running linters", Kind: status.GroupLint, Summary: status.Summary{Total: 7, Passed: 2, Failed: 1, Running: 4}}}, + Running: []status.Item{{Name: "golangci-lint run ./...", Group: "Running linters", PID: 1102, Started: frame.SampledAt.Add(-42 * time.Second)}}, + Slots: []status.Lease{{Pool: "global", Limit: 4, Index: 1, State: status.LeaseHeld, Since: frame.SampledAt.Add(-time.Minute), Command: "golangci-lint run ./..."}}, + } + frame.Slots = []groups.SlotPool{{Name: "global", Limit: 4, Held: 1}} + m := newModel(200, 40) + source.processes["11"] = append(source.processes["11"], + groups.ProcessSample{Key: "1102@1", PID: 1102, PPID: 1101, Name: "golangci-lint", Command: "/opt/bin/golangci-lint run ./...", Usage: groups.Usage{Processes: 1, CPUPercent: percent(80)}}) + next, _ := m.Update(frameMsg{frame: frame, ok: true}) + m = next.(Model) + + Expect(strings.Split(m.render(), "\n")[headerLines-1]).To(ContainSubstring("SLT gavel global [██░░░░░░] 1/4")) + depths := map[string]int{} + for _, r := range m.rows() { + depths[r.key] = r.depth + } + Expect(depths).To(HaveKeyWithValue("11", 1)) + Expect(depths).To(HaveKeyWithValue("11/gavel/lint", 2)) + Expect(depths).To(HaveKeyWithValue("11/gavel/lint/0", 3)) + // 2 passed → 2 cells █, 1 failed → 1 ▓, 4 running → the other 5 ▒. + Expect(m.render()).To(SatisfyAll( + ContainSubstring("gavel ●global"), + ContainSubstring(" ▾ lint [██▓▒▒▒▒▒] 3/7 ✗1"), + ContainSubstring(" ▶ golangci-lint run ./... 42s"), + )) + + m = press(m, "down", "enter") + Expect(m.selected).To(Equal("11")) + Expect(depths).NotTo(HaveKey("proc:1102@1")) + for _, r := range m.rows() { + depths[r.key] = r.depth + } + Expect(depths).To(HaveKeyWithValue("proc:1102@1", 4), "the task's process nests under its task row") + Expect(depths).To(HaveKeyWithValue("proc:1101@1", 2)) + Expect(m.render()).NotTo(ContainSubstring("3/7 done"), "the pane no longer repeats the progress") + + m.selected = "11/gavel/lint" + m = press(m, "left") + Expect(slices.ContainsFunc(m.rows(), func(r row) bool { return r.key == "11/gavel/lint/0" })).To(BeFalse(), "← folds the lint row's tasks") + }) + + It("refuses to list processes in the tree from a recording", func() { + m := newModel(160, 40) + source.keeps = false + m = press(m, "enter") + Expect(m.status).To(ContainSubstring("A recording keeps each group's use")) }) It("reads from a new source with a flipped toggle, closing the old one", func() { diff --git a/internal/topui/source.go b/internal/topui/source.go index 68f2af6..8fbf818 100644 --- a/internal/topui/source.go +++ b/internal/topui/source.go @@ -7,6 +7,7 @@ import ( "context" "github.com/flanksource/telltale/pkg/tracing/groups" + "github.com/flanksource/telltale/pkg/tracing/processcapture" ) // Source reads the frames a Model shows. @@ -38,13 +39,15 @@ func (l Live) Close() { l.Top.Close() } // Recorded follows a recording's committed frames, which keep no processes. type Recorded struct { - Follower *groups.Follower + Follower *processcapture.Follower } func (r Recorded) Next(ctx context.Context) (groups.Frame, bool, error) { return r.Follower.Frame(ctx) } -func (Recorded) Processes(groups.ProcessFilter) ([]groups.ProcessSample, bool) { return nil, false } +func (r Recorded) Processes(filter groups.ProcessFilter) ([]groups.ProcessSample, bool) { + return r.Follower.Processes(filter), true +} func (Recorded) Close() {} diff --git a/internal/topui/view.go b/internal/topui/view.go index 61f22a9..4c8ff6c 100644 --- a/internal/topui/view.go +++ b/internal/topui/view.go @@ -6,18 +6,19 @@ import ( tea "charm.land/bubbletea/v2" "charm.land/lipgloss/v2" + "github.com/flanksource/telltale/internal/terminalui" "github.com/flanksource/telltale/pkg/tracing/groups" ) -// headerLines are the title, CPU, memory, swap and disk lines above the -// table. -const headerLines = 5 +// headerLines are the title, CPU, memory, swap, disk and gavel slots lines +// above the table. +const headerLines = 6 var ( - titleStyle = lipgloss.NewStyle().Bold(true) + titleStyle = terminalui.Title headStyle = lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("244")) - mutedStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("244")) - selectedStyle = lipgloss.NewStyle().Reverse(true) + mutedStyle = terminalui.Muted + selectedStyle = terminalui.Selected statusStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("208")) userStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("39")) kernelStyle = lipgloss.NewStyle().Foreground(lipgloss.Color("203")) @@ -116,7 +117,11 @@ func (m Model) header() []string { } disks := fmt.Sprintf("DSK read %s IOPS %s/s · write %s IOPS %s/s", ops(host.ReadOps), groups.Rate(host.ReadBps), ops(host.WriteOps), groups.Rate(host.WriteBps)) - return []string{titleStyle.Render(fit(title, m.width)), clip(cpu, m.width), clip(memory, m.width), clip(swap, m.width), clip(disks, m.width)} + slots := "SLT " + mutedStyle.Render("no gavel slot held or awaited") + if len(m.frame.Slots) > 0 { + slots = "SLT gavel " + groups.SlotsText(m.frame.Slots) + } + return []string{titleStyle.Render(fit(title, m.width)), clip(cpu, m.width), clip(memory, m.width), clip(swap, m.width), clip(disks, m.width), clip(slots, m.width)} } // ops is a known operations rate, in thousands from a thousand, or "-". @@ -170,7 +175,7 @@ type columns struct { origin, context int } -const fixedWidth = 6 + 7 + 8 + 9 + 9 + 9 + 9 + 6 +const fixedWidth = 6 + 7 + 8 + 8 + 8 + 9 + 9 + 9 + 9 + 6 func layout(width int) columns { c := columns{} @@ -185,11 +190,11 @@ func layout(width int) columns { } func (c columns) head() string { - return c.line("GROUP", "PROCS", "CPU%", "RSS", "DISK R/s", "DISK W/s", "NET IN/s", "NET OUT/s", "SOCK", "ORIGIN", "CONTEXT") + return c.line("GROUP", "PROCS", "CPU%", "RSS", "CMPRS", "SWAP", "DISK R/s", "DISK W/s", "NET IN/s", "NET OUT/s", "SOCK", "ORIGIN", "CONTEXT") } -func (c columns) line(name, procs, cpu, rss, diskRead, diskWrite, netIn, netOut, sockets, origin, context string) string { - text := fmt.Sprintf("%-*s%6s%7s%8s%9s%9s%9s%9s%6s", c.name, groups.Truncate(name, c.name-1), procs, cpu, rss, diskRead, diskWrite, netIn, netOut, sockets) +func (c columns) line(name, procs, cpu, rss, compressed, swap, diskRead, diskWrite, netIn, netOut, sockets, origin, context string) string { + text := fmt.Sprintf("%-*s%6s%7s%8s%8s%8s%9s%9s%9s%9s%6s", c.name, groups.Truncate(name, c.name-1), procs, cpu, rss, compressed, swap, diskRead, diskWrite, netIn, netOut, sockets) if c.origin > 0 { text += fmt.Sprintf(" %-*s", c.origin-2, groups.Truncate(origin, c.origin-2)) } @@ -207,18 +212,43 @@ func (m Model) renderRow(c columns, r row) string { glyph = "▸ " } } - usage := r.group.Total - label := groups.Label(r.group) - if m.cpuHog(usage.CPUPercent) { - label = "! CPU hog · " + label + usage, label, procs := r.group.Total, groups.Label(r.group), fmt.Sprint(r.group.Total.Processes) + origin, context := groups.OriginText(r.group.Origin), groups.ContextText(r.group.Context) + switch { + case r.process != nil: + usage, label, procs = r.process.Usage, fmt.Sprintf("%d %s", r.process.PID, groups.ShortCommand(r.process.Command)), "" + origin, context = groups.OriginText(r.process.Origin), "" + if r.detached { + label = "↰ " + label + } + case r.group.Task != nil: + label, context = groups.TaskText(r.group, m.frame.SampledAt), "" + if usage.Processes == 0 { + procs = "" + } + default: + if slots := groups.SlotGlyphs(r.group.Gavel); slots != "" { + label += " " + slots + } + if r.group.GavelError != "" { + label += " · status unreadable" + } + } + if hog := m.hogLabel(usage); hog != "" { + label = "! " + hog + " · " + label } - text := fit(c.line(strings.Repeat(" ", r.depth)+glyph+label, fmt.Sprint(usage.Processes), groups.Percent(usage.CPUPercent), - groups.Size(float64(usage.RSSBytes)), groups.Rate(usage.DiskRead), groups.Rate(usage.DiskWrite), groups.Rate(usage.NetRx), - groups.Rate(usage.NetTx), groups.Count(usage.Sockets), groups.OriginText(r.group.Origin), groups.ContextText(r.group.Context)), m.width) - if r.group.Key == m.selected { + name := strings.Repeat(" ", r.depth) + glyph + label + text := fit(c.line(name, procs, groups.Percent(usage.CPUPercent), + groups.Size(float64(usage.RSSBytes)), groups.MemorySize(usage.CompressedBytes), groups.MemorySize(usage.SwapBytes), groups.Rate(usage.DiskRead), groups.Rate(usage.DiskWrite), groups.Rate(usage.NetRx), + groups.Rate(usage.NetTx), groups.Count(usage.Sockets), origin, context), m.width) + if r.group.Task != nil && usage.Processes == 0 { + // A task row holding no process's group has no use to show. + text = fit(c.line(name, "", "", "", "", "", "", "", "", "", "", origin, context), m.width) + } + if r.key == m.selected { return selectedStyle.Render(text) } - if m.cpuHog(usage.CPUPercent) { + if m.hogLabel(usage) != "" { return statusStyle.Render(text) } if style, ok := kindStyles[r.group.Kind]; ok { @@ -232,41 +262,47 @@ func (m Model) renderDetail() []string { if height == 0 { return nil } - title := "processes of " + m.selected - if m.frame != nil { - for _, group := range m.frame.Groups { - if group.Key == m.selected { - title = "processes of " + groups.Label(group) + " and the groups under it" - } + title := m.selected + if rows := m.rows(); m.selectedIndex(rows) >= 0 { + selected := rows[m.selectedIndex(rows)] + title = groups.Label(selected.group) + if selected.process != nil { + title = fmt.Sprintf("%d %s", selected.process.PID, groups.ShortCommand(selected.process.Command)) } } - lines := []string{headStyle.Render(fit("── "+title+" "+strings.Repeat("─", m.width), m.width))} processes, kept := m.selectedProcesses() + if kept { + title += fmt.Sprintf(" · %d processes", len(processes)) + } + heading := "── " + groups.Truncate(title, max(1, m.width-4)) + " " + lines := []string{headStyle.Render(heading + strings.Repeat("─", max(0, m.width-lipgloss.Width(heading))))} + rows := height if !kept { - return append(lines, padLines(mutedStyle.Render("A recording keeps each group's use, not its processes."), height-1)...) + return append(lines, padLines(mutedStyle.Render("A recording keeps each group's use, not its processes."), rows-1)...) } - commandWidth := max(10, m.width-(8+12+7+8+9+9+9+9+6+24)) - lines = append(lines, headStyle.Render(fit(fmt.Sprintf("%8s %-11s%7s%8s%9s%9s%9s%9s%6s %-22s%s", - "PID", "USER", "CPU%", "RSS", "DISK R/s", "DISK W/s", "NET IN/s", "NET OUT/s", "SOCK", "ORIGIN", "COMMAND"), m.width))) + commandWidth := max(10, m.width-(8+12+7+8+8+8+9+9+9+9+6+24)) + lines = append(lines, headStyle.Render(fit(fmt.Sprintf("%8s %-11s%7s%8s%8s%8s%9s%9s%9s%9s%6s %-22s%s", + "PID", "USER", "CPU%", "RSS", "CMPRS", "SWAP", "DISK R/s", "DISK W/s", "NET IN/s", "NET OUT/s", "SOCK", "ORIGIN", "COMMAND"), m.width))) start := 0 for index, p := range processes { if p.Key == m.processKey { - start = max(0, index-(height-3)) + start = max(0, index-(rows-3)) } } - for index := start; index < min(len(processes), start+height-2); index++ { + for index := start; index < min(len(processes), start+rows-2); index++ { p := processes[index] command := p.Command - if m.cpuHog(p.CPUPercent) { - command = "! CPU hog · " + command + if hog := m.hogLabel(p.Usage); hog != "" { + command = "! " + hog + " · " + command } - text := fit(fmt.Sprintf("%8d %-11s%7s%8s%9s%9s%9s%9s%6s %-22s%s", + text := fit(fmt.Sprintf("%8d %-11s%7s%8s%8s%8s%9s%9s%9s%9s%6s %-22s%s", p.PID, groups.Truncate(p.Origin.Owner, 10), groups.Percent(p.CPUPercent), groups.Size(float64(p.RSSBytes)), + groups.MemorySize(p.CompressedBytes), groups.MemorySize(p.SwapBytes), groups.Rate(p.DiskRead), groups.Rate(p.DiskWrite), groups.Rate(p.NetRx), groups.Rate(p.NetTx), groups.Count(p.Sockets), groups.Truncate(groups.OriginText(p.Origin), 21), groups.Truncate(command, commandWidth)), m.width) if p.Key == m.processKey || (m.processKey == "" && index == 0) { text = selectedStyle.Render(text) - } else if m.cpuHog(p.CPUPercent) { + } else if m.hogLabel(p.Usage) != "" { text = statusStyle.Render(text) } lines = append(lines, text) @@ -282,10 +318,10 @@ func (m Model) footer() string { return mutedStyle.Render(fit("type to filter · enter keeps it · esc clears it", m.width)) } if m.detail { - return mutedStyle.Render(fit("[ ] choose process x terminate r nice=10 y confirm esc cancel · ! CPU hog >25% of all cores", m.width)) + return mutedStyle.Render(fit("[ ] choose process x terminate r nice=10 y confirm esc cancel f close · hogs pinned 120s · CMPRS includes swapped-out pages on macOS", m.width)) } toggles := fmt.Sprintf("o other:%s n net:%s", onOff(m.toggles.All), onOff(m.toggles.Net)) - return mutedStyle.Render(fit("↑↓ move ←→ fold enter processes b group s sort S reverse / filter "+toggles+" q quit", m.width)) + return mutedStyle.Render(fit("↑↓ move ←→ fold enter list processes f process pane b group s sort S reverse / filter "+toggles+" q quit", m.width)) } func onOff(on bool) string { diff --git a/internal/traceui/model.go b/internal/traceui/model.go new file mode 100644 index 0000000..68cb5f7 --- /dev/null +++ b/internal/traceui/model.go @@ -0,0 +1,279 @@ +package traceui + +import ( + "context" + "slices" + "time" + + tea "charm.land/bubbletea/v2" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces/read" +) + +type Options struct { + Refs []read.Ref + Runs []telltale.RunInfo + Sort string + Replay bool +} + +type tab struct { + name, file, cursor string + refs []read.Ref + page read.FeedResult + history []string + selected int + paused, detail bool + monitor, output string + watermarks []int64 + columns []query.ColumnDef + following bool + outputOffset int64 + browse bool +} + +type pageMsg struct { + generation int + page read.FeedResult + monitor, output string + watermarks []int64 + columns []query.ColumnDef + err error +} +type End struct { + Err error + Info *telltale.RunInfo +} +type tickMsg struct{} + +type Model struct { + ctx context.Context + options Options + tabs []tab + active, run, generation, width, height int + ended, loading bool + err error + saved map[int]runState +} + +type runState struct { + tabs []tab + active int +} + +func New(ctx context.Context, options Options) Model { + if options.Sort == "" { + options.Sort = "seq" + } + m := Model{ctx: ctx, options: options, ended: options.Replay, saved: map[int]runState{}} + m.buildTabs() + return m +} + +func tick() tea.Cmd { + return tea.Tick(time.Second, func(time.Time) tea.Msg { return tickMsg{} }) +} + +func (m Model) Init() tea.Cmd { return tea.Batch(m.load(), tick()) } + +func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { + switch value := msg.(type) { + case tea.WindowSizeMsg: + m.width, m.height = value.Width, value.Height + case End: + m.ended = true + if value.Info != nil && len(m.options.Runs) > 0 { + m.options.Runs = slices.Clone(m.options.Runs) + m.options.Runs[m.run] = *value.Info + } + if value.Err != nil { + m.err = value.Err + return m, tea.Quit + } + m.generation++ + return m, m.load() + case tickMsg: + if m.loading || m.tabs[m.active].paused { + return m, tick() + } + m.loading = true + return m, tea.Batch(m.load(), tick()) + case pageMsg: + if value.generation != m.generation { + return m, nil + } + m.loading = false + if value.err != nil { + m.err = value.err + return m, tea.Quit + } + t := &m.tabs[m.active] + if !t.paused { + t.page, t.monitor, t.output, t.watermarks = value.page, value.monitor, value.output, value.watermarks + t.columns = value.columns + if t.file == "" { + t.selected = min(t.selected, max(0, len(t.page.Rows)-1)) + } + } + case tea.KeyPressMsg: + return m.key(value.String()) + } + return m, nil +} + +func (m Model) key(key string) (tea.Model, tea.Cmd) { + t := &m.tabs[m.active] + switch key { + case "q", "ctrl+c": + return m, tea.Quit + case "tab", "shift+tab": + delta := 1 + if key == "shift+tab" { + delta = -1 + } + m.active = (m.active + delta + len(m.tabs)) % len(m.tabs) + case "[", "]": + if len(m.options.Runs) < 2 { + return m, nil + } + delta := 1 + if key == "[" { + delta = -1 + } + m.saved[m.run] = runState{tabs: m.tabs, active: m.active} + m.run = (m.run + delta + len(m.options.Runs)) % len(m.options.Runs) + if state, ok := m.saved[m.run]; ok { + m.tabs, m.active = state.tabs, state.active + } else { + m.buildTabs() + } + case "down", "j", "pgdown": + t.following = false + step := 1 + if key == "pgdown" { + step = max(1, m.height-8) + } + t.selected = max(0, min(m.rowCount()-1, t.selected+step)) + return m, nil + case "up", "k", "pgup": + if t.following { + t.selected = max(0, m.rowCount()-1) + t.following = false + } + step := 1 + if key == "pgup" { + step = max(1, m.height-8) + } + t.selected = max(0, t.selected-step) + return m, nil + case "home", "g": + t.following = false + t.selected = 0 + if t.file == "" { + t.browse = true + t.cursor = "" + t.history = nil + break + } + t.outputOffset = 0 + case "end", "G": + t.following = true + t.selected = max(0, m.rowCount()-1) + if t.file == "" { + t.browse = false + t.cursor = "" + t.history = nil + break + } + t.outputOffset = -1 + case "enter": + t.detail = !t.detail + return m, nil + case " ", "space": + t.paused = !t.paused + if t.paused { + return m, nil + } + case "n": + if t.file != "" { + if t.outputOffset < 0 { + t.outputOffset = min(-1, t.outputOffset+1) + } else { + t.outputOffset += (1 << 20) + } + t.selected = 0 + t.following = false + break + } + if t.page.NextCursor == "" { + return m, nil + } + t.history = append(t.history, t.cursor) + t.cursor = t.page.NextCursor + case "p": + if t.file != "" { + if t.outputOffset < 0 { + t.outputOffset-- + } else { + t.outputOffset = max(0, t.outputOffset-(1<<20)) + } + t.selected = 0 + t.following = false + break + } + if len(t.history) == 0 { + return m, nil + } + t.cursor = t.history[len(t.history)-1] + t.history = t.history[:len(t.history)-1] + case "r": + t.cursor = "" + t.history = nil + t.watermarks = nil + case "s": + if m.options.Sort == "seq" { + m.options.Sort = "timestamp" + } else { + m.options.Sort = "seq" + } + for i := range m.tabs { + m.tabs[i].cursor = "" + m.tabs[i].history = nil + } + default: + return m, nil + } + m.generation++ + m.loading = true + return m, m.load() +} + +func (m Model) Err() error { return m.err } + +func (m *Model) buildTabs() { + m.tabs = nil + names := []string{} + for _, ref := range m.options.Refs { + if len(m.options.Runs) > 0 && ref.RunID != m.options.Runs[m.run].RunID { + continue + } + owner, _ := ref.Runtime.Kinds.ResultOf(ref.Kind) + if !slices.Contains(names, owner) { + names = append(names, owner) + } + } + slices.Sort(names) + for _, name := range names { + t := tab{name: name} + for _, ref := range m.options.Refs { + owner, _ := ref.Runtime.Kinds.ResultOf(ref.Kind) + if owner == name && (len(m.options.Runs) == 0 || ref.RunID == m.options.Runs[m.run].RunID) { + t.refs = append(t.refs, ref) + } + } + m.tabs = append(m.tabs, t) + } + m.tabs = append(m.tabs, tab{name: "Stdout", file: "stdout", following: true, outputOffset: -1}, tab{name: "Stderr", file: "stderr", following: true, outputOffset: -1}) + m.active = 0 +} diff --git a/internal/traceui/model_test.go b/internal/traceui/model_test.go new file mode 100644 index 0000000..73a6602 --- /dev/null +++ b/internal/traceui/model_test.go @@ -0,0 +1,38 @@ +package traceui + +import ( + tea "charm.land/bubbletea/v2" + "context" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/flanksource/telltale/pkg/tracing" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "testing" +) + +func TestTraceUI(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Trace UI") } + +var _ = Describe("record model", func() { + runtime := &tracing.Runtime{Kinds: tracing.NewKinds()} + It("keeps enabled empty kinds visible and uses an alternate screen", func() { + model := New(context.Background(), Options{Refs: []read.Ref{{Runtime: runtime, TraceRef: tracing.TraceRef{Kind: "sql", Stream: "s"}}, {Runtime: runtime, TraceRef: tracing.TraceRef{Kind: "http", Stream: "h"}}}}) + Expect(model.tabs).To(HaveLen(4)) + Expect(model.tabs[0].name).To(Equal("http")) + Expect(model.View().AltScreen).To(BeTrue()) + }) + It("preserves selection and pause independently across tabs", func() { + model := New(context.Background(), Options{Refs: []read.Ref{{Runtime: runtime, TraceRef: tracing.TraceRef{Kind: "http", Stream: "h"}}, {Runtime: runtime, TraceRef: tracing.TraceRef{Kind: "sql", Stream: "s"}}}}) + model.tabs[0].selected = 3 + model.tabs[0].paused = true + updated, _ := model.Update(tea.KeyPressMsg{Code: tea.KeyTab}) + model = updated.(Model) + Expect(model.active).To(Equal(1)) + Expect(model.tabs[1].selected).To(BeZero()) + Expect(model.tabs[0].paused).To(BeTrue()) + }) + It("discards responses from a previously selected tab", func() { + model := New(context.Background(), Options{}) + updated, _ := model.Update(pageMsg{generation: -1, output: "stale"}) + Expect(updated.(Model).tabs[0].output).To(BeEmpty()) + }) +}) diff --git a/internal/traceui/source.go b/internal/traceui/source.go new file mode 100644 index 0000000..f71a246 --- /dev/null +++ b/internal/traceui/source.go @@ -0,0 +1,208 @@ +package traceui + +import ( + "errors" + "fmt" + "io" + "os" + "path/filepath" + "slices" + "strings" + + tea "charm.land/bubbletea/v2" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons-db/recordstore" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/flanksource/telltale/pkg/tracing/processcapture" +) + +func (m Model) load() tea.Cmd { + m.tabs = slices.Clone(m.tabs) + m.options.Runs = slices.Clone(m.options.Runs) + t := m.tabs[m.active] + return func() tea.Msg { + result := pageMsg{generation: m.generation} + if t.file != "" { + result.output, result.err = m.readOutput(t.file) + return result + } + refs := slices.Clone(t.refs) + identities := map[string]query.Row{} + if t.name == processcapture.Kind { + refs = nil + for _, ref := range t.refs { + switch ref.Kind { + case processcapture.MetricsTable: + refs = append(refs, ref) + case processcapture.Kind: + if err := ref.Runtime.Read(m.ctx, ref.TraceRef, func(_ int64, row recordstore.Row) error { + key, ok := row["key"].(string) + if !ok { + return fmt.Errorf("process identity has no key") + } + identities[key] = query.Row(row) + return nil + }); err != nil { + result.err = err + return result + } + } + } + result.columns = []query.ColumnDef{{Name: "pid", Label: "PID"}, {Name: "name", Label: "Process"}, {Name: "cpuPercent", Label: "CPU %"}, {Name: "rssBytes", Label: "RSS"}, {Name: "openFiles", Label: "Files"}, {Name: "receivingSockets", Label: "Listeners"}, {Name: "connectionsIn", Label: "Peers in"}, {Name: "connectionsOut", Label: "Peers out"}, {Name: "connectionsUnknown", Label: "Peers ?"}} + } + var observations int64 + for _, ref := range refs { + plugin, ok := ref.Runtime.Kinds.Get(ref.Kind) + if !ok { + result.err = fmt.Errorf("unknown trace kind %s", ref.Kind) + return result + } + schema, err := plugin.Schema(ref.Kind) + if err != nil { + result.err = err + return result + } + if len(result.columns) == 0 { + for _, column := range schema.Columns { + if !column.Hidden && column.Type != "json" { + result.columns = append(result.columns, column) + } + } + } + meta, err := ref.Runtime.Results.Backend.Meta(m.ctx, ref.Stream) + if err != nil { + result.err = err + return result + } + result.watermarks = append(result.watermarks, meta.HighSeq) + observations += meta.Total + } + result.monitor = t.monitor + if t.name == processcapture.Kind { + result.monitor = fmt.Sprintf("%d processes · %d numeric observations · resource counts from committed deltas", len(identities), observations) + } else if !slices.Equal(t.watermarks, result.watermarks) || t.monitor == "" { + result.monitor = "" + for _, ref := range t.refs { + summary, err := ref.Runtime.Summarize(m.ctx, ref.TraceRef) + if err != nil { + result.err = err + return result + } + result.monitor += ref.Stream + " · " + summaryText(summary) + "\n" + } + } + if !m.options.Replay && !t.browse && t.cursor == "" { + for i := range refs { + refs[i].AfterSeq = max(refs[i].AfterSeq, result.watermarks[i]-100) + } + } + result.page, result.err = read.FeedPage(m.ctx, refs, read.FeedQuery{Sort: m.options.Sort, Query: read.Query{Cursor: t.cursor}}) + if t.name == processcapture.Kind && result.err == nil { + for i := range result.page.Rows { + row := &result.page.Rows[i] + key, _ := row.Record["entity"].(string) + identity, ok := identities[key] + if !ok { + result.err = fmt.Errorf("metrics reference unknown process %q", key) + return result + } + row.Record["name"], row.Record["pid"] = identity["name"], identity["pid"] + } + } + return result + } +} + +func (m Model) readOutput(channel string) (string, error) { + if len(m.options.Runs) == 0 { + return "Output unavailable: no command recording.", nil + } + run := m.options.Runs[m.run] + if run.Output == nil { + if channel == "stderr" { + return "Separate stderr unavailable in this recording.", nil + } + path := filepath.Join(run.Dir, telltale.OutputFile) + if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) { + return "Output unavailable: process output was not recorded.", nil + } else if err != nil { + return "", err + } + return outputWindow(path, m.tabs[m.active].outputOffset) + } + name := run.Output.Stdout + if channel == "stderr" { + name = run.Output.Stderr + } + if name == "" || filepath.Base(name) != name { + return "", fmt.Errorf("invalid recorded %s path %q", channel, name) + } + return outputWindow(filepath.Join(run.Dir, name), m.tabs[m.active].outputOffset) +} + +func outputWindow(path string, offset int64) (_ string, err error) { + f, err := os.Open(path) + if err != nil { + return "", err + } + defer func() { err = errors.Join(err, f.Close()) }() + info, err := f.Stat() + if err != nil { + return "", err + } + const limit = 1 << 20 + start := offset + if start < 0 { + start = max(int64(0), info.Size()+offset*limit) + } + start = min(start, max(int64(0), info.Size()-limit)) + if _, err = f.Seek(start, io.SeekStart); err != nil { + return "", err + } + data, err := io.ReadAll(io.LimitReader(f, limit)) + if err != nil { + return "", err + } + text := string(data) + if info.Size() > limit { + text = fmt.Sprintf("[bytes %d..%d of %d · Home/End start/tail · n/p blocks]\n", start, start+int64(len(data)), info.Size()) + text + } + return text, nil +} + +func summaryText(summary map[string]any) string { + keys := make([]string, 0, len(summary)) + for key := range summary { + keys = append(keys, key) + } + slices.Sort(keys) + parts := []string{} + for _, key := range keys { + switch value := summary[key].(type) { + case map[string]any: + parts = append(parts, key+" {"+summaryText(value)+"}") + case map[string]int: + nested := map[string]any{} + for k, v := range value { + nested[k] = v + } + parts = append(parts, key+" {"+summaryText(nested)+"}") + case map[string]int64: + nested := map[string]any{} + for k, v := range value { + nested[k] = v + } + parts = append(parts, key+" {"+summaryText(nested)+"}") + case []map[string]any: + if key != "requests" && key != "queries" { + for _, v := range value { + parts = append(parts, summaryText(v)) + } + } + case string, bool, int, int64, uint64, float64, float32: + parts = append(parts, fmt.Sprintf("%s=%v", key, value)) + } + } + return strings.Join(parts, " · ") +} diff --git a/internal/traceui/source_test.go b/internal/traceui/source_test.go new file mode 100644 index 0000000..0e7f850 --- /dev/null +++ b/internal/traceui/source_test.go @@ -0,0 +1,56 @@ +package traceui + +import ( + "context" + "os" + "path/filepath" + "strings" + + tea "charm.land/bubbletea/v2" + "github.com/charmbracelet/x/ansi" + "github.com/flanksource/telltale" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("trace terminal output", func() { + It("pages large saved output without retaining the whole file", func() { + path := filepath.Join(GinkgoT().TempDir(), "stdout.log") + Expect(os.WriteFile(path, []byte("first\n"+strings.Repeat("x", 2<<20)+"\nlast"), 0600)).To(Succeed()) + first, err := outputWindow(path, 0) + Expect(err).NotTo(HaveOccurred()) + Expect(first).To(ContainSubstring("first\n")) + Expect(len(first)).To(BeNumerically("<", (1<<20)+256)) + last, err := outputWindow(path, -1) + Expect(err).NotTo(HaveOccurred()) + Expect(last).To(HaveSuffix("\nlast")) + }) + It("keeps stdout and stderr separate including partial lines", func() { + dir := GinkgoT().TempDir() + Expect(os.WriteFile(filepath.Join(dir, telltale.StdoutFile), []byte("standard\npartial"), 0600)).To(Succeed()) + Expect(os.WriteFile(filepath.Join(dir, telltale.StderrFile), []byte("diagnostic"), 0600)).To(Succeed()) + m := New(context.Background(), Options{Runs: []telltale.RunInfo{{Dir: dir, Output: &telltale.OutputRefs{Stdout: telltale.StdoutFile, Stderr: telltale.StderrFile}}}}) + out, err := m.readOutput("stdout") + Expect(err).NotTo(HaveOccurred()) + Expect(out).To(Equal("standard\npartial")) + errout, err := m.readOutput("stderr") + Expect(err).NotTo(HaveOccurred()) + Expect(errout).To(Equal("diagnostic")) + }) + It("rejects a missing declared output file", func() { + m := New(context.Background(), Options{Runs: []telltale.RunInfo{{Dir: GinkgoT().TempDir(), Output: &telltale.OutputRefs{Stdout: telltale.StdoutFile}}}}) + _, err := m.readOutput("stdout") + Expect(err).To(HaveOccurred()) + }) + It("bounds every rendered line and keeps the footer on small terminals", func() { + m := New(context.Background(), Options{}) + updated, _ := m.Update(tea.WindowSizeMsg{Width: 40, Height: 8}) + m = updated.(Model) + m.tabs[0].output = strings.Repeat("long output ", 100) + lines := strings.Split(m.View().Content, "\n") + Expect(lines).To(HaveLen(8)) + for _, line := range lines { + Expect(ansi.StringWidth(line)).To(BeNumerically("<=", 40)) + } + }) +}) diff --git a/internal/traceui/view.go b/internal/traceui/view.go new file mode 100644 index 0000000..4971804 --- /dev/null +++ b/internal/traceui/view.go @@ -0,0 +1,116 @@ +package traceui + +import ( + "fmt" + "strings" + "time" + + tea "charm.land/bubbletea/v2" + "github.com/charmbracelet/x/ansi" + "github.com/flanksource/clicky" + "github.com/flanksource/telltale/internal/terminalui" +) + +var titleStyle = terminalui.Title +var mutedStyle = terminalui.Muted +var selectedStyle = terminalui.Selected + +func (m Model) rowCount() int { + t := m.tabs[m.active] + if t.file != "" { + return len(strings.Split(t.output, "\n")) + } + return len(t.page.Rows) +} + +func (m Model) View() tea.View { + width, height := max(1, m.width), max(1, m.height) + t := m.tabs[m.active] + status := "Following" + if m.ended { + status = "Capture complete" + } + if t.paused { + status = "Paused" + } + title := "Trace · " + status + if len(m.options.Runs) > 0 { + r := m.options.Runs[m.run] + elapsed := time.Since(r.StartedAt) + if !r.EndedAt.IsZero() { + elapsed = r.EndedAt.Sub(r.StartedAt) + } + title = fmt.Sprintf("%s · %s · %s · %s", title, r.RunID, elapsed.Round(time.Second), strings.Join(r.Command, " ")) + } + names := []string{} + for i, tab := range m.tabs { + name := " " + tab.name + " " + if i == m.active { + name = selectedStyle.Render(name) + } + names = append(names, name) + } + tabLine := strings.Join(names, " ") + if ansi.StringWidth(tabLine) > width { + tabLine = "‹ " + strings.Join(names[m.active:], " ") + " ›" + } + lines := []string{titleStyle.Render(title), tabLine} + monitor := strings.TrimSpace(t.monitor) + if monitor == "" { + monitor = "Waiting for " + t.name + "…" + } + if t.file != "" { + monitor = t.name + " · " + status + } + monitorLines := strings.Split(ansi.Wrap(monitor, width, ""), "\n") + lines = append(lines, monitorLines[:min(len(monitorLines), max(1, height/4))]...) + body := []string{} + if t.file != "" { + body = strings.Split(ansi.Strip(t.output), "\n") + } else { + for i, row := range t.page.Rows { + text, err := clicky.Format(row.Pretty(), clicky.FormatOptions{Format: "pretty"}) + if err != nil { + text = err.Error() + } + text = strings.ReplaceAll(text, "\n", " ") + if i == t.selected { + text = selectedStyle.Render(text) + } + body = append(body, text) + } + } + available := max(0, height-len(lines)-1) + detail := []string{} + if t.detail && t.file == "" && len(t.page.Rows) > 0 { + text, err := clicky.Format(t.page.Rows[t.selected].PrettyFull(), clicky.FormatOptions{Format: "pretty"}) + if err != nil { + text = err.Error() + } + detail = strings.Split(text, "\n") + detail = detail[:min(len(detail), available/2)] + available -= len(detail) + } + start := max(0, t.selected-available+1) + if t.file != "" && t.following { + start = max(0, len(body)-available) + } + for i := start; i < min(len(body), start+available); i++ { + lines = append(lines, body[i]) + } + for len(lines) < height-1-len(detail) { + lines = append(lines, "") + } + lines = append(lines, detail...) + footer := "q quit · tab/shift+tab kind · ↑↓ scroll · space pause · n/p page · s sort · enter detail · r refresh · [/] run" + lines = append(lines, mutedStyle.Render(footer)) + if len(lines) > height { + lines = append(lines[:height-1], mutedStyle.Render(footer)) + } + for i, line := range lines { + lines[i] = ansi.Truncate(line, width, "") + } + view := tea.NewView(strings.Join(lines, "\n")) + view.AltScreen = true + return view +} diff --git a/internal/traceui/view_test.go b/internal/traceui/view_test.go new file mode 100644 index 0000000..c64663c --- /dev/null +++ b/internal/traceui/view_test.go @@ -0,0 +1,57 @@ +package traceui + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + + "github.com/charmbracelet/x/ansi" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces/read" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("styled trace view", func() { + It("keeps HTTP pretty rows when the kind also has schema columns", func() { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + defer GinkgoRecover() + _, err := w.Write([]byte("recorded orders")) + Expect(err).NotTo(HaveOccurred()) + })) + DeferCleanup(server.Close) + dataDir := GinkgoT().TempDir() + run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: dataDir, + Command: []string{"curl", "--noproxy", "", "-sS", server.URL + "/orders"}, + Traces: []telltale.TraceSpec{{Kind: "http", Params: json.RawMessage(`{"target":{"seam":"proxy"}}`)}}}) + Expect(err).NotTo(HaveOccurred()) + _, err = run.Wait() + Expect(err).NotTo(HaveOccurred()) + selected, err := read.Resolve("http", read.Scope{DataDir: dataDir, Runs: []string{run.ID()}}) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(selected.Close) + model := New(context.Background(), Options{Refs: selected.Refs, Replay: true}) + model.width, model.height = 180, 20 + loaded := model.load()().(pageMsg) + Expect(loaded.err).NotTo(HaveOccurred()) + Expect(loaded.columns).NotTo(BeEmpty()) + updated, _ := model.Update(loaded) + text := strings.Join(strings.Fields(ansi.Strip(updated.(Model).View().Content)), " ") + Expect(text).To(ContainSubstring("http #1 GET")) + Expect(text).To(ContainSubstring(server.URL + "/orders")) + }) + + It("keeps terminal event rows visible alongside snapshots", func() { + model := New(context.Background(), Options{Replay: true}) + model.width, model.height = 100, 20 + model.tabs = []tab{{name: "terminal", page: read.FeedResult{Rows: []read.Record{ + {Kind: "terminal", Seq: 1, Record: query.Row{"kind": "r", "width": 120, "height": 40}}, + {Kind: "terminal", Seq: 2, Record: query.Row{"kind": "snapshot", "data": "recorded terminal screen"}}, + }}}} + text := strings.Join(strings.Fields(ansi.Strip(model.View().Content)), " ") + Expect(text).To(And(ContainSubstring("terminal #1"), ContainSubstring("terminal #2"))) + }) +}) From 2353f406f8ee61ef93aa5250ac4394b4bb2724c2 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:06:30 +0200 Subject: [PATCH 09/89] feat(demo): Add real end-to-end demo recording for all trace kinds Add hack/demo, a runnable program that records one persisted Telltale run with real fresh captures for every registered trace kind. It drives localhost HTTP and SQLite orders, a Clicky exec and PTY terminal session of git --version, a child JVM under JFR, managed Prometheus scraping, lab SQL Server XEvents, plan-cache and deadlock captures, and one bounded Captain API LLM request capped at USD 0.05. Verification fails the run unless every kind has meaningful records with no dropped or unencodable loss, and every session ends stopped or completed. Fixtures are never loaded. The demo also exports Clicky UI playground events and saves the lab connection with a private file mode, refusing to overwrite an existing one. Also adds hack/docs-catalog, which regenerates docs/_data/kinds.json from the trace registry and can check it for staleness. --- hack/demo/DemoWorkload.java | 22 ++++ hack/demo/README.md | 68 ++++++++++++ hack/demo/coverage.go | 215 ++++++++++++++++++++++++++++++++++++ hack/demo/demo_test.go | 66 +++++++++++ hack/demo/export.go | 184 ++++++++++++++++++++++++++++++ hack/demo/export_sources.go | 112 +++++++++++++++++++ hack/demo/export_test.go | 22 ++++ hack/demo/generate.go | 137 +++++++++++++++++++++++ hack/demo/llm.go | 56 ++++++++++ hack/demo/main.go | 61 ++++++++++ hack/demo/mssql.go | 158 ++++++++++++++++++++++++++ hack/demo/sessions.go | 48 ++++++++ hack/demo/setup.go | 57 ++++++++++ hack/demo/setup_test.go | 43 ++++++++ hack/demo/specs.go | 51 +++++++++ hack/demo/workloads.go | 171 ++++++++++++++++++++++++++++ hack/docs-catalog/main.go | 82 ++++++++++++++ 17 files changed, 1553 insertions(+) create mode 100644 hack/demo/DemoWorkload.java create mode 100644 hack/demo/README.md create mode 100644 hack/demo/coverage.go create mode 100644 hack/demo/demo_test.go create mode 100644 hack/demo/export.go create mode 100644 hack/demo/export_sources.go create mode 100644 hack/demo/export_test.go create mode 100644 hack/demo/generate.go create mode 100644 hack/demo/llm.go create mode 100644 hack/demo/main.go create mode 100644 hack/demo/mssql.go create mode 100644 hack/demo/sessions.go create mode 100644 hack/demo/setup.go create mode 100644 hack/demo/setup_test.go create mode 100644 hack/demo/specs.go create mode 100644 hack/demo/workloads.go create mode 100644 hack/docs-catalog/main.go diff --git a/hack/demo/DemoWorkload.java b/hack/demo/DemoWorkload.java new file mode 100644 index 0000000..9846951 --- /dev/null +++ b/hack/demo/DemoWorkload.java @@ -0,0 +1,22 @@ +import java.util.concurrent.locks.LockSupport; + +public class DemoWorkload { + private static volatile long sink; + private static final Object lock = new Object(); + + public static void main(String[] args) throws Exception { + Runnable[] jobs = { + () -> { while (true) { for (int i = 0; i < 100_000; i++) sink += i; LockSupport.parkNanos(1_000_000); } }, + () -> { while (true) { byte[] allocation = new byte[1024 * 1024]; sink = allocation.length; LockSupport.parkNanos(10_000_000); } }, + () -> { while (true) { synchronized (lock) { LockSupport.parkNanos(30_000_000); } } }, + () -> { while (true) { synchronized (lock) { sink++; } LockSupport.parkNanos(10_000_000); } } + }; + for (Runnable job : jobs) { + Thread thread = new Thread(job); + thread.setDaemon(true); + thread.start(); + } + System.out.println("Demo workload ready"); + System.in.read(); + } +} diff --git a/hack/demo/README.md b/hack/demo/README.md new file mode 100644 index 0000000..093e608 --- /dev/null +++ b/hack/demo/README.md @@ -0,0 +1,68 @@ +# Record every trace kind + +Run this from the repository root to create one ordinary persisted Telltale run with fresh recordings for every kind returned by `traces.Registrations()`. The program exits unsuccessfully if any kind is missing, has no useful records, loses records, fails to stop, or fails cleanup. It never loads recorded fixtures. + +## Prerequisites + +- Run `make setup` and use the repository's local Go workspace. +- Put `git`, `java`, `javac`, `jcmd`, and `ps` on `PATH`. Use a JDK that supports Flight Recorder and allows attaching to a child JVM. +- Configure `connection://mssql` for **mssql.lab:31433**, with permission to create/drop a database, create/drop Extended Events sessions, inspect plan-cache DMVs, and read `system_health` deadlock events. This demo uses the lab server, not Docker. It creates only a uniquely named `telltale_demo_*` database and XE session and removes them after the captures drain. +- Authenticate a Captain API model with known pricing. Supply the model explicitly. One fresh, short request is made per recording, with a 128-token output limit, no tools or caching, and a maximum approved cost of USD 0.05. No LLM request is made by tests or `--verify-run`. + +To save the existing lab Connection resource in the shared connection store, run this once: + +```sh +go run ./hack/demo --save-connection-from "$HOME/.config/sqlglot-go/connections/lab.yaml" +``` + +The helper validates the endpoint, normalizes the database to `master`, saves `mssql.yaml` with mode `0600`, and refuses to overwrite an existing shared connection. Credentials stay in that connection file and memory; trace params contain `connection://mssql`. + +## Record and inspect + +```sh +go run ./hack/demo --model api:claude-haiku-5-5 +``` + +Use any authenticated Captain API model whose bounded request fits the cap. `--data-dir` defaults to `.tmp/demo/data`; `--timeout` defaults to `2m`. Progress goes to stderr and the final JSON report goes to stdout. The report includes the run ID, store directory, native record counts, final session summaries, and errors. It is also saved as `demo-report.json` in the run directory. The workload's SQLite database, Java source/classes, and JVM log remain in a sibling `work-*` directory for inspection. + +Recheck a saved recording without another paid request: + +```sh +go run ./hack/demo --verify-run +``` + +After `make build`, view the saved records using the local binary: + +```sh +.bin/telltale trace replay --data-dir .tmp/demo/data --format ndjson +.bin/telltale trace replay --data-dir .tmp/demo/data --format ansi +.bin/telltale trace replay --data-dir .tmp/demo/data --tui +.bin/telltale trace replay --data-dir .tmp/demo/data --ui +``` + +## Recorded work + +| Kinds | Real workload | +| --- | --- | +| `http`, `sql`, `logs`, `spans` | Instrumented localhost orders requests reading a freshly seeded SQLite database | +| `exec`, `terminal` | A Clicky execution and a separate PTY execution of `git --version`, including output, resize, and measured exit status | +| `stacks`, `goprof` | Periodic native stack and heap readings of the demo process while it holds allocations | +| `process`, `process/metrics`, `process/facets` | Native process identities, numeric observations, and resource events during the workloads | +| `jvm_jfr` | A child JVM allocating, computing, parking, and contending while Flight Recorder samples it | +| `prometheus`, `query` | Managed Prometheus scraping the demo's request counter and a windowed query reading those samples | +| `sql_xevent`, `sql_plancache`, `sql_deadlock` | Lab database statements, execution deltas, and two transactions updating rows in opposite order to produce a deadlock | +| `llm` | One observed Captain API request and its actual response/token usage | + +The run is stopped and drained before the JVM, local HTTP server, and lab database are removed. Errors and partial traces are retained. A new catalog kind requires a new real workload and evidence predicate; it cannot silently pass. + +## Clicky UI event playground + +Export representative events through the same Clicky pretty printers used by CLI follow and replay, without another LLM call or external SQL workload: + +```sh +CLICKY_FORCE_INTERACTIVE=1 go run ./hack/demo --verify-run --export-playground ../clicky-ui/apps/playground/src/pages/telltale/_trace-events.json +``` + +The sibling Clicky UI playground page is `?page=telltale%2Ftrace-events`. Styled log rows are the primary view; Details, Native view, and Stored record tabs expose the full presentation and original payload. HTTP, SQL, XEvents, and execution rows reuse the existing shared formatting code. All registered kinds and named result tables are included, with variants such as JFR CPU/allocation/lock/park, LLM request/response, terminal output/resize/snapshot/exit, and SQL Extended Events. + +When the source recording predates the current process schema, the exporter records a three-second local process capture with an observed file descriptor. These process, metrics, and facet examples identify their own source run. Other examples retain their original recording, payloads, and sequence numbers. Counts describe the complete source streams; opening the playground requires no running capture services. diff --git a/hack/demo/coverage.go b/hack/demo/coverage.go new file mode 100644 index 0000000..8aceb22 --- /dev/null +++ b/hack/demo/coverage.go @@ -0,0 +1,215 @@ +package main + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "math" + "os" + "path/filepath" + "slices" + "strconv" + "strings" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/traces/read" +) + +type evidence struct { + Kind string `json:"kind"` + Count int `json:"count"` + Meaningful bool `json:"meaningful"` +} + +func validateCoverage(kinds []string, rows map[string][]query.Row) ([]evidence, error) { + var result []evidence + var failures []error + for _, kind := range kinds { + item := evidence{Kind: kind, Count: len(rows[kind])} + for _, row := range rows[kind] { + item.Meaningful = item.Meaningful || meaningful(kind, row) + if err := captureLoss(map[string]any(row)); err != nil { + failures = append(failures, fmt.Errorf("%s: %w", kind, err)) + } + } + if kind == "terminal" { + item.Meaningful = item.Meaningful && slices.ContainsFunc(rows[kind], func(row query.Row) bool { return row["kind"] == "exit" && number(row["exitCode"]) == 0 }) + } + if kind == "llm" && (len(rows[kind]) != 2 || !slices.ContainsFunc(rows[kind], func(row query.Row) bool { return row["phase"] == "request" })) { + failures = append(failures, fmt.Errorf("llm: expected exactly one request and response")) + } + if !item.Meaningful { + failures = append(failures, fmt.Errorf("%s: %d rows, no successful workload evidence", kind, item.Count)) + } + result = append(result, item) + } + return result, errors.Join(failures...) +} + +func meaningful(kind string, row query.Row) bool { + switch kind { + case "exec": + return text(row["name"]) != "" && number(row["exitCode"]) == 0 && text(row["error"]) == "" + case "terminal": + return row["kind"] == "o" && text(row["data"]) != "" + case "goprof", "stacks": + return text(row["frames"]) != "" && text(row["frames"]) != "[]" + case "jvm_jfr": + return strings.Contains(text(row["stack"]), "DemoWorkload") && number(row["value"]) > 0 + case "prometheus": + return row["health"] == "up" && number(row["samples"]) > 0 + case "sql_plancache": + return number(row["executions"]) > 0 + case "sql_deadlock": + return number(row["victims"]) > 0 && strings.Contains(text(row["xml"]), "deadlock") + case "sql_xevent", "sql": + return text(row["sql"]) != "" && text(row["error"]) == "" + case "llm": + usage, ok := row["usage"].(map[string]any) + return ok && row["phase"] == "response" && text(row["error"]) == "" && text(row["response"]) != "" && + number(usage["inputTokens"]) > 0 && number(usage["outputTokens"]) > 0 && number(row["cost"]) >= 0 && number(row["cost"]) <= llmBudget + case "http": + return number(row["status"]) == 200 && text(row["error"]) == "" + case "logs": + return text(row["message"]) != "" + case "spans": + return row["status"] == "ok" && text(row["operation"]) != "" + case "query": + values, ok := row["row"].(map[string]any) + return ok && row["provider"] == "prometheus" && values["__name__"] == "demo_requests_total" && number(values["value"]) > 0 + case "process": + return number(row["pid"]) > 0 && text(row["command"]) != "" && row["tags"] != nil + default: + return false + } +} + +func text(value any) string { + if value == nil { + return "" + } + if s, ok := value.(string); ok { + return s + } + data, err := json.Marshal(value) + if err != nil { + panic(fmt.Errorf("encode recorded value: %w", err)) + } + return string(data) +} + +func number(value any) float64 { + value64, err := strconv.ParseFloat(fmt.Sprint(value), 64) + if err != nil { + return math.NaN() + } + return value64 +} + +func captureLoss(values map[string]any) error { + for key, value := range values { + switch key { + case "dropped", "unencodable": + if number(value) != 0 { + return fmt.Errorf("%s records: %v", key, value) + } + case "truncated": + if value != nil && text(value) != "false" && text(value) != "[]" && text(value) != "" { + return fmt.Errorf("truncated records: %v", value) + } + } + if nested, ok := value.(map[string]any); ok { + if err := captureLoss(nested); err != nil { + return err + } + } + } + return nil +} + +type report struct { + RunID string `json:"runId"` + Directory string `json:"directory"` + Coverage []evidence `json:"coverage"` + Errors []string `json:"errors"` + Sessions []sessionEvidence `json:"sessions"` + WorkloadError string `json:"workloadError,omitempty"` +} + +type verification struct { + DataDir, RunID string + Failure error + Sessions []sessionEvidence +} + +func verifyStored(ctx context.Context, v verification) error { + dataDir, runID := v.DataDir, v.RunID + info, err := telltale.Get(telltale.GetOptions{DataDir: dataDir, RunID: runID}) + if err != nil { + return err + } + r := report{RunID: runID, Directory: info.Dir, Errors: []string{}, Sessions: v.Sessions} + if v.Sessions == nil { + previous, err := os.ReadFile(filepath.Join(info.Dir, "demo-report.json")) + if err != nil { + return fmt.Errorf("read original demo evidence: %w", err) + } + var original report + if err := json.Unmarshal(previous, &original); err != nil { + return err + } + r.WorkloadError, r.Sessions = original.WorkloadError, original.Sessions + } + if v.Failure != nil { + r.WorkloadError = v.Failure.Error() + } + if r.WorkloadError != "" { + r.Errors = append(r.Errors, r.WorkloadError) + } + if err := validateSessions(r.Sessions); err != nil { + r.Errors = append(r.Errors, err.Error()) + } + rows := map[string][]query.Row{} + var kinds []string + for _, registration := range traces.Registrations() { + kinds = append(kinds, registration.Name) + selected, err := read.Resolve(registration.Name, read.Scope{DataDir: dataDir, Run: runID}) + if err != nil { + r.Errors = append(r.Errors, err.Error()) + continue + } + for row, readErr := range read.Rows(ctx, selected.Refs, read.Query{All: true}) { + if readErr != nil { + r.Errors = append(r.Errors, readErr.Error()) + break + } + rows[registration.Name] = append(rows[registration.Name], row) + } + if err := selected.Close(); err != nil { + r.Errors = append(r.Errors, err.Error()) + } + } + r.Coverage, err = validateCoverage(kinds, rows) + if err != nil { + r.Errors = append(r.Errors, err.Error()) + } + if info.Error != "" { + r.Errors = append(r.Errors, info.Error) + } + r.Errors = append(r.Errors, info.CheckpointErrors...) + data, err := json.MarshalIndent(r, "", " ") + if err != nil { + return err + } + if err := os.WriteFile(filepath.Join(info.Dir, "demo-report.json"), append(data, '\n'), 0o600); err != nil { + return err + } + fmt.Println(string(data)) + if len(r.Errors) != 0 { + return fmt.Errorf("demo run %s failed verification; see %s/demo-report.json", runID, info.Dir) + } + return nil +} diff --git a/hack/demo/demo_test.go b/hack/demo/demo_test.go new file mode 100644 index 0000000..bf7220f --- /dev/null +++ b/hack/demo/demo_test.go @@ -0,0 +1,66 @@ +package main + +import ( + "encoding/json" + "testing" + + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale/pkg/traces" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestDemo(t *testing.T) { RegisterFailHandler(Fail); RunSpecs(t, "Real demo trace") } + +var _ = Describe("capture coverage", func() { + It("rejects missing kinds and empty captures", func() { + _, err := validateCoverage([]string{"exec", "terminal"}, map[string][]query.Row{"exec": {{"exitCode": 0, "name": "git"}}}) + Expect(err).To(MatchError(ContainSubstring("terminal"))) + }) + It("requires meaningful records instead of counting failed operations", func() { + _, err := validateCoverage([]string{"prometheus"}, map[string][]query.Row{"prometheus": {{"health": "down", "samples": 0, "error": "connection refused"}}}) + Expect(err).To(MatchError(ContainSubstring("prometheus"))) + }) + It("accepts genuine successful captures and reports their complete coverage", func() { + result, err := validateCoverage([]string{"exec", "terminal"}, map[string][]query.Row{ + "exec": {{"exitCode": 0, "name": "git"}}, + "terminal": {{"kind": "o", "data": "git version"}, {"kind": "exit", "exitCode": 0}}, + }) + Expect(err).NotTo(HaveOccurred()) + Expect(result).To(Equal([]evidence{{Kind: "exec", Count: 1, Meaningful: true}, {Kind: "terminal", Count: 2, Meaningful: true}})) + }) + It("rejects a terminal without a measured exit status", func() { + _, err := validateCoverage([]string{"terminal"}, map[string][]query.Row{"terminal": {{"kind": "o", "data": "git version"}, {"kind": "exit"}}}) + Expect(err).To(HaveOccurred()) + }) + It("rejects a capture with dropped records", func() { + _, err := validateCoverage([]string{"exec"}, map[string][]query.Row{"exec": {{"name": "git", "exitCode": 0, "dropped": 1}}}) + Expect(err).To(HaveOccurred()) + }) + It("recognizes native JFR stacks and windowed Prometheus query rows", func() { + _, err := validateCoverage([]string{"jvm_jfr", "query"}, map[string][]query.Row{ + "jvm_jfr": {{"stack": "DemoWorkload.compute", "value": 2}}, + "query": {{"provider": "prometheus", "row": map[string]any{"__name__": "demo_requests_total", "value": 3}}}, + }) + Expect(err).NotTo(HaveOccurred()) + }) + It("validates parameters for every registered kind before starting workloads", func() { + specs, err := demoSpecs("http://127.0.0.1:43210", "telltale_demo_test", 12345) + Expect(err).NotTo(HaveOccurred()) + kinds, err := traces.Kinds() + Expect(err).NotTo(HaveOccurred()) + var names []string + for _, spec := range specs { + names = append(names, spec.Kind) + Expect(traces.Validate(kinds, spec.Kind, spec.Params)).To(Succeed(), spec.Kind) + } + Expect(names).To(Equal(traces.KindNames(kinds))) + }) + It("rejects loss reported inside a completed session summary", func() { + Expect(validateSessions([]sessionEvidence{{Kind: "exec", State: query.SessionCompleted, Summary: json.RawMessage(`{"source":{"dropped":1}}`)}})).To(MatchError(ContainSubstring("dropped"))) + }) + It("requires a single LLM request with measured response usage", func() { + _, err := validateCoverage([]string{"llm"}, map[string][]query.Row{"llm": {{"phase": "request"}, {"phase": "response", "response": "example reply"}}}) + Expect(err).To(HaveOccurred()) + }) +}) diff --git a/hack/demo/export.go b/hack/demo/export.go new file mode 100644 index 0000000..a77e908 --- /dev/null +++ b/hack/demo/export.go @@ -0,0 +1,184 @@ +package main + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "slices" + "strings" + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/traces/read" +) + +type playgroundEvent struct { + Variant string `json:"variant"` + Seq int64 `json:"seq"` + ANSI string `json:"ansi"` + DetailANSI string `json:"detailAnsi"` + Record query.Row `json:"record"` +} + +type playgroundKind struct { + Name string `json:"name"` + Title string `json:"title"` + Description string `json:"description"` + Count int `json:"count"` + Events []playgroundEvent `json:"events"` + SourceRunID string `json:"sourceRunId"` + rootPID int +} + +type playgroundRecording struct { + RunID string `json:"runId"` + StartedAt time.Time `json:"startedAt"` + EndedAt time.Time `json:"endedAt"` + Kinds []playgroundKind `json:"kinds"` +} + +func exportPlayground(ctx context.Context, o options) (err error) { + info, err := telltale.Get(telltale.GetOptions{DataDir: o.dataDir, RunID: o.verifyRun}) + if err != nil { + return err + } + if info.Status != telltale.StatusSucceeded { + return fmt.Errorf("export needs a succeeded run, got %s", info.Status) + } + result := playgroundRecording{RunID: info.RunID, StartedAt: info.StartedAt, EndedAt: info.EndedAt} + sources, closeSources, err := playgroundSources(ctx, o, info) + if err != nil { + return err + } + defer func() { err = errors.Join(err, closeSources()) }() + for _, registration := range traces.Registrations() { + source := sources["recording"] + if registration.Name == "process" { + source = sources["process"] + } + items, err := source.samples(ctx, registration) + if err != nil { + return err + } + result.Kinds = append(result.Kinds, items...) + } + data, err := json.MarshalIndent(result, "", " ") + if err != nil { + return err + } + if err := os.MkdirAll(filepath.Dir(o.exportPlayground), 0o755); err != nil { + return err + } + if err := os.WriteFile(o.exportPlayground, append(data, '\n'), 0o600); err != nil { + return err + } + fmt.Fprintf(os.Stderr, "Exported %d recorded kinds to %s\n", len(result.Kinds), o.exportPlayground) + return nil +} + +func playgroundSamples(ctx context.Context, refs []read.Ref, item playgroundKind) (playgroundKind, error) { + byVariant := map[string]read.Record{} + q := read.FeedQuery{Query: read.Query{Limit: 500}} + for { + page, err := read.FeedPage(ctx, refs, q) + if err != nil { + return item, err + } + for _, record := range page.Rows { + item.Count++ + if item.Name == "process" && number(record.Record["pid"]) != float64(item.rootPID) { + continue + } + if item.Name == "process_metrics" && !strings.HasPrefix(text(record.Record["entity"]), fmt.Sprintf("%d@", item.rootPID)) { + continue + } + if item.Name == "process_facets" && !strings.HasPrefix(text(record.Record["process"]), fmt.Sprintf("%d@", item.rootPID)) { + continue + } + key := exportSampleKey(item.Name, record.Record) + if key == "" { + continue + } + previous, exists := byVariant[key] + if !exists || number(record.Record["value"]) > number(previous.Record["value"]) { + byVariant[key] = record + } + } + if page.NextCursor == "" { + break + } + q.Cursor = page.NextCursor + } + if len(byVariant) == 0 { + return item, fmt.Errorf("%s: no meaningful recorded playground sample", item.Name) + } + for variant, record := range byVariant { + ansi, err := clicky.Format(record.Pretty(), clicky.FormatOptions{Format: "pretty"}) + if err != nil { + return item, err + } + detail, err := clicky.Format(record.PrettyFull(), clicky.FormatOptions{Format: "pretty"}) + if err != nil { + return item, err + } + item.Events = append(item.Events, playgroundEvent{Variant: variant, Seq: record.Seq, ANSI: ansi, DetailANSI: detail, Record: record.Record}) + } + slices.SortFunc(item.Events, func(a, b playgroundEvent) int { + if a.Seq < b.Seq { + return -1 + } + if a.Seq > b.Seq { + return 1 + } + return 0 + }) + return item, nil +} + +func exportSampleKey(kind string, row query.Row) string { + switch kind { + case "exec": + if filepath.Base(text(row["name"])) == "git" && meaningful(kind, row) { + return "record" + } + case "terminal": + return text(row["kind"]) + case "llm": + return text(row["phase"]) + case "jvm_jfr": + if meaningful(kind, row) { + return text(row["event"]) + } + case "sql_xevent": + if row["name"] == "error_reported" { + if number(row["errorNumber"]) == 1205 { + return "error_reported" + } + } else if strings.Contains(text(row["sql"]), "orders") { + return text(row["name"]) + } + case "stacks": + if meaningful(kind, row) { + return text(row["state"]) + } + case "process_metrics": + if number(row["rssBytes"]) > 0 && row["cpuPercent"] != nil { + return "record" + } + case "process_facets": + if row["resource"] != nil { + return text(row["facet"]) + "/" + text(row["operation"]) + } + default: + if meaningful(kind, row) { + return "record" + } + } + return "" +} diff --git a/hack/demo/export_sources.go b/hack/demo/export_sources.go new file mode 100644 index 0000000..fa55c01 --- /dev/null +++ b/hack/demo/export_sources.go @@ -0,0 +1,112 @@ +package main + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "maps" + "os" + "slices" + "time" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/flanksource/telltale/pkg/tracing" +) + +type playgroundSource struct { + info telltale.RunInfo + runtime *tracing.Runtime +} + +func playgroundSources(ctx context.Context, o options, info telltale.RunInfo) (map[string]playgroundSource, func() error, error) { + runtime, closeRecording, err := telltale.Reopen(o.dataDir, info.RunID) + if err != nil { + return nil, nil, err + } + recording := playgroundSource{info: info, runtime: runtime} + for _, capture := range info.Captures { + if capture.Kind == "process" { + return map[string]playgroundSource{"recording": recording, "process": recording}, closeRecording, nil + } + } + if info.Process != nil && info.Process.Tree.Kind == "process" { + return map[string]playgroundSource{"recording": recording, "process": recording}, closeRecording, nil + } + process, err := recordPlaygroundProcess(ctx, o.dataDir) + if err != nil { + return nil, nil, errors.Join(err, closeRecording()) + } + processRuntime, closeProcess, err := telltale.Reopen(o.dataDir, process.RunID) + if err != nil { + return nil, nil, errors.Join(err, closeRecording()) + } + return map[string]playgroundSource{"recording": recording, "process": {info: process, runtime: processRuntime}}, func() error { return errors.Join(closeRecording(), closeProcess()) }, nil +} + +func recordPlaygroundProcess(ctx context.Context, dataDir string) (info telltale.RunInfo, err error) { + file, err := os.CreateTemp(dataDir, "playground-observed-") + if err != nil { + return info, err + } + defer func() { err = errors.Join(err, file.Close()) }() + run, err := telltale.Start(ctx, telltale.StartOptions{DataDir: dataDir, PID: os.Getpid(), Duration: 3 * time.Second, + Traces: []telltale.TraceSpec{{Kind: "process", Params: json.RawMessage(`{"target":{"seam":"process"},"interval":"500ms","facets":["files"]}`)}}}) + if err != nil { + return info, err + } + defer func() { err = errors.Join(err, run.Stop()) }() + if _, err := run.Wait(); err != nil { + return info, err + } + info = run.Info() + if info.Status != telltale.StatusSucceeded { + return info, fmt.Errorf("local process capture %s: %s", info.RunID, info.Status) + } + fmt.Fprintln(os.Stderr, "Recorded current process examples in", info.RunID) + return info, nil +} + +func (s playgroundSource) samples(ctx context.Context, registration traces.Registration) ([]playgroundKind, error) { + primary := []tracing.TraceRef{} + for _, capture := range s.info.Captures { + if capture.Kind == registration.Name { + primary = append(primary, capture.Ref) + } + } + if s.info.Process != nil { + for _, ref := range []tracing.TraceRef{s.info.Process.Tree, s.info.Process.Stacks} { + if ref.Kind == registration.Name { + primary = append(primary, ref) + } + } + } + byKind, seen := map[string][]read.Ref{}, map[string]bool{} + for _, ref := range primary { + for _, result := range s.runtime.Kinds.CaptureRefs(ref) { + if seen[result.Stream] { + continue + } + seen[result.Stream] = true + byKind[result.Kind] = append(byKind[result.Kind], read.Ref{RunID: s.info.RunID, Runtime: s.runtime, TraceRef: result}) + } + } + if len(byKind) == 0 { + return nil, fmt.Errorf("run %s has no recorded %s capture", s.info.RunID, registration.Name) + } + items := []playgroundKind{} + for _, name := range slices.Sorted(maps.Keys(byKind)) { + plugin, ok := s.runtime.Kinds.Get(name) + if !ok { + return nil, fmt.Errorf("no registered presentation for %s", name) + } + item, err := playgroundSamples(ctx, byKind[name], playgroundKind{Name: name, Title: plugin.Title(), Description: registration.Summary, SourceRunID: s.info.RunID, rootPID: s.info.PID}) + if err != nil { + return nil, err + } + items = append(items, item) + } + return items, nil +} diff --git a/hack/demo/export_test.go b/hack/demo/export_test.go new file mode 100644 index 0000000..339d340 --- /dev/null +++ b/hack/demo/export_test.go @@ -0,0 +1,22 @@ +package main + +import ( + "github.com/flanksource/commons-db/query" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("playground sample selection", func() { + DescribeTable("keeps meaningful native event variants", + func(kind string, row query.Row, key string) { Expect(exportSampleKey(kind, row)).To(Equal(key)) }, + Entry("JFR CPU stack", "jvm_jfr", query.Row{"event": "cpu", "stack": "DemoWorkload.compute", "value": 2}, "cpu"), + Entry("JFR runtime-only sample", "jvm_jfr", query.Row{"event": "cpu", "stack": "[no stack]", "value": 2}, ""), + Entry("LLM request", "llm", query.Row{"phase": "request"}, "request"), + Entry("PTY resize", "terminal", query.Row{"kind": "r"}, "r"), + Entry("deadlock error", "sql_xevent", query.Row{"name": "error_reported", "errorNumber": 1205}, "error_reported"), + Entry("database context notice", "sql_xevent", query.Row{"name": "error_reported", "errorNumber": 5701}, ""), + Entry("process metrics", "process_metrics", query.Row{"rssBytes": 4096, "cpuPercent": 1.5}, "record"), + Entry("process descriptor", "process_facets", query.Row{"facet": "files", "operation": "open", "resource": map[string]any{"name": "playground-observed-recording"}}, "files/open"), + Entry("existing process descriptor", "process_facets", query.Row{"facet": "files", "operation": "open", "resource": map[string]any{"name": "/work/orders.db"}}, "files/open"), + ) +}) diff --git a/hack/demo/generate.go b/hack/demo/generate.go new file mode 100644 index 0000000..b302469 --- /dev/null +++ b/hack/demo/generate.go @@ -0,0 +1,137 @@ +package main + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "os/exec" + "path/filepath" + "runtime" + "time" + + "github.com/flanksource/captain/pkg/ai" + clickyexec "github.com/flanksource/clicky/exec" + "github.com/flanksource/telltale" +) + +func generate(ctx context.Context, o options) (err error) { + var workDir string + defer func() { + if err != nil && workDir != "" { + data, encodeErr := json.Marshal(map[string]string{"error": err.Error(), "dataDir": o.dataDir, "workDir": workDir}) + if encodeErr != nil { + err = errors.Join(err, encodeErr) + return + } + err = errors.Join(err, os.WriteFile(filepath.Join(workDir, "demo-failure.json"), append(data, '\n'), 0o600)) + fmt.Fprintln(os.Stderr, "Partial demo artifacts:", workDir) + } + }() + for _, binary := range []string{"git", "java", "javac", "jcmd", "ps"} { + if _, err := exec.LookPath(binary); err != nil { + return fmt.Errorf("demo prerequisite: %w", err) + } + } + provider, err := prepareLLM(o.model) + if err != nil { + return err + } + lab, err := openLab(ctx) + if err != nil { + return err + } + defer func() { + if lab != nil { + err = errors.Join(err, lab.close()) + } + }() + if err := os.MkdirAll(filepath.Dir(o.dataDir), 0o700); err != nil { + return err + } + dir, err := os.MkdirTemp(filepath.Dir(o.dataDir), "work-") + if err != nil { + return err + } + workDir = dir + local, err := startLocal(ctx, dir) + if err != nil { + return err + } + defer func() { + if local != nil { + err = errors.Join(err, local.close()) + } + }() + jvm, err := startJava(ctx, dir) + if err != nil { + return err + } + defer func() { + if jvm != nil { + err = errors.Join(err, jvm.close()) + } + }() + if err := lab.create(ctx); err != nil { + return err + } + specs, err := demoSpecs(local.url, lab.name, jvm.cmd.Process.Pid) + if err != nil { + return err + } + run, err := telltale.Start(ctx, telltale.StartOptions{DataDir: o.dataDir, PID: os.Getpid(), Every: 3 * time.Second, Traces: specs, Connections: lab.connections}) + if err != nil { + return err + } + fmt.Fprintln(os.Stderr, "Recording demo", run.ID(), "into", run.Dir()) + workErr := exercise(ctx, run, local, lab, provider) + stopErr := run.Stop() + _, waitErr := run.Wait() + err = errors.Join(workErr, stopErr, waitErr, jvm.close(), local.close(), lab.close()) + jvm, local, lab = nil, nil, nil + verificationCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second) + defer cancel() + return verifyStored(verificationCtx, verification{DataDir: o.dataDir, RunID: run.ID(), Failure: err, Sessions: captureSessions(run.Runtime().Sessions.List())}) +} + +func exercise(ctx context.Context, run *telltale.Run, local *localWorkload, lab *labWorkload, provider ai.Provider) error { + for _, capture := range run.Info().Captures { + if capture.Kind == "terminal" { + if err := recordTerminal(ctx, capture.Ref.Stream); err != nil { + return err + } + } + } + if result := clickyexec.NewExec("git", "--version").WithContext(ctx).Run().Result(); result.Error != nil { + return result.Error + } + if err := lab.deadlock(ctx); err != nil { + return err + } + var held [][]byte + ticker := time.NewTicker(250 * time.Millisecond) + defer ticker.Stop() + until := time.NewTimer(20 * time.Second) + defer until.Stop() + for { + select { + case <-ctx.Done(): + return ctx.Err() + case <-until.C: + if err := recordLLM(ctx, provider); err != nil { + return err + } + runtime.KeepAlive(held) + return nil + case <-ticker.C: + held = append(held, make([]byte, 64<<10)) + if err := local.request(ctx); err != nil { + return err + } + if err := lab.query(ctx); err != nil { + return err + } + } + } +} diff --git a/hack/demo/llm.go b/hack/demo/llm.go new file mode 100644 index 0000000..23b4d24 --- /dev/null +++ b/hack/demo/llm.go @@ -0,0 +1,56 @@ +package main + +import ( + "context" + "fmt" + "strings" + "time" + + "github.com/flanksource/captain/pkg/ai" + "github.com/flanksource/captain/pkg/ai/observe" + "github.com/flanksource/captain/pkg/ai/pricing" + _ "github.com/flanksource/captain/pkg/ai/provider" + "github.com/flanksource/captain/pkg/api" +) + +const llmBudget = 0.05 +const outputTokens = 128 +const demoPrompt = "Reply with one short sentence confirming that the acme checkout demonstration is ready." + +func prepareLLM(model string) (ai.Provider, error) { + provider, err := ai.NewProvider(ai.Config{Model: api.Model{Name: model}, Budget: api.Budget{Cost: llmBudget, MaxTokens: outputTokens}, NoCache: true}) + if err != nil { + return nil, err + } + if provider.GetRuntime().Mode != ai.ModeAPI { + return nil, fmt.Errorf("demo requires an API runtime with a bounded output token limit") + } + pricing.EnsureLoaded(pricing.LoadOptions{}) + price, err := pricing.CalculateCost(provider.GetModel(), 1024, outputTokens, outputTokens, 0, 0) + if err != nil { + return nil, fmt.Errorf("demo needs known model pricing: %w", err) + } + if price.TotalCost > llmBudget { + return nil, fmt.Errorf("maximum demo request price $%.4f exceeds $%.2f", price.TotalCost, llmBudget) + } + return observe.Wrap(provider), nil +} + +func recordLLM(ctx context.Context, provider ai.Provider) error { + ctx, cancel := context.WithTimeout(ctx, 20*time.Second) + defer cancel() + response, err := provider.Execute(ctx, ai.Request{Prompt: api.Prompt{User: demoPrompt}, Budget: api.Budget{Cost: llmBudget, MaxTokens: outputTokens, MaxTurns: 1}, Model: api.Model{Name: provider.GetModel(), NoCache: true}}) + if err != nil { + return err + } + if response == nil || strings.TrimSpace(response.Text) == "" { + return fmt.Errorf("LLM returned no text") + } + if response.Usage.TotalTokens() == 0 { + return fmt.Errorf("LLM returned no measured token usage") + } + if response.CostUSD > llmBudget { + return fmt.Errorf("LLM response cost $%.4f exceeded $%.2f", response.CostUSD, llmBudget) + } + return nil +} diff --git a/hack/demo/main.go b/hack/demo/main.go new file mode 100644 index 0000000..d0c5183 --- /dev/null +++ b/hack/demo/main.go @@ -0,0 +1,61 @@ +package main + +import ( + "context" + "flag" + "fmt" + "log" + "os" + "os/signal" + "syscall" + "time" + + "gorm.io/gorm/logger" +) + +type options struct { + dataDir, model, saveConnection, verifyRun, exportPlayground string + timeout time.Duration +} + +func main() { + logger.Default = logger.New(log.New(os.Stderr, "", log.LstdFlags), logger.Config{LogLevel: logger.Warn, SlowThreshold: 200 * time.Millisecond}) + var o options + flag.StringVar(&o.dataDir, "data-dir", ".tmp/demo/data", "Demo trace data directory") + flag.StringVar(&o.model, "model", "", "Captain API model for one request costing at most $0.05") + flag.StringVar(&o.saveConnection, "save-connection-from", "", "Save an existing Connection resource as shared connection://mssql, then exit") + flag.StringVar(&o.verifyRun, "verify-run", "", "Verify an existing demo run without making another LLM call") + flag.StringVar(&o.exportPlayground, "export-playground", "", "Export recorded ANSI events and native rows for the Clicky UI playground (requires --verify-run)") + flag.DurationVar(&o.timeout, "timeout", 2*time.Minute, "Overall recording deadline") + flag.Parse() + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + if err := command(ctx, o); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func command(ctx context.Context, o options) error { + if o.exportPlayground != "" { + if o.verifyRun == "" { + return fmt.Errorf("--export-playground requires --verify-run") + } + return exportPlayground(ctx, o) + } + if o.saveConnection != "" { + return saveConnection(o.saveConnection) + } + if o.verifyRun != "" { + return verifyStored(ctx, verification{DataDir: o.dataDir, RunID: o.verifyRun}) + } + if o.model == "" { + return fmt.Errorf("--model is required; use an authenticated Captain API model") + } + if o.timeout <= 0 { + return fmt.Errorf("--timeout must be positive") + } + ctx, cancel := context.WithTimeout(ctx, o.timeout) + defer cancel() + return generate(ctx, o) +} diff --git a/hack/demo/mssql.go b/hack/demo/mssql.go new file mode 100644 index 0000000..2200890 --- /dev/null +++ b/hack/demo/mssql.go @@ -0,0 +1,158 @@ +package main + +import ( + "context" + "database/sql" + "errors" + "fmt" + "strings" + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/task" + "github.com/flanksource/commons-db/connection/store" + dbcontext "github.com/flanksource/commons-db/context" + commonsctx "github.com/flanksource/commons/context" + mssql "github.com/microsoft/go-mssqldb" + "github.com/microsoft/go-mssqldb/msdsn" +) + +type labWorkload struct { + admin, db *sql.DB + name string + connections *store.Store + created bool +} + +func openLab(ctx context.Context) (*labWorkload, error) { + connections, err := store.Open("telltale") + if err != nil { + return nil, err + } + model, err := connections.ResolveConnection(dbcontext.NewContext(ctx), "connection://mssql") + if err != nil { + return nil, err + } + if model == nil { + return nil, fmt.Errorf("connection://mssql is not configured") + } + config, err := msdsn.Parse(model.URL) + if err != nil { + return nil, fmt.Errorf("invalid SQL Server DSN in connection://mssql") + } + if config.Host != "mssql.lab" || config.Port != 31433 { + return nil, fmt.Errorf("connection://mssql must target mssql.lab:31433") + } + config.Database = "master" + admin, err := sql.Open("sqlserver", config.URL().String()) + if err != nil { + return nil, fmt.Errorf("open lab SQL Server connection") + } + if err := admin.PingContext(ctx); err != nil { + return nil, errors.Join(err, admin.Close()) + } + var canCreate, canObserve int + if err := admin.QueryRowContext(ctx, "SELECT HAS_PERMS_BY_NAME(NULL, NULL, 'CREATE ANY DATABASE'), HAS_PERMS_BY_NAME(NULL, NULL, 'ALTER ANY EVENT SESSION')").Scan(&canCreate, &canObserve); err != nil { + return nil, errors.Join(err, admin.Close()) + } + if canCreate != 1 || canObserve != 1 { + return nil, errors.Join(fmt.Errorf("mssql needs CREATE ANY DATABASE and ALTER ANY EVENT SESSION"), admin.Close()) + } + return &labWorkload{admin: admin, connections: connections, name: fmt.Sprintf("telltale_demo_%d", time.Now().UnixNano())}, nil +} + +func (w *labWorkload) create(ctx context.Context) error { + if _, err := w.admin.ExecContext(ctx, "CREATE DATABASE ["+w.name+"]"); err != nil { + return err + } + w.created = true + // Credentials remain in memory; the trace only names connection://mssql. + connection, err := w.connections.ResolveConnection(dbcontext.NewContext(ctx), "connection://mssql") + if err != nil { + return err + } + config, err := msdsn.Parse(connection.URL) + if err != nil { + return fmt.Errorf("invalid SQL Server DSN") + } + config.Database, config.AppName = w.name, "telltale-demo" + w.db, err = sql.Open("sqlserver", config.URL().String()) + if err != nil { + return fmt.Errorf("open demo database") + } + _, err = w.db.ExecContext(ctx, "CREATE TABLE dbo.orders (id int PRIMARY KEY, value int); INSERT INTO dbo.orders VALUES (1, 0), (2, 0)") + return err +} + +func (w *labWorkload) query(ctx context.Context) error { + var total int + return w.db.QueryRowContext(ctx, "SELECT SUM(value) FROM dbo.orders /* telltale_demo */").Scan(&total) +} + +func (w *labWorkload) deadlock(ctx context.Context) error { + ctx, cancel := context.WithTimeout(ctx, 20*time.Second) + defer cancel() + first, err := w.db.BeginTx(ctx, nil) + if err != nil { + return err + } + defer func() { _ = first.Rollback() }() + second, err := w.db.BeginTx(ctx, nil) + if err != nil { + return err + } + defer func() { _ = second.Rollback() }() + if _, err := first.ExecContext(ctx, "UPDATE dbo.orders SET value=value+1 WHERE id=1"); err != nil { + return err + } + if _, err := second.ExecContext(ctx, "UPDATE dbo.orders SET value=value+1 WHERE id=2"); err != nil { + return err + } + var handles []task.TypedTask[error] + for index, tx := range []*sql.Tx{first, second} { + id, transaction := 2-index, tx + handles = append(handles, clicky.StartTask("Induce demo deadlock", func(_ commonsctx.Context, _ *task.Task) (error, error) { + _, err := transaction.ExecContext(ctx, "UPDATE dbo.orders SET value=value+1 WHERE id=@p1", id) + rollback := transaction.Rollback() + if errors.Is(rollback, sql.ErrTxDone) { + rollback = nil + } + return err, rollback + }, task.WithContext(ctx), task.WithCancellationDrain())) + } + victims := 0 + for _, handle := range handles { + result, err := handle.GetResult() + if err != nil { + return err + } + if result != nil { + var serverError mssql.Error + if !errors.As(result, &serverError) || serverError.Number != 1205 { + return result + } + victims++ + } + } + if victims != 1 { + return fmt.Errorf("expected one deadlock victim, got %d", victims) + } + return nil +} + +func (w *labWorkload) close() error { + var err error + if w.db != nil { + err = w.db.Close() + } + if w.created { + if !strings.HasPrefix(w.name, "telltale_demo_") { + return errors.Join(err, fmt.Errorf("refusing to drop non-demo database"), w.admin.Close()) + } + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + _, dropErr := w.admin.ExecContext(ctx, "DROP DATABASE ["+w.name+"]") + err = errors.Join(err, dropErr) + } + return errors.Join(err, w.admin.Close()) +} diff --git a/hack/demo/sessions.go b/hack/demo/sessions.go new file mode 100644 index 0000000..7d03ad5 --- /dev/null +++ b/hack/demo/sessions.go @@ -0,0 +1,48 @@ +package main + +import ( + "encoding/json" + "errors" + "fmt" + "strings" + + "github.com/flanksource/commons-db/query" +) + +type sessionEvidence struct { + Kind string `json:"kind"` + State query.SessionState `json:"state"` + Error string `json:"error,omitempty"` + Warning string `json:"warning,omitempty"` + Summary json.RawMessage `json:"summary"` +} + +func captureSessions(infos []query.SessionInfo) []sessionEvidence { + result := make([]sessionEvidence, 0, len(infos)) + for _, info := range infos { + result = append(result, sessionEvidence{Kind: strings.TrimPrefix(info.Profile, "traces/"), State: info.State, Error: info.Error, Warning: info.Warning, Summary: info.Summary}) + } + return result +} + +func validateSessions(sessions []sessionEvidence) error { + if len(sessions) == 0 { + return fmt.Errorf("no final session evidence recorded") + } + var failures []error + for _, session := range sessions { + if session.State != query.SessionStopped && session.State != query.SessionCompleted { + failures = append(failures, fmt.Errorf("%s session ended %s: %s", session.Kind, session.State, session.Error)) + } + if session.Warning != "" || session.Error != "" { + failures = append(failures, fmt.Errorf("%s session: %s %s", session.Kind, session.Error, session.Warning)) + } + var summary map[string]any + if err := json.Unmarshal(session.Summary, &summary); err != nil { + failures = append(failures, fmt.Errorf("%s session summary: %w", session.Kind, err)) + } else if err := captureLoss(summary); err != nil { + failures = append(failures, fmt.Errorf("%s session: %w", session.Kind, err)) + } + } + return errors.Join(failures...) +} diff --git a/hack/demo/setup.go b/hack/demo/setup.go new file mode 100644 index 0000000..6574b23 --- /dev/null +++ b/hack/demo/setup.go @@ -0,0 +1,57 @@ +package main + +import ( + "fmt" + "os" + "path/filepath" + + "github.com/flanksource/commons-db/connection/crd" + "github.com/flanksource/commons-db/connection/store" + "github.com/flanksource/commons-db/types" + "github.com/microsoft/go-mssqldb/msdsn" + "sigs.k8s.io/yaml" +) + +func saveConnection(source string) error { + data, err := os.ReadFile(source) + if err != nil { + return err + } + var resource crd.Connection + if err := yaml.UnmarshalStrict(data, &resource); err != nil { + return fmt.Errorf("decode connection resource: invalid YAML") + } + model, err := crd.ToModel(&resource) + if err != nil { + return fmt.Errorf("decode connection resource: invalid connection") + } + config, err := msdsn.Parse(model.URL) + if err != nil { + return fmt.Errorf("parse SQL Server connection: invalid DSN") + } + if config.Host != "mssql.lab" || config.Port != 31433 { + return fmt.Errorf("expected mssql.lab:31433") + } + config.Database = "master" + resource.Name, resource.Namespace = "mssql", "" + resource.Spec = crd.ConnectionSpec{Type: "sql_server", URL: types.EnvVar{ValueStatic: config.URL().String()}} + connections, err := store.Open("telltale") + if err != nil { + return err + } + global, err := store.ConfigDir(store.GlobalApp) + if err != nil { + return err + } + path := filepath.Join(global, "connections", "mssql.yaml") + if _, err := os.Stat(path); err == nil { + return fmt.Errorf("connection://mssql already exists; refusing to overwrite %s", path) + } else if !os.IsNotExist(err) { + return err + } + if err := connections.Save(store.LayerGlobal, &resource); err != nil { + return err + } + fmt.Println("Saved connection://mssql at", path) + return nil +} diff --git a/hack/demo/setup_test.go b/hack/demo/setup_test.go new file mode 100644 index 0000000..0662442 --- /dev/null +++ b/hack/demo/setup_test.go @@ -0,0 +1,43 @@ +package main + +import ( + "os" + "path/filepath" + + "github.com/flanksource/commons-db/connection/crd" + "github.com/flanksource/commons-db/types" + "github.com/microsoft/go-mssqldb/msdsn" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "sigs.k8s.io/yaml" +) + +var _ = Describe("shared lab connection", func() { + It("normalizes the lab DSN, saves privately, and refuses to overwrite it", func() { + dir := GinkgoT().TempDir() + GinkgoT().Setenv("XDG_CONFIG_HOME", dir) + resource := crd.Connection{} + resource.Name = "lab" + resource.Spec = crd.ConnectionSpec{Type: "sql_server", URL: types.EnvVar{ValueStatic: "sqlserver://mssql.lab:31433?database=example"}} + data, err := yaml.Marshal(resource) + Expect(err).NotTo(HaveOccurred()) + source := filepath.Join(dir, "lab.yaml") + Expect(os.WriteFile(source, data, 0o600)).To(Succeed()) + Expect(saveConnection(source)).To(Succeed()) + path := filepath.Join(dir, "flanksource", "connections", "mssql.yaml") + info, err := os.Stat(path) + Expect(err).NotTo(HaveOccurred()) + Expect(info.Mode().Perm()).To(Equal(os.FileMode(0o600))) + stored, err := os.ReadFile(path) + Expect(err).NotTo(HaveOccurred()) + Expect(yaml.UnmarshalStrict(stored, &resource)).To(Succeed()) + config, err := msdsn.Parse(resource.Spec.URL.ValueStatic) + Expect(err).NotTo(HaveOccurred()) + Expect(config.Database).To(Equal("master")) + Expect(resource.Name).To(Equal("mssql")) + Expect(saveConnection(source)).To(MatchError(ContainSubstring("refusing to overwrite"))) + again, err := os.ReadFile(path) + Expect(err).NotTo(HaveOccurred()) + Expect(again).To(Equal(stored)) + }) +}) diff --git a/hack/demo/specs.go b/hack/demo/specs.go new file mode 100644 index 0000000..518ade8 --- /dev/null +++ b/hack/demo/specs.go @@ -0,0 +1,51 @@ +package main + +import ( + "encoding/json" + "fmt" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/traces" +) + +func demoSpecs(url, database string, javaPID int) ([]telltale.TraceSpec, error) { + self := map[string]any{"seam": "self"} + params := map[string]map[string]any{ + "process": {"target": map[string]any{"seam": "process"}, "interval": "500ms", "facets": []string{"files", "sockets", "connections"}}, + "stacks": {"target": self}, + "goprof": {"target": self}, + "http": {"target": self, "features": []string{"demo"}}, + "sql": {"target": self, "connections": []string{"demo"}}, + "exec": {"target": self, "tailBytes": 4096}, + "logs": {"target": self, "minLevel": "info"}, + "spans": {"target": self}, + "terminal": {"target": self, "width": 100, "height": 24, "command": []string{"git", "--version"}}, + "jvm_jfr": {"target": map[string]any{"seam": "process", "pid": javaPID}, "engine": "jfr", "settings": "profile", "threads": true}, + "prometheus": {"target": map[string]any{"seam": "host"}, "endpoints": []string{url + "/metrics"}, "interval": "1s"}, + "query": {"target": map[string]any{"seam": "host"}, "untilStopped": true, "provider": map[string]any{"type": "prometheus", "connection": "connection://telltale-prometheus", "query": "demo_requests_total", "prometheus": map[string]any{"range": map[string]any{"step": "1s"}}}}, + "sql_xevent": {"connection": "connection://mssql", "databases": []string{database}, "sessionName": database, "poll": "200ms"}, + "sql_plancache": {"connection": "connection://mssql", "databases": []string{database}, "poll": "1s", "top": 20}, + "sql_deadlock": {"connection": "connection://mssql", "databases": []string{database}, "poll": "1s"}, + "llm": {"target": self, "includePrompts": true, "includeResponses": true}, + } + if len(params) != len(traces.Registrations()) { + return nil, fmt.Errorf("demo workload catalog has %d kinds; registry has %d", len(params), len(traces.Registrations())) + } + var specs []telltale.TraceSpec + for _, registration := range traces.Registrations() { + p, exists := params[registration.Name] + if !exists { + return nil, fmt.Errorf("no real demo workload for registered kind %s", registration.Name) + } + raw, err := json.Marshal(p) + if err != nil { + return nil, err + } + spec := telltale.TraceSpec{Kind: registration.Name, Params: raw} + if registration.Name == "goprof" { + spec.Checkpoint = json.RawMessage(`{"profile":"heap","source":"gops","reason":"demo"}`) + } + specs = append(specs, spec) + } + return specs, nil +} diff --git a/hack/demo/workloads.go b/hack/demo/workloads.go new file mode 100644 index 0000000..a450063 --- /dev/null +++ b/hack/demo/workloads.go @@ -0,0 +1,171 @@ +package main + +import ( + "context" + "database/sql" + _ "embed" + "encoding/json" + "errors" + "fmt" + "io" + "log/slog" + "net" + "net/http" + "os" + "os/exec" + "path/filepath" + "sync/atomic" + "syscall" + "time" + + "github.com/creack/pty" + "github.com/flanksource/clicky" + clickyexec "github.com/flanksource/clicky/exec" + "github.com/flanksource/clicky/task" + "github.com/flanksource/commons-db/observability" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons-db/query/providers/sqlite" + commonsctx "github.com/flanksource/commons/context" + "github.com/flanksource/telltale/pkg/tracing/terminal" + sdk "github.com/flanksource/telltale/sdk" +) + +//go:embed DemoWorkload.java +var javaSource []byte + +type localWorkload struct { + url string + db *sql.DB + server *http.Server + serve task.TypedTask[struct{}] + requests atomic.Int64 +} + +func startLocal(ctx context.Context, dir string) (*localWorkload, error) { + db, err := sql.Open("sqlite", filepath.Join(dir, "orders.sqlite")) + if err != nil { + return nil, err + } + if _, err := db.ExecContext(ctx, "CREATE TABLE orders (id INTEGER PRIMARY KEY, name TEXT); INSERT INTO orders VALUES (1, 'acme checkout'), (2, 'acme shipment')"); err != nil { + return nil, errors.Join(err, db.Close()) + } + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + return nil, errors.Join(err, db.Close()) + } + w := &localWorkload{db: db, url: "http://" + listener.Addr().String()} + mux := http.NewServeMux() + mux.HandleFunc("GET /orders", w.orders) + mux.HandleFunc("GET /metrics", func(out http.ResponseWriter, _ *http.Request) { + out.Header().Set("Content-Type", "text/plain; version=0.0.4") + if _, err := fmt.Fprintf(out, "# TYPE demo_requests_total counter\ndemo_requests_total %d\n", w.requests.Load()); err != nil { + slog.Error("write metrics", "error", err) + } + }) + w.server = &http.Server{Handler: mux, ReadHeaderTimeout: 5 * time.Second} + w.serve = clicky.StartTask("Demo HTTP server", func(_ commonsctx.Context, _ *task.Task) (struct{}, error) { + err := w.server.Serve(listener) + if errors.Is(err, http.ErrServerClosed) { + err = nil + } + return struct{}{}, err + }, task.WithContext(ctx), task.WithCancellationDrain()) + return w, nil +} + +func (w *localWorkload) orders(out http.ResponseWriter, request *http.Request) { + ctx, end := sdk.StartSpan(request.Context(), "demo.orders", "service.name", "telltale-demo") + result, err := sqlite.ReadSQLPage(ctx, w.db, "sqlite", sqlite.SQLPageRequest{Connection: "demo", Query: "SELECT id, name FROM orders", Page: query.PageRequest{Limit: 10}}) + end(err) + if err != nil { + http.Error(out, "read demo orders", http.StatusInternalServerError) + return + } + w.requests.Add(1) + slog.New(sdk.SlogHandler(slog.NewTextHandler(io.Discard, nil))).InfoContext(ctx, "demo orders read", "rows", len(result.Rows)) + out.Header().Set("Content-Type", "application/json") + if err := json.NewEncoder(out).Encode(result.Rows); err != nil { + slog.Error("write orders", "error", err) + } +} + +func (w *localWorkload) request(ctx context.Context) error { + client := &http.Client{Transport: observability.ApplyHTTPObservability(ctx, "demo", nil, nil), Timeout: 5 * time.Second} + req, err := http.NewRequestWithContext(ctx, http.MethodGet, w.url+"/orders", nil) + if err != nil { + return err + } + response, err := client.Do(req) + if err != nil { + return err + } + _, readErr := io.Copy(io.Discard, response.Body) + if response.StatusCode != http.StatusOK { + readErr = errors.Join(readErr, fmt.Errorf("orders returned %d", response.StatusCode)) + } + return errors.Join(readErr, response.Body.Close()) +} + +func (w *localWorkload) close() error { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + err := w.server.Shutdown(ctx) + if err != nil { + err = errors.Join(err, w.server.Close()) + } + _, serveErr := w.serve.GetResult() + return errors.Join(err, serveErr, w.db.Close()) +} + +type javaWorkload struct { + cmd *exec.Cmd + input io.WriteCloser + output *os.File +} + +func startJava(ctx context.Context, dir string) (*javaWorkload, error) { + source := filepath.Join(dir, "DemoWorkload.java") + if err := os.WriteFile(source, javaSource, 0o600); err != nil { + return nil, err + } + if result := clickyexec.NewExec("javac", "-d", dir, source).WithContext(ctx).Run().Result(); result.Error != nil { + return nil, fmt.Errorf("compile demo JVM: %w", result.Error) + } + output, err := os.Create(filepath.Join(dir, "jvm.log")) + if err != nil { + return nil, err + } + cmd := exec.CommandContext(ctx, "java", "-Xmx64m", "-cp", dir, "DemoWorkload") + cmd.Stdout, cmd.Stderr = output, output + input, err := cmd.StdinPipe() + if err != nil { + return nil, errors.Join(err, output.Close()) + } + if err := cmd.Start(); err != nil { + return nil, errors.Join(err, input.Close(), output.Close()) + } + return &javaWorkload{cmd: cmd, input: input, output: output}, nil +} + +func (w *javaWorkload) close() error { + return errors.Join(w.input.Close(), w.cmd.Wait(), w.output.Close()) +} + +func recordTerminal(ctx context.Context, stream string) (err error) { + writer, err := terminal.Writer(stream) + if err != nil { + return err + } + defer func() { err = errors.Join(err, writer.Close()) }() + cmd := exec.CommandContext(ctx, "git", "--version") + file, err := pty.StartWithSize(cmd, &pty.Winsize{Rows: 24, Cols: 100}) + if err != nil { + return err + } + _, copyErr := io.Copy(writer, file) + if errors.Is(copyErr, syscall.EIO) { + copyErr = nil + } + waitErr := cmd.Wait() + return errors.Join(copyErr, waitErr, terminal.Resize(stream, 120, 30), terminal.SetExitCode(stream, cmd.ProcessState.ExitCode()), file.Close()) +} diff --git a/hack/docs-catalog/main.go b/hack/docs-catalog/main.go new file mode 100644 index 0000000..d85b50c --- /dev/null +++ b/hack/docs-catalog/main.go @@ -0,0 +1,82 @@ +package main + +import ( + "bytes" + "encoding/json" + "flag" + "fmt" + "os" + + "github.com/flanksource/telltale/internal/cli" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/spf13/pflag" +) + +type kind struct { + tracing.KindInfo + Flags []argument `json:"flags"` +} + +type argument struct { + Name string `json:"name"` + Type string `json:"type"` + Description string `json:"description"` + Default string `json:"default"` + Required bool `json:"required"` +} + +func main() { + check := flag.Bool("check", false, "check that the documentation catalog is current") + flag.Parse() + kinds, err := traces.Kinds() + if err != nil { + fatal(err) + } + list, err := kinds.List() + if err != nil { + fatal(err) + } + root := cli.NewRoot("dev") + entries := make([]kind, 0, len(list)) + for _, info := range list { + cmd, _, err := root.Find([]string{"run", info.Name}) + if err != nil || cmd.Name() != info.Name { + fatal(fmt.Errorf("find command for trace kind %s: %v", info.Name, err)) + } + entry := kind{KindInfo: info, Flags: []argument{}} + cmd.Flags().VisitAll(func(f *pflag.Flag) { + if !f.Hidden && f.Name != "help" { + entry.Flags = append(entry.Flags, argument{Name: f.Name, Type: f.Value.Type(), Description: f.Usage, Default: f.DefValue, Required: len(f.Annotations["cobra_annotation_bash_completion_one_required_flag"]) > 0}) + } + }) + entries = append(entries, entry) + } + data, err := json.MarshalIndent(entries, "", " ") + if err != nil { + fatal(err) + } + data = append(data, '\n') + const path = "docs/_data/kinds.json" + if *check { + current, err := os.ReadFile(path) + if err != nil { + fatal(err) + } + if !bytes.Equal(current, data) { + fatal(fmt.Errorf("%s is stale; run go run ./hack/docs-catalog", path)) + } + return + } + if err := os.MkdirAll("docs/_data", 0o755); err != nil { + fatal(err) + } + if err := os.WriteFile(path, data, 0o644); err != nil { + fatal(err) + } +} + +func fatal(err error) { + _, _ = fmt.Fprintln(os.Stderr, err) + os.Exit(1) +} From 5439e35777b503db070be92037924c98a7120b5a Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:06:39 +0200 Subject: [PATCH 10/89] feat(webapp): add memory hog pinning, compressed and swap columns, and gavel slot grouping --- webapp/package.json | 2 +- webapp/src/App.tsx | 3 + webapp/src/otel/OtelPage.test.tsx | 1 + webapp/src/otel/OtelPage.tsx | 1 - webapp/src/routes.test.tsx | 12 +++- webapp/src/top/GroupsTable.test.tsx | 21 ++++-- webapp/src/top/GroupsTable.tsx | 40 ++++++++---- webapp/src/top/ProcessPage.test.tsx | 12 ++-- webapp/src/top/ProcessPage.tsx | 20 ++++-- webapp/src/top/RecordedGroups.test.tsx | 88 +++++++++----------------- webapp/src/top/RecordedGroups.tsx | 52 +++++++-------- webapp/src/top/TopPage.test.tsx | 7 +- webapp/src/top/TopPage.tsx | 2 +- webapp/src/top/api.ts | 32 +++++++++- webapp/src/top/grouping.test.tsx | 22 ++++++- webapp/src/top/grouping.ts | 52 +++++++++++++-- webapp/src/top/groups.ts | 16 +++-- webapp/src/top/hogs.test.tsx | 37 +++++++++++ webapp/src/top/hogs.ts | 22 +++++++ webapp/src/top/processes.ts | 16 +++-- webapp/src/traces/TracesPage.test.tsx | 50 +++++++++------ webapp/src/traces/TracesPage.tsx | 33 ++++++++-- webapp/src/traces/TracesPanel.tsx | 56 +++------------- webapp/src/traces/api.ts | 1 + webapp/src/traces/feed.ts | 42 ++++++++++++ webapp/src/traces/processData.test.tsx | 20 ++++++ webapp/src/traces/processData.ts | 77 ++++++++++++++++++++++ webapp/src/traces/useProcessTrace.ts | 49 ++++++++++---- webapp/vite.config.test.ts | 11 ++++ webapp/vite.config.ts | 10 ++- 30 files changed, 581 insertions(+), 226 deletions(-) create mode 100644 webapp/src/top/hogs.test.tsx create mode 100644 webapp/src/top/hogs.ts create mode 100644 webapp/src/traces/feed.ts create mode 100644 webapp/src/traces/processData.test.tsx create mode 100644 webapp/src/traces/processData.ts diff --git a/webapp/package.json b/webapp/package.json index ae81b9f..542469c 100644 --- a/webapp/package.json +++ b/webapp/package.json @@ -10,7 +10,7 @@ }, "dependencies": { "@ai-sdk/react": "^3.0.318", - "@flanksource/clicky-ui": "0.3.56", + "@flanksource/clicky-ui": "0.3.58", "@tanstack/react-query": "^5.101.4", "ai": "^6.0.315", "react": "^19.2.8", diff --git a/webapp/src/App.tsx b/webapp/src/App.tsx index 1cd3926..634a0ce 100644 --- a/webapp/src/App.tsx +++ b/webapp/src/App.tsx @@ -3,14 +3,17 @@ import { useTheme } from "@flanksource/clicky-ui/hooks"; import { RouterProvider, useBrowserRouter, useRouter } from "@flanksource/clicky-ui/rpc"; import { AppRoutes, matchRoute } from "./routes"; import { CommandSearch } from "./search/CommandSearch"; +import TracesPage from "./traces/TracesPage"; function Shell() { const { resolvedTheme, setTheme } = useTheme(); const { pathname } = useRouter(); const page = matchRoute(pathname).page; + if (new URLSearchParams(window.location.search).get("viewer") === "1") return ; return ( Telltale
    } + nav={page === "otel" ?

    OpenTelemetry traces

    : undefined} contentWidth="contained" search={} navSections={[{ diff --git a/webapp/src/otel/OtelPage.test.tsx b/webapp/src/otel/OtelPage.test.tsx index b50b36b..0a2c7bc 100644 --- a/webapp/src/otel/OtelPage.test.tsx +++ b/webapp/src/otel/OtelPage.test.tsx @@ -90,6 +90,7 @@ describe("trace search", () => { renderPage(); expect(await screen.findByRole("button", { name: /POST \/orders.*p50 100 ms · p95 100 ms/ })).toBeInTheDocument(); + expect(screen.queryByRole("heading", { name: "OpenTelemetry traces" })).not.toBeInTheDocument(); expect(screen.getByRole("button", { name: /gorm\.Query.*98 single-span/ })).toHaveClass("opacity-50"); expect(Object.fromEntries(lastSearch(fetchMock))).toEqual({ source: "records", lookback: "1h", limit: "100", minSpans: "2" }); expect(screen.getByText("1 error")).toBeInTheDocument(); diff --git a/webapp/src/otel/OtelPage.tsx b/webapp/src/otel/OtelPage.tsx index 94b7c4b..d75daf5 100644 --- a/webapp/src/otel/OtelPage.tsx +++ b/webapp/src/otel/OtelPage.tsx @@ -79,7 +79,6 @@ export default function OtelPage({ traceId }: { traceId?: string }) { } return (
    -

    OpenTelemetry traces

    ); diff --git a/webapp/src/routes.test.tsx b/webapp/src/routes.test.tsx index 2bb4dc7..c2af745 100644 --- a/webapp/src/routes.test.tsx +++ b/webapp/src/routes.test.tsx @@ -1,5 +1,5 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; -import { fireEvent, render, screen } from "@testing-library/react"; +import { fireEvent, render, screen, within } from "@testing-library/react"; import { DensityProvider, ThemeProvider } from "@flanksource/clicky-ui/hooks"; import { RouterProvider, useMemoryRouter } from "@flanksource/clicky-ui/rpc"; import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; @@ -113,6 +113,16 @@ describe("AppRoutes", () => { }); describe("App", () => { + it.each(["/otel", "/otel/73748978474d62e1e4f6e744a3c5f605"])("shows the trace title in the AppShell navbar at %s", async pathname => { + window.history.replaceState(null, "", pathname); + serve(); + render( + , + ); + expect(within(screen.getByRole("banner")).getByRole("heading", { name: "OpenTelemetry traces", level: 1 })).toBeInTheDocument(); + expect(within(screen.getByRole("main")).queryByRole("heading", { name: "OpenTelemetry traces" })).not.toBeInTheDocument(); + }); + it("navigates between Overview and Top in the browser, marking the current one", async () => { window.history.replaceState(null, "", "/top/123"); serve(); diff --git a/webapp/src/top/GroupsTable.test.tsx b/webapp/src/top/GroupsTable.test.tsx index 85452e0..97d98a2 100644 --- a/webapp/src/top/GroupsTable.test.tsx +++ b/webapp/src/top/GroupsTable.test.tsx @@ -16,6 +16,19 @@ function renderTable(overrides: Partial = {}, groups = sampleFrame() const cells = (name: RegExp) => within(screen.getByRole("row", { name })).getAllByRole("cell").map(cell => cell.textContent); describe("GroupsTable", () => { + it("reveals a pinned other-process hog and still lets its parent be collapsed and reopened", () => { + const frame = othersFrame(); + for (const group of frame.groups) { + if (group.key === "other:user" || group.name === "Slack") group.total.hogs = { memory: "2026-10-25T10:02:00Z" }; + } + renderTable({}, frame.groups); + expect(screen.getByText("Slack")).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Collapse other" })); + expect(screen.queryByText("Slack")).not.toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Expand other" })); + expect(screen.getByText("Slack")).toBeInTheDocument(); + }); + it("shows aggregate repository buckets and folds their tools", () => { renderTable({ groupBy: "repo" }, fixture.frame.groups as Frame["groups"]); const bucket = screen.getByRole("button", { name: "Collapse acme" }); @@ -29,9 +42,9 @@ describe("GroupsTable", () => { it("shows each group's total, and a dash for what is unknown rather than zero", () => { renderTable(); - // Group, Procs, CPU %, RSS, Disk read/s, Disk write/s, Net in/s, Net out/s, Sockets, Origin, Owner, Context - expect(cells(/vitest/)).toEqual(["vitest", "2", "30.0", "300 MiB", "–", "–", "1.5 KiB/s", "–", "–", "", "", ""]); - expect(cells(/^claude/)).toEqual(["claude 01234567", "5", "12.5", "600 MiB", "2 KiB/s", "0 B/s", "–", "–", "7", "", "", "telltale@main claude:0123456… cmux:workspa…"]); + // Group, Procs, CPU %, RSS, Compressed, Swap, Disk read/s, Disk write/s, Net in/s, Net out/s, Sockets, Origin, Owner, Context + expect(cells(/vitest/)).toEqual(["vitest", "2", "30.0", "300 MiB", "–", "–", "–", "–", "1.5 KiB/s", "–", "–", "", "", ""]); + expect(cells(/^claude/)).toEqual(["claude 01234567", "5", "12.5", "600 MiB", "–", "–", "2 KiB/s", "0 B/s", "–", "–", "7", "", "", "telltale@main claude:0123456… cmux:workspa…"]); }); it("indents a child under its parent and keeps the tree order", () => { @@ -98,7 +111,7 @@ function renderLive(initialPath = "/top", overrides: Partial = {}) { describe("GroupsTable origin, scope and the other processes tree", () => { it("shows what started a group and who owns it, in the Origin and Owner columns", () => { renderLive(); - // Group, Procs, CPU %, RSS, Disk read/s, Disk write/s, Net in/s, Net out/s, Sockets, Origin, Owner, Context + // Group, Procs, CPU %, RSS, Compressed, Swap, Disk read/s, Disk write/s, Net in/s, Net out/s, Sockets, Origin, Owner, Context const service = cells(/^postgresql@17/); expect(service.slice(-3)).toEqual(["brew:postgresql@17", "moshe (user)", ""]); expect(screen.getByRole("columnheader", { name: "Origin" })).toBeInTheDocument(); diff --git a/webapp/src/top/GroupsTable.tsx b/webapp/src/top/GroupsTable.tsx index 55dcb69..bc42d51 100644 --- a/webapp/src/top/GroupsTable.tsx +++ b/webapp/src/top/GroupsTable.tsx @@ -4,6 +4,7 @@ import { useRouter } from "@flanksource/clicky-ui/rpc"; import { GROUP_KINDS, SCOPES, type GroupKind, type GroupSample, type Scope, type Usage } from "./api"; import { GROUPINGS, GROUPING_LABELS, type GroupBy } from "./grouping"; import { isCPUHog } from "./cpu"; +import { hogLabel, isPinned } from "./hogs"; import { contextText, formatBytes, formatCount, formatPercent, formatRate, groupLabel, groupPath, groupRows, isSyntheticOther, originText, type GroupsView, type SortKey, @@ -19,6 +20,8 @@ const COLUMNS: Column[] = [ { key: "procs", label: "Procs", value: usage => String(usage.processes) }, { key: "cpu", label: "CPU %", value: usage => formatPercent(usage.cpuPercent) }, { key: "rss", label: "RSS", value: usage => formatBytes(usage.rssBytes) }, + { key: "compressed", label: "Compressed", value: usage => formatBytes(usage.compressedBytes) }, + { key: "swap", label: "Swap", value: usage => formatBytes(usage.swapBytes) }, { key: "diskRead", label: "Disk read/s", value: usage => formatRate(usage.diskReadBps) }, { key: "diskWrite", label: "Disk write/s", value: usage => formatRate(usage.diskWriteBps) }, { key: "netRx", label: "Net in/s", value: usage => formatRate(usage.netRxBps) }, @@ -104,8 +107,9 @@ function GroupRowView({ group, depth, trend, link, expanded, onToggle, cores }: const label = groupLabel(group); const path = link ? groupPath(group) : undefined; const origin = originText(group.origin); + const hog = hogLabel(group.total, group.sampledAt) || (isCPUHog(group.total.cpuPercent, cores) ? "CPU hog" : ""); return ( - + {(isSyntheticOther(group) || group.kind === "bucket") && ( @@ -116,7 +120,7 @@ function GroupRowView({ group, depth, trend, link, expanded, onToggle, cores }: {path ? renderLink({ to: path, className: "hover:underline", children: label, title: `Processes of ${label}` }) : label} - {isCPUHog(group.total.cpuPercent, cores) && CPU hog} + {hog && {hog}} {trend !== undefined && ( @@ -131,7 +135,7 @@ function GroupRowView({ group, depth, trend, link, expanded, onToggle, cores }: )} {COLUMNS.map(column => ( - + {column.value(group.total)} ))} @@ -162,11 +166,18 @@ export function GroupsTable({ groups, view, onViewChange, trend, linkGroups = fa const rows = useMemo(() => groupRows(groups, view, expanded, collapsed), [groups, view, expanded, collapsed]); if (groups.length === 0) return

    No process groups yet.

    ; if (rows.length === 0) return

    No group matches these filters.

    ; - const toggle = (key: string, bucket: boolean) => (bucket ? setCollapsed : setExpanded)(previous => { - const next = new Set(previous); - if (!next.delete(key)) next.add(key); - return next; - }); + const toggle = (key: string, open: boolean) => { + setExpanded(previous => { + const next = new Set(previous); + if (open) next.delete(key); else next.add(key); + return next; + }); + setCollapsed(previous => { + const next = new Set(previous); + if (open) next.add(key); else next.delete(key); + return next; + }); + }; const sortBy = (key: SortKey) => onViewChange(view.sort === key ? { dir: view.dir === "desc" ? "asc" : "desc" } : { sort: key, dir: key === "name" ? "asc" : "desc" }); @@ -192,18 +203,19 @@ export function GroupsTable({ groups, view, onViewChange, trend, linkGroups = fa - {rows.map(({ group, depth }) => ( - { + const open = (!collapsed.has(group.key) && (group.kind === "bucket" || expanded.has(group.key) || isPinned(group.total, group.sampledAt))) || !!view.q.trim(); + return toggle(group.key, group.kind === "bucket")} - /> - ))} + expanded={open} + onToggle={() => toggle(group.key, open)} + />; + })} diff --git a/webapp/src/top/ProcessPage.test.tsx b/webapp/src/top/ProcessPage.test.tsx index d9f5441..3487bdf 100644 --- a/webapp/src/top/ProcessPage.test.tsx +++ b/webapp/src/top/ProcessPage.test.tsx @@ -114,9 +114,9 @@ describe("process totals", () => { it("sorts by CPU or RSS, highest first, and filters by name, command, owner and origin", () => { const processes = reading().processes; - expect(sortProcesses(processes, "cpu").map(p => p.pid)).toEqual([101, 202]); - expect(sortProcesses(processes, "rss").map(p => p.pid)).toEqual([101, 202]); - expect(sortProcesses([processes[1]!, { ...processes[0]!, rssBytes: 1 }], "rss").map(p => p.pid)).toEqual([202, 101]); + expect(sortProcesses(processes, { by: "cpu", sampledAt: reading().sampledAt }).map(p => p.pid)).toEqual([101, 202]); + expect(sortProcesses(processes, { by: "rss", sampledAt: reading().sampledAt }).map(p => p.pid)).toEqual([101, 202]); + expect(sortProcesses([processes[1]!, { ...processes[0]!, rssBytes: 1 }], { by: "rss", sampledAt: reading().sampledAt }).map(p => p.pid)).toEqual([202, 101]); expect(filterProcesses(processes, "--CHILD").map(p => p.pid)).toEqual([202]); expect(filterProcesses(processes, "root").map(p => p.pid)).toEqual([101]); expect(filterProcesses(processes, "launchd:com.example").map(p => p.pid)).toEqual([101]); @@ -189,9 +189,9 @@ describe("ProcessPage", () => { renderPage("launchd"); await screen.findByRole("row", { name: /--child/ }); const cells = (name: RegExp) => within(screen.getByRole("row", { name })).getAllByRole("cell").map(cell => cell.textContent); - // PID, PPID, Name, Owner, Scope, Origin, CPU %, RSS, Disk read/s, Disk write/s, Net in/s, Net out/s, Sockets, Command - expect(cells(/^101/)).toEqual(["101", "1", "launchd", "root", "system", "launchd:com.example.launchd root", "150.0", "2 GiB", "2 KiB/s", "1 KiB/s", "4 KiB/s", "512 B/s", "3", "/usr/bin/launchd", "TerminateRenice"]); - expect(cells(/^202/)).toEqual(["202", "101", "launchd", "moshe", "user", "", "50.0", "1 GiB", "–", "–", "–", "–", "–", "launchd --child", "TerminateRenice"]); + // PID, PPID, Name, Owner, Scope, Origin, CPU %, RSS, Compressed, Swap, Disk read/s, Disk write/s, Net in/s, Net out/s, Sockets, Command + expect(cells(/^101/)).toEqual(["101", "1", "launchd", "root", "system", "launchd:com.example.launchd root", "150.0", "2 GiB", "–", "–", "2 KiB/s", "1 KiB/s", "4 KiB/s", "512 B/s", "3", "/usr/bin/launchd", "TerminateRenice"]); + expect(cells(/^202/)).toEqual(["202", "101", "launchd", "moshe", "user", "", "50.0", "1 GiB", "–", "–", "–", "–", "–", "–", "–", "launchd --child", "TerminateRenice"]); expect(screen.getAllByRole("row").slice(1).map(row => within(row).getAllByRole("cell")[0]!.textContent)).toEqual(["101", "202"]); }); diff --git a/webapp/src/top/ProcessPage.tsx b/webapp/src/top/ProcessPage.tsx index 5c870e4..abd8725 100644 --- a/webapp/src/top/ProcessPage.tsx +++ b/webapp/src/top/ProcessPage.tsx @@ -8,6 +8,7 @@ import { appendFrame, formatBytes, formatCount, formatPercent, formatRate, origi import { FacetsPanel } from "./FacetsPanel"; import { toneOf } from "./HostStrip"; import { isCPUHog } from "./cpu"; +import { hogLabel } from "./hogs"; import { ProcessActions } from "./ProcessActions"; import { RefreshControl, useRefreshInterval } from "../monitoring/RefreshControl"; import { @@ -30,6 +31,8 @@ const PEAK = (_host: HostUsage | undefined, peak: number) => Math.max(peak, 1); const METRIC_VIEWS: MetricView[] = [ { metric: "cpu", label: "CPU %", format: formatPercent, max: (host, peak) => (host ? host.cores * 100 : Math.max(peak, 100)) }, { metric: "rss", label: "RSS", format: formatBytes, max: (host, peak) => (host ? host.memoryTotalBytes : Math.max(peak, 1)) }, + { metric: "compressed", label: "Compressed", format: formatBytes, max: (host, peak) => (host ? host.memoryTotalBytes : Math.max(peak, 1)) }, + { metric: "swap", label: "Swap", format: formatBytes, max: (host, peak) => host?.swapTotalBytes || Math.max(peak, 1) }, { metric: "diskRead", label: "Disk read/s", format: formatRate, max: PEAK }, { metric: "diskWrite", label: "Disk write/s", format: formatRate, max: PEAK }, { metric: "netRx", label: "Net in/s", format: formatRate, max: PEAK }, @@ -69,6 +72,7 @@ function SortHeader({ label, active, onClick }: { label: string; active: boolean } interface ProcessTableProps { + sampledAt: string; cores: number | undefined; processes: ProcessSample[]; sort: ProcessSortKey; @@ -78,7 +82,7 @@ interface ProcessTableProps { onSelect: (pid: number) => void; } -function ProcessTable({ processes, sort, onSort, selected, onSelect, cores }: ProcessTableProps) { +function ProcessTable({ processes, sort, onSort, selected, onSelect, cores, sampledAt }: ProcessTableProps) { const { renderLink } = useRouter(); const muted = "whitespace-nowrap px-2 py-1 text-muted-foreground"; const number = "whitespace-nowrap px-2 py-1 text-right tabular-nums"; @@ -95,6 +99,8 @@ function ProcessTable({ processes, sort, onSort, selected, onSelect, cores }: Pr Origin onSort("cpu")} /> onSort("rss")} /> + onSort("compressed")} /> + onSort("swap")} /> Disk read/s Disk write/s Net in/s @@ -110,7 +116,7 @@ function ProcessTable({ processes, sort, onSort, selected, onSelect, cores }: Pr key={process.key} aria-selected={process.pid === selected} title="Show this process's environment, files and connections" - className={`cursor-pointer border-t border-border align-top hover:bg-muted/40 ${isCPUHog(process.cpuPercent, cores) ? "bg-destructive/10" : process.pid === selected ? "bg-muted/60" : ""}`} + className={`cursor-pointer border-t border-border align-top hover:bg-muted/40 ${hogLabel(process, sampledAt) || isCPUHog(process.cpuPercent, cores) ? "bg-destructive/10" : process.pid === selected ? "bg-muted/60" : ""}`} onClick={() => onSelect(process.pid)} > {renderLink({ to: `/top/${process.pid}`, className: "hover:underline", children: process.pid, title: `Process ${process.pid} and those under it` })} @@ -119,8 +125,10 @@ function ProcessTable({ processes, sort, onSort, selected, onSelect, cores }: Pr {process.origin.owner ?? ""} {process.origin.scope ?? ""} {originText(process.origin)} - {formatPercent(process.cpuPercent)}{isCPUHog(process.cpuPercent, cores) && CPU hog} + {formatPercent(process.cpuPercent)}{(hogLabel(process, sampledAt) || isCPUHog(process.cpuPercent, cores)) && {hogLabel(process, sampledAt) || "CPU hog"}} {formatBytes(process.rssBytes)} + {formatBytes(process.compressedBytes)} + {formatBytes(process.swapBytes)} {formatRate(process.diskReadBps)} {formatRate(process.diskWriteBps)} {formatRate(process.netRxBps)} @@ -159,7 +167,7 @@ function ProcessView({ target }: { target: string }) { const latest = query.data; const total = useMemo(() => latest && sumProcesses(latest.processes), [latest]); const series = useMemo(() => Object.fromEntries(METRIC_VIEWS.map(view => [view.metric, metricSeries(history, view.metric)])) as Record, [history]); - const shown = useMemo(() => latest ? sortProcesses(filterProcesses(latest.processes, q), sort) : [], [latest, q, sort]); + const shown = useMemo(() => latest ? sortProcesses(filterProcesses(latest.processes, q), { by: sort, sampledAt: latest.sampledAt }) : [], [latest, q, sort]); const heading = "pid" in parsed ? `Process ${parsed.pid} and those under it` : parsed.name; return (
    @@ -188,11 +196,11 @@ function ProcessView({ target }: { target: string }) {
    {METRIC_VIEWS.map(view => )}
    -

    CPU hogs use more than 25% of all cores. Terminate sends SIGTERM to one process; renice changes its scheduling priority.

    +

    Hogs exceed 25% of all cores, physical RAM, or swap capacity and stay pinned for 120 seconds after their last spike. On macOS, Compressed includes swapped-out pages; per-process disk swap is unavailable (–). Terminate sends SIGTERM to one process; renice changes its scheduling priority.

    {selected !== undefined && } {shown.length === 0 ?

    No process matches these filters.

    - : } + : } )}
    diff --git a/webapp/src/top/RecordedGroups.test.tsx b/webapp/src/top/RecordedGroups.test.tsx index 805d942..8580f0c 100644 --- a/webapp/src/top/RecordedGroups.test.tsx +++ b/webapp/src/top/RecordedGroups.test.tsx @@ -1,85 +1,57 @@ -import { act, fireEvent, render, screen } from "@testing-library/react"; -import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { afterEach, describe, expect, it, vi } from "vitest"; import { RecordedGroups } from "./RecordedGroups"; import { DEFAULT_VIEW } from "./groups"; import { sampleFrame } from "./testFrames"; import type { RunTraces } from "../traces/api"; -class Source extends EventTarget { - static instances: Source[] = []; - close = vi.fn(); - constructor(readonly url: string) { super(); Source.instances.push(this); } -} - const run: RunTraces = { - runId: "run-one", mount: "/api/traces/run-one", dir: "/work/run-one", status: "running", - captures: [{ kind: "process_groups", ref: { kind: "process_groups", stream: "groups-one" } }], + runId: "run-one", mount: "/api/traces/run-one", dir: "/work/run-one", status: "succeeded", + captures: [{ kind: "process", ref: { kind: "process", stream: "process-one" } }], }; +const page = (ticks: number[]) => new Response(JSON.stringify({ highSeq: ticks.length * 4, frames: ticks.map(tick => sampleFrame(tick)) })); +afterEach(() => vi.unstubAllGlobals()); -function frame(source: Source, tick: number, after = (tick - 1) * 4) { - act(() => { - sampleFrame(tick).groups.forEach((row, index) => source.dispatchEvent(new MessageEvent("message", { - data: JSON.stringify({ ...row, seq: after + index + 1 }), lastEventId: String(after + index + 1), - }))); - }); -} - -beforeEach(() => { vi.stubGlobal("EventSource", Source); vi.stubGlobal("fetch", vi.fn()); }); -afterEach(() => { Source.instances = []; vi.unstubAllGlobals(); }); - -describe("recorded groups follow", () => { - it("streams frames, publishes the final tick on end, and closes on unmount", () => { - const view = render(); - const source = Source.instances[0]!; - expect(source.url).toBe("/api/traces/run-one/traces/process_groups/records?stream=groups-one&follow=1"); - frame(source, 1); - frame(source, 2); - expect(screen.getByText(/tick 1 of 1/)).toBeInTheDocument(); - act(() => source.dispatchEvent(new Event("end"))); - expect(screen.getByText(/tick 2 of 2/)).toBeInTheDocument(); - expect(source.close).toHaveBeenCalled(); - expect(fetch).not.toHaveBeenCalled(); +describe("derived recorded process groups", () => { + it("shows complete ticks and moves between an earlier tick and the latest", async () => { + const fetchMock = vi.fn(() => Promise.resolve(page([1, 2]))); + vi.stubGlobal("fetch", fetchMock); + render(); + expect(await screen.findByText(/tick 2 of 2/)).toBeInTheDocument(); + expect(fetchMock).toHaveBeenCalledWith("/api/traces/run-one/process/groups?stream=process-one&afterSeq=0", expect.objectContaining({ signal: expect.any(AbortSignal) })); fireEvent.change(screen.getByRole("slider", { name: "Tick" }), { target: { value: "0" } }); expect(screen.getByText(/tick 1 of 2/)).toBeInTheDocument(); fireEvent.click(screen.getByRole("button", { name: "Latest" })); expect(screen.getByText(/tick 2 of 2/)).toBeInTheDocument(); - view.unmount(); - expect(source.close).toHaveBeenCalled(); }); - it("surfaces errors without polling and retries after the last received sequence", () => { + it("surfaces a failed read and retries without advancing the sequence", async () => { + const fetchMock = vi.fn().mockResolvedValueOnce(new Response("storage unavailable", { status: 503 })).mockImplementation(() => Promise.resolve(page([1]))); + vi.stubGlobal("fetch", fetchMock); render(); - const source = Source.instances[0]!; - frame(source, 1); - act(() => source.dispatchEvent(new Event("error"))); - expect(screen.getByRole("alert")).toHaveTextContent("process_groups"); + expect(await screen.findByRole("alert")).toHaveTextContent("storage unavailable"); expect(screen.getByRole("searchbox", { name: "Filter" })).toBeInTheDocument(); - expect(fetch).not.toHaveBeenCalled(); fireEvent.click(screen.getByRole("button", { name: "Retry" })); - expect(source.close).toHaveBeenCalledOnce(); - const resumed = Source.instances[1]!; - expect(resumed.url).toContain("afterSeq=4"); - frame(resumed, 2); - act(() => resumed.dispatchEvent(new Event("end"))); + expect(await screen.findByText(/tick 1 of 1/)).toBeInTheDocument(); + expect(fetchMock).toHaveBeenLastCalledWith(expect.stringContaining("afterSeq=0"), expect.anything()); expect(screen.queryByRole("alert")).not.toBeInTheDocument(); - expect(screen.getByRole("slider", { name: "Tick" })).toHaveAttribute("max", "1"); }); - it("closes and resets rows when the selected run changes", () => { + it("resets the frame history when the selected run changes and aborts on unmount", async () => { + const fetchMock = vi.fn(() => Promise.resolve(page([1]))); + vi.stubGlobal("fetch", fetchMock); const view = render(); - const source = Source.instances[0]!; - frame(source, 1); + await screen.findByRole("slider"); + const previous = fetchMock.mock.calls[0] as unknown as [string, RequestInit]; view.rerender(); - expect(source.close).toHaveBeenCalledOnce(); - expect(screen.queryByRole("slider")).not.toBeInTheDocument(); - expect(Source.instances[1]!.url).toContain("/run-two/"); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(expect.stringContaining("/run-two/"), expect.anything())); + expect(previous[1].signal?.aborted).toBe(true); + view.unmount(); }); - it("reports invalid frame data through the existing error state", () => { + it("reports malformed group data without advancing the recording", async () => { + vi.stubGlobal("fetch", vi.fn(() => Promise.resolve(new Response(JSON.stringify({ highSeq: 1, frames: [{ tick: "bad" }] }))))); render(); - const source = Source.instances[0]!; - act(() => source.dispatchEvent(new MessageEvent("message", { data: '{"seq":1,"tick":"invalid"}', lastEventId: "1" }))); - expect(screen.getByRole("alert")).toHaveTextContent("no numeric tick"); - expect(source.close).toHaveBeenCalledOnce(); + expect(await screen.findByRole("alert")).toHaveTextContent("Invalid process group frames"); }); }); diff --git a/webapp/src/top/RecordedGroups.tsx b/webapp/src/top/RecordedGroups.tsx index 377f1f2..07c968f 100644 --- a/webapp/src/top/RecordedGroups.tsx +++ b/webapp/src/top/RecordedGroups.tsx @@ -1,7 +1,7 @@ -import { useEffect, useMemo, useRef, useState } from "react"; +import { useEffect, useRef, useState } from "react"; import { Button } from "@flanksource/clicky-ui/components"; -import { followTraceRecords, type CaptureResult, type RunTraces, type TraceRecord } from "../traces/api"; -import { framesFromRecords, PROCESS_GROUPS_KIND, type Frame } from "./api"; +import { failure, type CaptureResult, type RunTraces } from "../traces/api"; +import { PROCESS_GROUPS_KIND, type Frame } from "./api"; import { CpuChart } from "./charts"; import { GroupsFilterBar, GroupsTable } from "./GroupsTable"; import { viewGroups, type GroupsView } from "./groups"; @@ -13,33 +13,39 @@ export function processGroupsCapture(run: RunTraces): CaptureResult | undefined interface Loaded { seq: number; - rows: TraceRecord[]; frames: Frame[]; } /** Replay and follow the capture, retaining received rows across retries. */ function useRecordedFrames(run: RunTraces, capture: CaptureResult) { const { ref } = capture; - const loaded = useRef({ seq: ref.afterSeq ?? 0, rows: [], frames: [] }); + const loaded = useRef({ seq: 0, frames: [] }); const [state, setState] = useState<{ data: Frame[]; pending: boolean; ended: boolean; error?: Error }>({ data: [], pending: true, ended: false }); const [attempt, setAttempt] = useState(0); - const { kind, stream, afterSeq, toSeq } = ref; + const { stream } = ref; useEffect(() => { setState(previous => ({ ...previous, pending: true, error: undefined })); - return followTraceRecords({ - mount: run.mount, - ref: { kind, stream, afterSeq: Math.max(afterSeq ?? 0, loaded.current.seq), ...(toSeq ? { toSeq } : {}) }, - onOpen: () => setState(previous => ({ ...previous, pending: false, error: undefined })), - onRow: row => { - const rows = [...loaded.current.rows, row]; - const frames = framesFromRecords(rows); - loaded.current = { seq: row.seq as number, rows, frames }; - setState({ data: frames, pending: false, ended: false }); - }, - onError: error => setState(previous => ({ ...previous, pending: false, error })), - onEnd: () => setState(previous => ({ ...previous, pending: false, ended: true, error: undefined })), - }); - }, [run.mount, kind, stream, afterSeq, toSeq, attempt]); + const controller = new AbortController(); + let timer: ReturnType | undefined; + const load = async () => { + try { + const params = new URLSearchParams({ stream, afterSeq: String(loaded.current.seq) }); + const response = await fetch(`${run.mount}/process/groups?${params}`, { signal: controller.signal }); + if (!response.ok) throw await failure(response, "Read recorded process groups"); + const page = await response.json() as { highSeq: number; frames: Frame[] }; + if (!Number.isSafeInteger(page.highSeq) || page.highSeq < loaded.current.seq || !Array.isArray(page.frames) || page.frames.some(frame => !Number.isSafeInteger(frame.tick) || frame.tick <= 0 || !Array.isArray(frame.groups))) throw new Error("Invalid process group frames or sequence"); + if (controller.signal.aborted) return; + const frames = [...loaded.current.frames, ...page.frames]; + loaded.current = { seq: page.highSeq, frames }; + setState({ data: frames, pending: false, ended: run.status !== "running" }); + if (run.status === "running") timer = setTimeout(() => void load(), 1000); + } catch (error) { + if (!controller.signal.aborted) setState(previous => ({ ...previous, pending: false, error: error instanceof Error ? error : new Error(String(error)) })); + } + }; + void load(); + return () => { controller.abort(); if (timer) clearTimeout(timer); }; + }, [run.mount, run.status, stream, attempt]); return { ...state, refetch: () => setAttempt(previous => previous + 1) }; } @@ -61,11 +67,7 @@ export function RecordedGroups({ run, view, onViewChange }: RecordedGroupsProps) function RecordedFrames({ run, capture, view, onViewChange }: RecordedGroupsProps & { capture: CaptureResult }) { const query = useRecordedFrames(run, capture); const [picked, setPicked] = useState(null); - // While the run records, rows of the newest tick are still arriving: its frame is whole once a later tick has begun. - const frames = useMemo(() => { - const read = query.data; - return run.status === "running" && !query.ended && read.length > 1 ? read.slice(0, -1) : read; - }, [query.data, query.ended, run.status]); + const frames = query.data; const index = picked === null ? frames.length - 1 : Math.min(picked, frames.length - 1); const frame = frames[index]; return ( diff --git a/webapp/src/top/TopPage.test.tsx b/webapp/src/top/TopPage.test.tsx index e17d3d9..1736f88 100644 --- a/webapp/src/top/TopPage.test.tsx +++ b/webapp/src/top/TopPage.test.tsx @@ -112,7 +112,7 @@ const recording: RunTraces = { mount, dir: "/cache/telltale/traces/run-2026-10-25T10-00-00Z", status: "succeeded", - captures: [{ kind: "process_groups", ref: { kind: "process_groups", stream: "groups-1", toSeq: 8 } }], + captures: [{ kind: "process", ref: { kind: "process", stream: "groups-1", toSeq: 8 } }], }; function recordedFrames(): Frame[] { @@ -136,6 +136,7 @@ function serveRecording(runs: RunTraces[]) { close() { this.closed = true; } })(); })); const fetchMock = vi.fn((url: string) => { + if (url.includes("/process/groups?")) return Promise.resolve(json({ highSeq: rows.length, frames: recordedFrames() })); if (url.startsWith("/api/top")) return Promise.resolve(json(sampleFrame())); if (url.startsWith("/api/traces?")) return Promise.resolve(json({ runs })); return Promise.resolve(new Response("", { status: 404 })); @@ -151,8 +152,8 @@ describe("recorded process groups", () => { renderPage(); expect(await screen.findByRole("option", { name: `${recording.runId} (succeeded)` })).toBeInTheDocument(); expect(await screen.findByRole("row", { name: /^claude/ })).toBeInTheDocument(); - expect(fetchMock).toHaveBeenCalledWith("/api/traces?kind=process_groups", expect.anything()); - expect(EventSource).toHaveBeenCalledWith(`${mount}/traces/process_groups/records?stream=groups-1&toSeq=8&follow=1`); + expect(fetchMock).toHaveBeenCalledWith("/api/traces?kind=process", expect.anything()); + expect(fetchMock).toHaveBeenCalledWith(`${mount}/process/groups?stream=groups-1&afterSeq=0`, expect.anything()); expect(fetchMock).not.toHaveBeenCalledWith(expect.stringMatching(/\/(seq|export)\?/), expect.anything()); expect(screen.getByRole("slider", { name: "Tick" })).toHaveValue("1"); expect(screen.getByText(/tick 2 of 2/)).toBeInTheDocument(); diff --git a/webapp/src/top/TopPage.tsx b/webapp/src/top/TopPage.tsx index 05fbbe3..a5bca25 100644 --- a/webapp/src/top/TopPage.tsx +++ b/webapp/src/top/TopPage.tsx @@ -63,7 +63,7 @@ function LiveGroups({ state, setState, query }: TabProps & { query: ReturnType

    tick {query.data.tick} · {new Date(query.data.sampledAt).toLocaleTimeString()}

    -

    CPU hogs use more than 25% of all cores. Open a group to terminate or renice individual processes.

    +

    Hogs exceed 25% of all cores, physical RAM, or swap capacity and stay pinned for 120 seconds after their last spike. On macOS, Compressed includes swapped-out pages; per-process disk swap is unavailable (–). Open a group to terminate or renice individual processes.

    )} diff --git a/webapp/src/top/api.ts b/webapp/src/top/api.ts index 2c77b3f..ccefcf1 100644 --- a/webapp/src/top/api.ts +++ b/webapp/src/top/api.ts @@ -8,7 +8,7 @@ import { failure, type TraceRecord } from "../traces/api"; export const TOP_ENDPOINT = "/api/top"; /** The trace kind a host run records its process groups as. */ -export const PROCESS_GROUPS_KIND = "process_groups"; +export const PROCESS_GROUPS_KIND = "process"; export const GROUP_KINDS = ["agent", "browser", "test", "build", "tool", "service", "app", "other"] as const; @@ -19,6 +19,13 @@ export interface Usage { processes: number; cpuPercent?: number; rssBytes: number; + /** Disk swap; unavailable per process on macOS. */ + swapBytes?: number; + /** macOS CMPRS: compressed and swapped-out pages, before compression. */ + compressedBytes?: number; + memoryError?: string; + /** Resource name to expiry, 120 seconds after its last excessive sample. */ + hogs?: Record; diskReadBps?: number; diskWriteBps?: number; netRxBps?: number; @@ -79,6 +86,29 @@ export interface GroupSample { origin: Origin; self: Usage; total: Usage; + /** What a gavel group's process publishes (gavel sdk status.Status); only its slots are read here. */ + gavel?: GavelStatus; + gavelError?: string; +} + +/** A slot a gavel process holds, or a pool it waits for (gavel sdk status.Lease). */ +export interface GavelLease { + /** "global" or "project/". */ + pool: string; + /** The git common directory of a project pool. */ + project?: string; + limit: number; + /** The slot held, -1 while waiting. */ + index: number; + state: "held" | "waiting"; + since: string; + command: string; +} + +export interface GavelStatus { + pid: number; + command: string; + slots: GavelLease[] | null; } /** What the whole host uses at one live tick (groups.HostUsage); the CPU shares are missing on the first tick. */ diff --git a/webapp/src/top/grouping.test.tsx b/webapp/src/top/grouping.test.tsx index a60f173..6dc277a 100644 --- a/webapp/src/top/grouping.test.tsx +++ b/webapp/src/top/grouping.test.tsx @@ -1,6 +1,6 @@ import { describe, expect, it } from "vitest"; import fixture from "../../../testdata/top-grouping.json"; -import type { Frame } from "./api"; +import type { Frame, GavelLease } from "./api"; import { projectGroups, type GroupBy } from "./grouping"; describe("grouping projection", () => { @@ -71,4 +71,24 @@ describe("grouping projection", () => { expect(projected[0]!.total.netRxBps).toBe(1024); expect(projected[2]!.total.netRxBps).toBeUndefined(); }); + + it("buckets gavel groups by the slot pool they hold, their tests with them, and queued ones by the pool they wait for", () => { + const lease = (pool: string, state: GavelLease["state"]): GavelLease => ({ + pool, project: pool === "global" ? undefined : "/src/acme/.git", limit: 2, index: state === "held" ? 0 : -1, state, since: "", command: "go test", + }); + const base = { sampledAt: "", tick: 1, kind: "test", command: "", context: {}, origin: {}, self: { processes: 1, rssBytes: 10 }, total: { processes: 1, rssBytes: 10 } } as const; + const groups: Frame["groups"] = [ + { ...base, key: "agent", name: "claude", kind: "agent", pid: 1 }, + { ...base, key: "gavel-a", parentKey: "agent", name: "gavel", pid: 2, gavel: { pid: 2, command: "gavel test", slots: [lease("global", "held"), lease("project/abc", "held")] } }, + { ...base, key: "go-test", parentKey: "gavel-a", name: "go-test", pid: 3 }, + { ...base, key: "gavel-b", parentKey: "agent", name: "gavel", pid: 4, gavel: { pid: 4, command: "gavel lint", slots: [lease("project/abc", "waiting")] } }, + ]; + const projected = projectGroups(groups, "slots"); + expect(Object.fromEntries(projected.map(group => [group.key, group.parentKey ?? ""]))).toEqual({ + "bucket:slots:": "", agent: "bucket:slots:", + "bucket:slots:project/abc": "", "gavel-a": "bucket:slots:project/abc", "go-test": "gavel-a", + "bucket:slots:project/abc:waiting": "", "gavel-b": "bucket:slots:project/abc:waiting", + }); + expect(projected.filter(group => group.kind === "bucket").map(group => group.name)).toEqual(["Unattributed", "acme", "acme (waiting)"]); + }); }); diff --git a/webapp/src/top/grouping.ts b/webapp/src/top/grouping.ts index 70b7486..e0c5567 100644 --- a/webapp/src/top/grouping.ts +++ b/webapp/src/top/grouping.ts @@ -1,18 +1,22 @@ -import type { GroupContext, GroupSample, Usage } from "./api"; +import type { GavelLease, GavelStatus, GroupContext, GroupSample, Usage } from "./api"; +import { mergeHogs } from "./hogs"; -export const GROUPINGS = ["tree", "repo", "worktree", "claude-session"] as const; +export const GROUPINGS = ["tree", "repo", "worktree", "claude-session", "slots"] as const; export type GroupBy = (typeof GROUPINGS)[number]; export const GROUPING_LABELS: Record = { - tree: "Process tree", repo: "Git repository", worktree: "Worktree", "claude-session": "Claude session", + tree: "Process tree", repo: "Git repository", worktree: "Worktree", "claude-session": "Claude session", slots: "Gavel slot pool", }; -const OPTIONAL_USAGE = ["cpuPercent", "diskReadBps", "diskWriteBps", "netRxBps", "netTxBps", "sockets", "connections"] as const; +const OPTIONAL_USAGE = ["cpuPercent", "compressedBytes", "swapBytes", "diskReadBps", "diskWriteBps", "netRxBps", "netTxBps", "sockets", "connections"] as const; function mergeUsage(a: Usage, b: Usage): Usage { const sum: Usage = { processes: a.processes + b.processes, rssBytes: a.rssBytes + b.rssBytes }; for (const key of OPTIONAL_USAGE) { if (a[key] !== undefined || b[key] !== undefined) sum[key] = (a[key] ?? 0) + (b[key] ?? 0); } + const hogs = mergeHogs(a.hogs, b.hogs); + if (hogs) sum.hogs = hogs; + if (a.memoryError || b.memoryError) sum.memoryError = [a.memoryError, b.memoryError].filter(Boolean).join(" "); return sum; } @@ -62,6 +66,41 @@ function bucketIdentity(by: GroupBy, context: GroupContext): [string, string] { return ["", "Unattributed"]; } +/** A slot pool's name: "global", or a project pool's repository. */ +function poolLabel(pool: string, project?: string): string { + if (pool === "global" || !project) return pool; + const parts = project.split("/").filter(Boolean); + const base = parts.at(-1) === ".git" ? parts.at(-2) ?? "" : parts.at(-1) ?? ""; + return base.replace(/\.git$/, ""); +} + +/** The pool a gavel status's leases name — held before waited for, a project pool before global — if it has any. */ +function slotBucket(status: GavelStatus | undefined): [string, string] | undefined { + const leases = status?.slots ?? []; + if (leases.length === 0) return undefined; + const rank = (lease: GavelLease) => (lease.state !== "waiting" ? 2 : 0) + (lease.pool !== "global" ? 1 : 0); + const best = leases.reduce((a, b) => (rank(b) > rank(a) ? b : a)); + const label = poolLabel(best.pool, best.project); + return best.state === "waiting" ? [`${best.pool}:waiting`, `${label} (waiting)`] : [best.pool, label]; +} + +/** Each group's slot pool bucket; a group with no gavel status of its own takes its parent's. groupingContexts has refused cycles by now. */ +function slotBuckets(groups: GroupSample[]): Map { + const byKey = new Map(groups.map(group => [group.key, group])); + const resolved = new Map(); + const resolve = (key: string): [string, string] => { + const previous = resolved.get(key); + if (previous) return previous; + const group = byKey.get(key); + if (!group) return ["", "Unattributed"]; + const found = slotBucket(group.gavel) ?? resolve(group.parentKey ?? ""); + resolved.set(key, found); + return found; + }; + for (const group of groups) resolve(group.key); + return resolved; +} + export function rollupGroups(groups: GroupSample[]): GroupSample[] { const children = new Map(); const present = new Set(); @@ -95,7 +134,8 @@ export function projectGroups(groups: GroupSample[], by: GroupBy): GroupSample[] if (!GROUPINGS.includes(by)) throw new Error(`group-by "${by}": expected one of ${GROUPINGS.join(", ")}`); if (by === "tree") return groups; const contexts = groupingContexts(groups); - const buckets = new Map(groups.map(group => [group.key, `bucket:${by}:${bucketIdentity(by, contexts.get(group.key)!)[0]}`])); + const identities = by === "slots" ? slotBuckets(groups) : new Map(groups.map(group => [group.key, bucketIdentity(by, contexts.get(group.key)!)])); + const buckets = new Map(groups.map(group => [group.key, `bucket:${by}:${identities.get(group.key)![0]}`])); const skipped = new Set(groups.filter(group => group.pid === 0 && (group.kind === "other" || group.kind === "app")).map(group => group.key)); const created = new Set(); const projected: GroupSample[] = []; @@ -104,7 +144,7 @@ export function projectGroups(groups: GroupSample[], by: GroupBy): GroupSample[] const key = buckets.get(group.key)!; const context = contexts.get(group.key)!; if (!created.has(key)) { - const [target, name] = bucketIdentity(by, context); + const [target, name] = identities.get(group.key)!; projected.push({ sampledAt: group.sampledAt, tick: group.tick, key, name, target, command: target, kind: "bucket", pid: 0, context: {}, origin: {}, self: { processes: 0, rssBytes: 0 }, total: { processes: 0, rssBytes: 0 } }); created.add(key); } diff --git a/webapp/src/top/groups.ts b/webapp/src/top/groups.ts index 88c448c..78d30ab 100644 --- a/webapp/src/top/groups.ts +++ b/webapp/src/top/groups.ts @@ -1,10 +1,11 @@ import type { Frame, GroupContext, GroupKind, GroupSample, Origin, Scope, Usage } from "./api"; import { projectGroups, rollupGroups, type GroupBy } from "./grouping"; +import { isPinned } from "./hogs"; // The pure side of the process groups view: which groups a view shows and in // what order (mirroring groups.Frame.Sorted), and how their values read. -export const SORT_KEYS = ["name", "procs", "cpu", "rss", "diskRead", "diskWrite", "netRx", "netTx", "sockets"] as const; +export const SORT_KEYS = ["name", "procs", "cpu", "rss", "compressed", "swap", "diskRead", "diskWrite", "netRx", "netTx", "sockets"] as const; export type SortKey = (typeof SORT_KEYS)[number]; @@ -69,6 +70,8 @@ function sortValue(usage: Usage, key: Exclude): number { case "procs": return usage.processes; case "cpu": return usage.cpuPercent ?? 0; case "rss": return usage.rssBytes; + case "compressed": return usage.compressedBytes ?? 0; + case "swap": return usage.swapBytes ?? 0; case "diskRead": return usage.diskReadBps ?? 0; case "diskWrite": return usage.diskWriteBps ?? 0; case "netRx": return usage.netRxBps ?? 0; @@ -89,7 +92,7 @@ function visibleGroups(groups: GroupSample[], view: GroupsView): GroupSample[] { const keep = new Set(); for (const group of groups) { if (group.kind === "bucket") continue; - if (group.kind === "other" && !view.showOther) continue; + if (group.kind === "other" && !view.showOther && !isPinned(group.total, group.sampledAt)) continue; if (view.kind && group.kind !== view.kind) continue; if (view.scope && group.origin.scope !== view.scope) continue; let bucket = group; @@ -118,14 +121,15 @@ export function groupRows(groups: GroupSample[], view: GroupsView, expanded: Rea children.set(parent, [...(children.get(parent) ?? []), group]); } const sign = view.dir === "desc" ? -1 : 1; - const compare = (a: GroupSample, b: GroupSample): number => sign * (view.sort === "name" - ? a.name.localeCompare(b.name) - : sortValue(a.total, view.sort) - sortValue(b.total, view.sort)); + const compare = (a: GroupSample, b: GroupSample): number => + Number(isPinned(b.total, b.sampledAt)) - Number(isPinned(a.total, a.sampledAt)) || sign * (view.sort === "name" + ? a.name.localeCompare(b.name) + : sortValue(a.total, view.sort) - sortValue(b.total, view.sort)); const rows: GroupRow[] = []; const walk = (parent: string, depth: number) => { for (const group of [...(children.get(parent) ?? [])].sort(compare)) { rows.push({ group, depth }); - if (isSyntheticOther(group) && !expanded.has(group.key) && !view.q.trim()) continue; + if (isSyntheticOther(group) && !view.q.trim() && (collapsed.has(group.key) || (!expanded.has(group.key) && !isPinned(group.total, group.sampledAt)))) continue; if (group.kind === "bucket" && collapsed.has(group.key) && !view.q.trim()) continue; walk(group.key, depth + 1); } diff --git a/webapp/src/top/hogs.test.tsx b/webapp/src/top/hogs.test.tsx new file mode 100644 index 0000000..f5a075d --- /dev/null +++ b/webapp/src/top/hogs.test.tsx @@ -0,0 +1,37 @@ +import { describe, expect, it } from "vitest"; +import { groupRows, DEFAULT_VIEW } from "./groups"; +import { group, usage } from "./testFrames"; +import { projectGroups } from "./grouping"; +import { sortProcesses, sumProcesses } from "./processes"; +import type { ProcessSample } from "./api"; + +describe("resource hog pinning", () => { + const sampledAt = "2026-11-06T10:00:00Z"; + const hogs = { memory: "2026-11-06T10:02:00Z" }; + const groups = [ + group({ key: "busy", name: "a", sampledAt, total: usage({ cpuPercent: 100, rssBytes: 1000 }) }), + group({ key: "hog", name: "z", sampledAt, self: usage({ compressedBytes: 100, swapBytes: 200, hogs }), total: usage({ hogs }) }), + ]; + + it("pins recent memory hogs ahead of ascending and descending sorts", () => { + for (const sort of ["cpu", "rss", "swap", "compressed", "name"] as const) { + for (const dir of ["asc", "desc"] as const) { + expect(groupRows(groups, { ...DEFAULT_VIEW, sort, dir })[0]!.group.key).toBe("hog"); + } + } + const expired = groups.map(group => ({ ...group, sampledAt: "2026-11-06T10:02:00Z" })); + expect(groupRows(expired, DEFAULT_VIEW)[0]!.group.key).toBe("busy"); + }); + + it("preserves memory and pins when regrouping or summing processes", () => { + const bucket = projectGroups(groups, "repo")[0]!; + expect(bucket.total).toMatchObject({ compressedBytes: 100, swapBytes: 200, hogs }); + const processes: ProcessSample[] = groups.map((group, index) => ({ + ...group.self, key: `${index}@1`, name: group.name, command: group.name, groupKey: group.key, + pid: index + 1, ppid: 0, origin: {}, + })); + expect(sumProcesses(processes)).toMatchObject({ compressedBytes: 100, swapBytes: 200 }); + expect(sortProcesses(processes, { by: "cpu", sampledAt })[0]!.key).toBe("1@1"); + expect(sortProcesses(processes, { by: "cpu", sampledAt: "2026-11-06T10:02:00Z" })[0]!.key).toBe("0@1"); + }); +}); diff --git a/webapp/src/top/hogs.ts b/webapp/src/top/hogs.ts new file mode 100644 index 0000000..bb1bfab --- /dev/null +++ b/webapp/src/top/hogs.ts @@ -0,0 +1,22 @@ +import type { Usage } from "./api"; + +export function isPinned(usage: Usage, sampledAt: string): boolean { + return Object.values(usage.hogs ?? {}).some(until => Date.parse(until) > Date.parse(sampledAt)); +} + +export function hogLabel(usage: Usage, sampledAt: string): string { + const resources = ["CPU", "memory", "swap", "compressed"].filter(resource => { + const until = usage.hogs?.[resource]; + return until !== undefined && Date.parse(until) > Date.parse(sampledAt); + }); + return resources.length ? `${resources.join("/")} hog` : ""; +} + +export function mergeHogs(a: Usage["hogs"], b: Usage["hogs"]): Usage["hogs"] { + if (!a && !b) return undefined; + const merged = { ...a }; + for (const [resource, until] of Object.entries(b ?? {})) { + if (!merged[resource] || Date.parse(until) > Date.parse(merged[resource])) merged[resource] = until; + } + return merged; +} diff --git a/webapp/src/top/processes.ts b/webapp/src/top/processes.ts index 6abbb1e..d353160 100644 --- a/webapp/src/top/processes.ts +++ b/webapp/src/top/processes.ts @@ -1,5 +1,6 @@ import type { ProcessSample, ProcessTarget, TopProcesses, Usage } from "./api"; import { originText } from "./groups"; +import { isPinned } from "./hogs"; // The pure side of the process page: which target a path names, what the // processes use in total, and which of them a view shows. @@ -19,6 +20,8 @@ function sumKnown(values: Array): number | undefined { export function sumProcesses(processes: ProcessSample[]): Usage { const usage: Usage = { processes: processes.length, rssBytes: processes.reduce((total, process) => total + process.rssBytes, 0) }; const optional = { + swapBytes: sumKnown(processes.map(process => process.swapBytes)), + compressedBytes: sumKnown(processes.map(process => process.compressedBytes)), cpuPercent: sumKnown(processes.map(process => process.cpuPercent)), diskReadBps: sumKnown(processes.map(process => process.diskReadBps)), diskWriteBps: sumKnown(processes.map(process => process.diskWriteBps)), @@ -31,7 +34,7 @@ export function sumProcesses(processes: ProcessSample[]): Usage { return usage; } -export const METRICS = ["cpu", "rss", "diskRead", "diskWrite", "netRx", "netTx", "sockets"] as const; +export const METRICS = ["cpu", "rss", "compressed", "swap", "diskRead", "diskWrite", "netRx", "netTx", "sockets"] as const; export type Metric = (typeof METRICS)[number]; @@ -39,6 +42,8 @@ export function metricValue(usage: Usage, metric: Metric): number | undefined { switch (metric) { case "cpu": return usage.cpuPercent; case "rss": return usage.rssBytes; + case "compressed": return usage.compressedBytes; + case "swap": return usage.swapBytes; case "diskRead": return usage.diskReadBps; case "diskWrite": return usage.diskWriteBps; case "netRx": return usage.netRxBps; @@ -55,11 +60,12 @@ export function metricSeries(readings: TopProcesses[], metric: Metric): number[] }); } -export type ProcessSortKey = "cpu" | "rss"; +export type ProcessSortKey = "cpu" | "rss" | "compressed" | "swap"; -export function sortProcesses(processes: ProcessSample[], key: ProcessSortKey): ProcessSample[] { - const value = (process: ProcessSample) => (key === "cpu" ? process.cpuPercent ?? 0 : process.rssBytes); - return [...processes].sort((a, b) => value(b) - value(a) || a.pid - b.pid); +export function sortProcesses(processes: ProcessSample[], { by, sampledAt }: { by: ProcessSortKey; sampledAt: string }): ProcessSample[] { + return [...processes].sort((a, b) => + Number(isPinned(b, sampledAt)) - Number(isPinned(a, sampledAt)) || + (metricValue(b, by) ?? 0) - (metricValue(a, by) ?? 0) || a.pid - b.pid); } /** The processes whose name, command, owner or origin hold the text, case-insensitively. */ diff --git a/webapp/src/traces/TracesPage.test.tsx b/webapp/src/traces/TracesPage.test.tsx index 09e277d..48ac76f 100644 --- a/webapp/src/traces/TracesPage.test.tsx +++ b/webapp/src/traces/TracesPage.test.tsx @@ -4,17 +4,22 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import type { DefinitionSummary } from "../definitions/api"; import { parseNdjson, runFilterQuery, traceExportUrl, type RunTraces, type StartForm, type TracesStatus } from "./api"; import { sampleFrame } from "../top/testFrames"; -import { captureWindows } from "./TracesPanel"; import TracesPage from "./TracesPage"; -beforeEach(() => window.history.replaceState(null, "", "/")); +beforeEach(() => { + window.history.replaceState(null, "", "/"); + vi.stubGlobal("EventSource", class extends EventTarget { + close() {} + }); +}); afterEach(() => vi.unstubAllGlobals()); const runId = "run-2026-10-24T10-00-00Z"; const mount = `/api/traces/${runId}`; const processRefs = { - tree: { kind: "process_tree", stream: "tree-1" }, - samples: { kind: "process_samples", stream: "samples-1" }, + tree: { kind: "process", stream: "tree-1" }, + samples: { kind: "process_metrics", stream: "tree-1-metrics" }, + facets: { kind: "process_facets", stream: "tree-1-facets" }, stacks: { kind: "stacks", stream: "stacks-1" }, }; @@ -68,6 +73,7 @@ function serve(status: TracesStatus, started: Response = json(running, 201), lis if (init?.method === "DELETE") return Promise.resolve(new Response(null, { status: 202 })); if (url.endsWith("/traces/kinds")) return Promise.resolve(json([{ name: "http", title: "HTTP traffic", exportFormats: [{ name: "har", ext: "har", mime: "application/json" }] }])); if (url.includes("/seq?")) return Promise.resolve(json({ seq: 0 })); + if (url.includes("/records?")) return Promise.resolve(json({ rows: [], nextCursor: "" })); return Promise.resolve(new Response("", { status: 404 })); }); vi.stubGlobal("fetch", fetchMock); @@ -83,11 +89,23 @@ function renderPage() { } describe("trace runs", () => { + it("switches replay runs in the viewer and preserves the selected run in the URL", async () => { + const other: RunTraces = { ...finished, runId: "other-run", mount: "/api/traces/other-run" }; + window.history.replaceState(null, "", `/?viewer=1&run=${other.runId}`); + const fetchMock = serve({ runs: [finished, other] }); + renderPage(); + expect(await screen.findByRole("combobox", { name: "Run" })).toHaveValue(other.runId); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${other.mount}/records?sort=seq&limit=100`, expect.anything())); + fireEvent.change(screen.getByRole("combobox", { name: "Run" }), { target: { value: runId } }); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/records?sort=seq&limit=100`, expect.anything())); + expect(new URLSearchParams(window.location.search).get("run")).toBe(runId); + expect(screen.queryByText("New run")).not.toBeInTheDocument(); + }); it.each(["sql_deadlock", "sql_xevent", "jvm_jfr"])("shows %s captures without a local process tree", async kind => { const fetchMock = serve({ runs: [{ ...finished, command: undefined, process: undefined, captures: [{ kind, ref: { kind, stream: "connection-or-agent", toSeq: 2 }, summary: { count: 2 } }] }] }); renderPage(); expect(await screen.findByText("host run")).toBeInTheDocument(); - await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/api/v1/traces/kinds`, expect.anything())); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/records?sort=seq&limit=100`, expect.anything())); expect(screen.queryByRole("alert")).not.toBeInTheDocument(); }); @@ -103,7 +121,7 @@ describe("trace runs", () => { expect(await screen.findByText("curl https://example.com")).toBeInTheDocument(); expect(screen.getByText(/exited with code 0/)).toBeInTheDocument(); expect(screen.getByRole("option", { name: `${runId} (succeeded)` })).toBeInTheDocument(); - expect(screen.getByRole("link", { name: "Open in query" })).toHaveAttribute("href", `/records/${runId}/http/proxy-1?toSeq=2`); + expect(screen.getByRole("option", { name: "http" })).toBeInTheDocument(); }); it("names an attached run by its pid and lists the checkpoints that failed", async () => { @@ -186,13 +204,13 @@ describe("trace runs", () => { }); describe("host runs recording process groups", () => { - const groupsRef = { kind: "process_groups", stream: "groups-1" }; + const groupsRef = { kind: "process", stream: "groups-1" }; const hostRun: RunTraces = { runId: "run-2026-10-25T12-00-00Z", mount: "/api/traces/run-2026-10-25T12-00-00Z", dir: "/cache/telltale/traces/run-2026-10-25T12-00-00Z", status: "running", - captures: [{ kind: "process_groups", ref: groupsRef }], + captures: [{ kind: "process", ref: groupsRef }], }; // serveGroups answers the run list with runs and the run's group rows with one tick of sampleFrame. @@ -211,13 +229,15 @@ describe("host runs recording process groups", () => { close() { this.closed = true; } }); const fetchMock = vi.fn((url: string, init?: RequestInit) => { + if (url.includes("/process/groups?")) return Promise.resolve(json({ highSeq: 4, frames: [sampleFrame()] })); if (url === "/api/traces" || url.startsWith("/api/traces?")) return Promise.resolve(json({ runs })); if (url === "/api/traces/start") return Promise.resolve(json(startForm)); if (url === "/api/traces/definitions") return Promise.resolve(json(definitions)); if (init?.method === "DELETE") return Promise.resolve(new Response(null, { status: 202 })); - if (url.endsWith("/traces/kinds")) return Promise.resolve(json([{ name: "process_groups", title: "Process groups", exportFormats: [] }])); + if (url.endsWith("/traces/kinds")) return Promise.resolve(json([{ name: "process", title: "Processes", exportFormats: [] }])); if (url.includes("/seq?")) return Promise.resolve(json({ seq: 4 })); if (url.includes("/export?")) return Promise.resolve(new Response(rows)); + if (url.includes("/records?")) return Promise.resolve(json({ rows: [], nextCursor: "" })); return Promise.resolve(new Response("", { status: 404 })); }); vi.stubGlobal("fetch", fetchMock); @@ -234,7 +254,7 @@ describe("host runs recording process groups", () => { }); it("shows a stopped host run's groups instead of saying it is unavailable", async () => { - serveGroups([{ ...hostRun, status: "succeeded", captures: [{ kind: "process_groups", ref: { ...groupsRef, toSeq: 4 } }] }]); + serveGroups([{ ...hostRun, status: "succeeded", captures: [{ kind: "process", ref: { ...groupsRef, toSeq: 4 } }] }]); renderPage(); expect(await screen.findByRole("row", { name: /^claude/ })).toBeInTheDocument(); expect(screen.getByText("host run")).toBeInTheDocument(); @@ -261,7 +281,7 @@ describe("starting a run", () => { await waitFor(() => expect(fetchMock).toHaveBeenCalledWith("/api/traces", expect.objectContaining({ method: "POST", body: JSON.stringify({ command: "sleep 60" }), }))); - await waitFor(() => expect(window.location.search).toBe(`?run=${running.runId}`)); + await waitFor(() => expect(Object.fromEntries(new URLSearchParams(window.location.search))).toEqual({ run: running.runId, feedSort: "seq" })); }); it("starts a saved definition with only the run's execution fields", async () => { @@ -276,7 +296,7 @@ describe("starting a run", () => { await waitFor(() => expect(fetchMock).toHaveBeenCalledWith("/api/traces", expect.objectContaining({ method: "POST", body: JSON.stringify({ definition: "checkout", command: "./bin/checkout", duration: "20s" }), }))); - await waitFor(() => expect(window.location.search).toBe(`?run=${running.runId}`)); + await waitFor(() => expect(Object.fromEntries(new URLSearchParams(window.location.search))).toEqual({ run: running.runId, feedSort: "seq" })); }); it("shows a failed definition listing and keeps the inline start", async () => { @@ -296,12 +316,6 @@ describe("starting a run", () => { }); describe("trace windows", () => { - it("names a capture's window in its run, counted from its summary", () => { - expect(captureWindows(finished)).toEqual([ - { kind: "http", stream: "proxy-1", toSeq: 2, run_id: finished.runId, count: 2, summary: { count: 2 } }, - ]); - }); - it("builds a window's export URL under the run's mount", () => { expect(traceExportUrl(mount, { kind: "http", stream: "proxy-1", afterSeq: 3, toSeq: 9 }, "har")) .toBe(`${mount}/api/v1/traces/http/export?stream=proxy-1&afterSeq=3&toSeq=9&format=har`); diff --git a/webapp/src/traces/TracesPage.tsx b/webapp/src/traces/TracesPage.tsx index 5cfc40c..a9f06aa 100644 --- a/webapp/src/traces/TracesPage.tsx +++ b/webapp/src/traces/TracesPage.tsx @@ -112,8 +112,8 @@ function HostRunDetail({ run }: { run: RunTraces }) { return (
    - {processGroupsCapture(run) && setView(previous => ({ ...previous, ...next }))} />} +
    ); } @@ -124,16 +124,16 @@ function RunDetail({ run }: { run: RunTraces }) { const [expandAll, setExpandAll] = useState(true); const trace = useProcessTrace({ mount: run.mount, - ...(run.process ? { refs: run.process } : {}), + ...(run.process && !run.unavailable ? { refs: run.process } : {}), ...(run.live ? { sessions: run.live.sessions } : {}), ...(selectedKey ? { selectedKey } : {}), done: !run.live, }); - if (!run.process) return run.unavailable ?

    {run.unavailable}

    : ; + if (run.unavailable) return

    {run.unavailable}

    ; + if (!run.process) return ; return (
    - +
    ); } @@ -193,13 +194,33 @@ function RunList({ state, setState }: { state: PageState; setState: (next: Parti } /** Starts runs, and shows the runs the server holds, newest first: the selected one's captures and processes, live while it runs. */ +function RunViewer({ selected, onSelect }: { selected?: string; onSelect: (id: string) => void }) { + const result = useQuery({ queryKey: ["viewer-run"], queryFn: () => fetchTraceRuns(), refetchInterval: 1000 }); + if (result.isPending) return

    Loading trace run…

    ; + if (result.isError) return

    {result.error.message}

    ; + const runs = result.data.runs; + const run = runs.find(candidate => candidate.runId === selected) ?? runs[0]; + if (!run) return

    The viewer has no trace run.

    ; + return
    + {runs.length > 1 && } + +
    ; +} + export default function TracesPage() { const [state, setState] = usePageState(); + const viewer = new URLSearchParams(window.location.search).get("viewer") === "1"; + if (viewer) return setState({ run })} />; return (
    - + {!viewer && setState({ run: run.runId, q: "", status: "", kind: "" })} /> - + }
    ); diff --git a/webapp/src/traces/TracesPanel.tsx b/webapp/src/traces/TracesPanel.tsx index 06e12d8..62f5345 100644 --- a/webapp/src/traces/TracesPanel.tsx +++ b/webapp/src/traces/TracesPanel.tsx @@ -1,52 +1,12 @@ -import { useCallback, useEffect, useMemo, useState } from "react"; -import { TraceWindowList, type TraceWindow, type TraceWindowSource } from "@flanksource/clicky-ui/data"; -import { fetchTraceKinds, fetchTraceRecords, traceExportUrl, type RunTraces, type TraceExportFormat } from "./api"; - -function useExportFormats(mount: string) { - const [byKind, setByKind] = useState>({}); - const [error, setError] = useState(undefined); - useEffect(() => { - fetchTraceKinds(mount) - .then(kinds => setByKind(Object.fromEntries(kinds.map(kind => [kind.name, kind.exportFormats])))) - .catch((e: unknown) => setError(e instanceof Error ? e.message : String(e))); - }, [mount]); - return { byKind, error }; -} - -/** The windows of the captures a run armed, as TraceWindowList reads them. */ -export function captureWindows(run: RunTraces): TraceWindow[] { - return (run.captures ?? []).map(capture => ({ - ...capture.ref, - run_id: run.runId, - count: Number(capture.summary?.count ?? 0), - summary: capture.summary ?? {}, - })); -} +import { useMemo } from "react"; +import { TraceFeed } from "@flanksource/clicky-ui/data"; +import { traceFeedSource } from "./feed"; +import { type RunTraces } from "./api"; /** The captures one run armed, read from its store. */ export function TracesPanel({ run }: { run: RunTraces }) { - const formats = useExportFormats(run.mount); - const windows = useMemo(() => captureWindows(run), [run]); - const resolve = useCallback((): TraceWindowSource => ({ mount: run.mount }), [run.mount]); - const props = useMemo(() => ({ - formats: (kind: string) => formats.byKind[kind] ?? [], - fetchRecords: (window: TraceWindow, signal: AbortSignal) => fetchTraceRecords(run.mount, window, signal), - exportUrl: (window: TraceWindow, format: string) => traceExportUrl(run.mount, window, format), - openUrl: (window: TraceWindow) => { - const params = new URLSearchParams(); - if (window.afterSeq) params.set("afterSeq", String(window.afterSeq)); - if (window.toSeq) params.set("toSeq", String(window.toSeq)); - return `/records/${encodeURIComponent(run.runId)}/${encodeURIComponent(window.kind)}/${encodeURIComponent(window.stream)}${params.size ? `?${params}` : ""}`; - }, - }), [formats.byKind, run.mount]); - - if (windows.length === 0) return

    This run armed no captures.

    ; - return ( - - ); + const source = useMemo(() => traceFeedSource(run.mount), [run.mount]); + const kinds = [...new Set([...(run.captures ?? []).map(capture => capture.kind), ...(run.process ? ["process", "stacks"] : [])])]; + const live = run.status === "running" && kinds.length > 0; + return capture.kind === "process" ? null : undefined} {...(live && source.follow ? { follow: source.follow } : {})} />; } diff --git a/webapp/src/traces/api.ts b/webapp/src/traces/api.ts index 8cdfd53..e885be2 100644 --- a/webapp/src/traces/api.ts +++ b/webapp/src/traces/api.ts @@ -18,6 +18,7 @@ export interface TraceRef { export interface ProcessTraceRefs { tree: TraceRef; samples: TraceRef; + facets: TraceRef; stacks: TraceRef; goprof?: TraceRef; } diff --git a/webapp/src/traces/feed.ts b/webapp/src/traces/feed.ts new file mode 100644 index 0000000..cd386bd --- /dev/null +++ b/webapp/src/traces/feed.ts @@ -0,0 +1,42 @@ +import type { TraceFeedPage, TraceFeedProps, TraceFeedRecord, TraceFeedRequest } from "@flanksource/clicky-ui/data"; +import { failure } from "./api"; + +function feedUrl(mount: string, values: Record): string { + const params = new URLSearchParams(); + for (const [key, value] of Object.entries(values)) if (value) params.set(key, value); + return `${mount}/records?${params}`; +} + +export function traceFeedSource(mount: string): Pick { + const tokens = new Map(); + return { + loadPage: async (request: TraceFeedRequest, signal: AbortSignal): Promise => { + const response = await fetch(feedUrl(mount, { ...request, limit: "100" }), { signal }); + if (!response.ok) throw await failure(response, "Read trace feed"); + return response.json() as Promise; + }, + follow: ({ kind, onRecord, onError, onEnd }) => { + const source = new EventSource(feedUrl(mount, { kind, follow: "1", resume: tokens.get(kind) ?? "" })); + source.onmessage = event => { + try { + const record = JSON.parse(event.data) as TraceFeedRecord; + if (!Number.isSafeInteger(record.seq) || record.seq < 1 || !record.kind || !record.stream || !record.record) throw new Error("Invalid trace feed record"); + onRecord(record); + tokens.set(kind, event.lastEventId); + } catch (error) { + source.close(); + onError(error instanceof Error ? error : new Error(String(error))); + } + }; + source.addEventListener("end", () => { source.close(); onEnd(); }); + source.addEventListener("error", event => { + if (event instanceof MessageEvent) { + source.close(); + try { onError(new Error((JSON.parse(event.data) as { error: string }).error)); } + catch (error) { onError(error instanceof Error ? error : new Error(String(error))); } + } else onError(new Error("Trace feed disconnected; reconnecting")); + }); + return () => source.close(); + }, + }; +} diff --git a/webapp/src/traces/processData.test.tsx b/webapp/src/traces/processData.test.tsx new file mode 100644 index 0000000..ac6b0ba --- /dev/null +++ b/webapp/src/traces/processData.test.tsx @@ -0,0 +1,20 @@ +import { describe, expect, it } from "vitest"; +import { ProcessFacets, projectProcesses, type ProcessIdentity, type ProcessMetric } from "./processData"; + +describe("process table projection", () => { + it("joins metrics to startup identity and applies file removals independently of sockets", () => { + const identity: ProcessIdentity = { key: "worker", pid: 123, ppid: 1, name: "worker", command: "worker", startedAt: "2026-11-08T10:00:00Z", firstObservedAt: "2026-11-08T10:00:00Z" }; + const metric: ProcessMetric = { entity: identity.key, observedAt: "2026-11-08T10:00:02Z", tick: 2, cpuPercent: null, rssBytes: 1024, memoryPercent: 0, openFiles: 0, receivingSockets: 1, connectionsIn: 0, connectionsOut: 0, connectionsUnknown: 0 }; + const facets = new ProcessFacets(); + const file = { process: identity.key, observedAt: identity.firstObservedAt, tick: 1, facet: "files", entity: "config", operation: "added", resource: { fd: "3", type: "REG", name: "config.yaml" } } as const; + facets.apply([file, { ...file, facet: "sockets", entity: "listener", resource: { fd: "4", type: "IPv4", name: "localhost:8080" } }]); + facets.apply([{ ...file, operation: "removed", tick: 2 }]); + const result = projectProcesses([identity], [metric], facets); + expect(result.nodes[0]).toMatchObject({ key: identity.key, status: "running", rssBytes: 1024, cpuPercent: null }); + expect(result.samples[0]).toMatchObject({ key: identity.key, pid: identity.pid, openFiles: 0, openFileList: [], ports: 1, portList: [{ fd: "4" }], connections: 0 }); + }); + + it("rejects metrics without a recorded identity", () => { + expect(() => projectProcesses([], [{ entity: "unknown", observedAt: "2026-11-08T10:00:00Z", tick: 1, rssBytes: 0, memoryPercent: 0, cpuPercent: null }], new ProcessFacets())).toThrow(/unknown process/); + }); +}); diff --git a/webapp/src/traces/processData.ts b/webapp/src/traces/processData.ts new file mode 100644 index 0000000..c52ffce --- /dev/null +++ b/webapp/src/traces/processData.ts @@ -0,0 +1,77 @@ +import type { ProcessSample, ProcessTraceNode } from "./api"; + +export type ProcessIdentity = Omit & { firstObservedAt: string }; +export interface ProcessMetric { + entity: string; + observedAt: string; + tick: number; + rssBytes: number; + memoryPercent: number; + cpuPercent: number | null; + diskReadBytes?: number | null; + diskWriteBytes?: number | null; + openFiles?: number | null; + receivingSockets?: number | null; + connectionsIn?: number | null; + connectionsOut?: number | null; + connectionsUnknown?: number | null; +} +type Descriptor = NonNullable[number]; +export interface FacetChange { + process: string; + observedAt: string; + tick: number; + facet: string; + entity: string; + operation: "added" | "removed"; + resource: Descriptor; +} + +export class ProcessFacets { + private held = new Map(); + apply(changes: FacetChange[]) { + for (const event of changes) { + const key = `${event.process}/${event.facet}/${event.entity}`; + if (event.operation === "added") this.held.set(key, event); + else if (event.operation === "removed") this.held.delete(key); + else throw new Error(`Unknown facet operation ${String(event.operation)}`); + } + } + list(process: string, facets: string[]): Descriptor[] { + return [...this.held.values()].filter(event => event.process === process && facets.includes(event.facet)).map(event => event.resource); + } +} + +export function projectProcesses(identities: ProcessIdentity[], metrics: ProcessMetric[], facets: ProcessFacets): { nodes: ProcessTraceNode[]; samples: ProcessSample[] } { + const nodes = identities.map(identity => ({ ...identity, status: identity.exitedAt ? "exited" : "running", isRoot: !identity.parentKey, lastSeenAt: identity.firstObservedAt, rssBytes: 0, peakRssBytes: 0 })); + const index = new Map(nodes.map(node => [node.key, node])); + const latest = new Map(); + const samples = metrics.map(metric => { + const node = index.get(metric.entity); + if (!node) throw new Error(`Metrics reference unknown process ${metric.entity}`); + if (metric.observedAt >= node.lastSeenAt) { + node.cpuPercent = metric.cpuPercent; + node.rssBytes = metric.rssBytes; + node.lastSeenAt = metric.observedAt; + } + node.peakRssBytes = Math.max(node.peakRssBytes, metric.rssBytes); + if (metric.cpuPercent !== null) node.peakCpuPercent = Math.max(node.peakCpuPercent ?? 0, metric.cpuPercent); + const connections = [metric.connectionsIn, metric.connectionsOut, metric.connectionsUnknown]; + const sample: ProcessSample = { + key: metric.entity, pid: node.pid, sampledAt: metric.observedAt, tick: metric.tick, rssBytes: metric.rssBytes, memoryPercent: metric.memoryPercent, cpuPercent: metric.cpuPercent, + ...(metric.diskReadBytes != null ? { diskReadBytes: metric.diskReadBytes } : {}), + ...(metric.diskWriteBytes != null ? { diskWriteBytes: metric.diskWriteBytes } : {}), + ...(metric.openFiles != null ? { openFiles: metric.openFiles } : {}), + ...(metric.receivingSockets != null ? { ports: metric.receivingSockets, sockets: metric.receivingSockets } : {}), + ...(connections.every(count => count != null) ? { connections: connections.reduce((sum, count) => sum + count!, 0) } : {}), + }; + if (!latest.has(sample.key) || latest.get(sample.key)!.tick < sample.tick) latest.set(sample.key, sample); + return sample; + }); + for (const [key, sample] of latest) { + if (sample.openFiles !== undefined) sample.openFileList = facets.list(key, ["files"]); + if (sample.ports !== undefined) sample.portList = sample.socketList = facets.list(key, ["sockets"]); + if (sample.connections !== undefined) sample.connectionList = facets.list(key, ["connection_in", "connection_out", "connection_unknown"]); + } + return { nodes, samples }; +} diff --git a/webapp/src/traces/useProcessTrace.ts b/webapp/src/traces/useProcessTrace.ts index 54bf43a..b862d73 100644 --- a/webapp/src/traces/useProcessTrace.ts +++ b/webapp/src/traces/useProcessTrace.ts @@ -11,6 +11,7 @@ import { type ProcessTraceRefs, type TraceRef, } from "./api"; +import { ProcessFacets, projectProcesses, type FacetChange, type ProcessIdentity, type ProcessMetric } from "./processData"; const POLL_INTERVAL_MS = 1000; @@ -73,10 +74,36 @@ async function readStream(mount: string, ref: TraceRef): Promise { } // readRecentSamples is the last SAMPLE_WINDOW samples of the stream. -async function readRecentSamples(mount: string, ref: TraceRef): Promise { +async function readRecentSamples(mount: string, ref: TraceRef): Promise { const latest = await fetchLatestSeq(mount, ref); if (latest === 0) return []; - return readStream(mount, { ...ref, afterSeq: Math.max(0, latest - SAMPLE_WINDOW) }); + return readStream(mount, { ...ref, afterSeq: Math.max(0, latest - SAMPLE_WINDOW), toSeq: latest }); +} + +function processReader(mount: string, refs: ProcessTraceRefs) { + const facets = new ProcessFacets(); + let after = 0; + let pending: FacetChange[] = []; + let loading: Promise> | undefined; + return () => { + if (loading) return loading; + loading = (async () => { + const metrics = await readRecentSamples(mount, refs.samples); + const [identities, high] = await Promise.all([ + readStream(mount, refs.tree), fetchLatestSeq(mount, refs.facets), + ]); + if (high > after) { + const changes = await readStream(mount, { ...refs.facets, afterSeq: after, toSeq: high }); + pending.push(...changes); + after = high; + } + const tick = Math.max(0, ...metrics.map(metric => metric.tick)); + facets.apply(pending.filter(event => event.tick <= tick)); + pending = pending.filter(event => event.tick > tick); + return projectProcesses(identities, metrics, facets); + })().finally(() => { loading = undefined; }); + return loading; + }; } function message(e: unknown): string { @@ -151,12 +178,8 @@ export function useProcessTrace({ mount, refs, sessions: reported, done, selecte const enabled = !!mount && !!refs; const sessions = live ? reported : undefined; - const tree = usePolled( - enabled, live, () => readStream(mount!, refs!.tree), `${mount}|${refs?.tree.stream}`, - ); - const sampled = usePolled( - enabled, live, () => readRecentSamples(mount!, refs!.samples), `${mount}|${refs?.samples.stream}`, - ); + const reader = useMemo(() => mount && refs ? processReader(mount, refs) : undefined, [mount, refs?.tree.stream, refs?.samples.stream, refs?.facets.stream]); + const process = usePolled(enabled, live, () => reader!(), `${mount}|${refs?.tree.stream}`); const stacked = usePolled( enabled && !!selectedKey, live, () => readStream(mount!, refs!.stacks), `${mount}|${refs?.stacks.stream}`, ); @@ -165,18 +188,18 @@ export function useProcessTrace({ mount, refs, sessions: reported, done, selecte ); const stackCheckpoint = useCheckpoint(mount, sessions?.stacks, stacked.reload); - const sampleCheckpoint = useCheckpoint(mount, sessions?.samples, sampled.reload); + const sampleCheckpoint = useCheckpoint(mount, sessions?.samples, process.reload); const collectStack = useCallback( (key: string, transport: string) => stackCheckpoint.checkpoint({ key, transport, reason: "manual" }), [stackCheckpoint.checkpoint], ); const refreshFacets = useCallback((key: string) => sampleCheckpoint.checkpoint({ key }), [sampleCheckpoint.checkpoint]); - const nodes = useMemo(() => tree.value ?? [], [tree.value]); - const samples = useMemo(() => sampled.value ?? [], [sampled.value]); + const nodes = useMemo(() => process.value?.nodes ?? [], [process.value]); + const samples = useMemo(() => process.value?.samples ?? [], [process.value]); const stacks = useMemo(() => stacked.value ?? [], [stacked.value]); const goprof = useMemo(() => profiled.value ?? [], [profiled.value]); - const error = tree.error ?? sampled.error ?? stacked.error ?? profiled.error; + const error = process.error ?? stacked.error ?? profiled.error; return { nodes, @@ -184,7 +207,7 @@ export function useProcessTrace({ mount, refs, sessions: reported, done, selecte stacks, goprof, ...(mount && refs?.goprof ? { goprofExportUrl: traceExportUrl(mount, refs.goprof, "pprof") } : {}), - loading: enabled && tree.value === null && !tree.error, + loading: enabled && process.value === null && !process.error, ...(error ? { error } : {}), canCollect: enabled && !!sessions, collecting: stackCheckpoint.busy, diff --git a/webapp/vite.config.test.ts b/webapp/vite.config.test.ts index 197e6d6..101dfdb 100644 --- a/webapp/vite.config.test.ts +++ b/webapp/vite.config.test.ts @@ -11,6 +11,8 @@ const options = { localUI: false, uiDirectory, apiURL: "http://localhost:8080" } beforeAll(() => { const source = resolve(uiDirectory, "packages/ui/src"); mkdirSync(`${source}/styles`, { recursive: true }); + mkdirSync(resolve(source, "../dist/runtime"), { recursive: true }); + writeFileSync(resolve(source, "../dist/runtime/importmap.json"), "{}"); for (const file of ["index.ts", "components.ts", "tailwind-preset.ts", "styles/full.css", "styles/mdx-editor.css"]) { writeFileSync(resolve(source, file), ""); } @@ -20,6 +22,7 @@ beforeAll(() => { "./tailwind-preset": { import: "./dist/tailwind-preset.js" }, "./styles.css": "./dist/styles.css", "./mdx-editor.css": "./dist/mdx-editor.css", + "./runtime/*": "./dist/runtime/*", } })); }); afterAll(() => rmSync(uiDirectory, { recursive: true })); @@ -66,6 +69,14 @@ describe("Clicky UI resolution", () => { expect(config.resolve?.alias).toEqual([]); }); + it("resolves generated runtime assets from the local package build", () => { + const aliases = createViteConfig({ ...options, localUI: true }).resolve?.alias; + if (!Array.isArray(aliases)) throw new Error("Expected alias array"); + const entry = "@flanksource/clicky-ui/runtime/importmap.json"; + const alias = aliases.find(value => new RegExp(value.find).test(entry)); + expect(alias && entry.replace(alias.find, alias.replacement)).toBe(`${uiDirectory}/packages/ui/dist/runtime/importmap.json`); + }); + it("uses exact aliases for local source, CSS, and theme entries", () => { const config = createViteConfig({ ...options, localUI: true }); const aliases = config.resolve?.alias; diff --git a/webapp/vite.config.ts b/webapp/vite.config.ts index 96ad252..462e9c2 100644 --- a/webapp/vite.config.ts +++ b/webapp/vite.config.ts @@ -1,5 +1,5 @@ import { existsSync, readFileSync } from "node:fs"; -import { resolve } from "node:path"; +import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import react from "@vitejs/plugin-react"; import tailwindcss from "@tailwindcss/vite"; @@ -18,11 +18,17 @@ function clickyAliases(uiDirectory: string) { const target = typeof value === "string" ? value : value.import; if (!target?.startsWith("./dist/")) return []; const entry = key === "." ? "@flanksource/clicky-ui" : `@flanksource/clicky-ui${key.slice(1)}`; + const pattern = entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + if (key.includes("*")) { + const source = resolve(packageRoot, target.replace("*", "$1")); + if (!existsSync(dirname(source))) throw new Error(`Missing local Clicky UI assets ${dirname(source)}; build the local package first`); + return [{ find: new RegExp(`^${pattern.replace("\\*", "(.+)")}$`), replacement: source }]; + } const cssSource: Record = { "./dist/styles.css": "styles/full.css", "./dist/mdx-editor.css": "styles/mdx-editor.css" }; const relative = cssSource[target] ?? target.slice("./dist/".length).replace(/\.js$/, ".ts"); const source = resolve(packageRoot, "src", relative); if (!existsSync(source)) throw new Error(`Missing local Clicky UI entrypoint ${source}`); - return [{ find: new RegExp(`^${entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`), replacement: source }]; + return [{ find: new RegExp(`^${pattern}$`), replacement: source }]; }); } From 2286d57fbe4ac9c0961af6aacea22f4ce5b96e4f Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 09:06:51 +0200 Subject: [PATCH 11/89] feat(traces): unify process kinds and add per-run combined records feed Process sampling is now the single kind process, replacing process_samples and process_groups. Host processes reuse the Resources options, and the process capture is renamed to processcapture. Adds a unified per-run records feed (SSE or NDJSON with resumable Last-Event-ID) and result-scoped record selection, plus a schema list helper used by storeSchemas. BREAKING CHANGE: the process_samples and process_groups kinds are removed; definitions must use kind process, and collect.host.processeGroups is replaced by collect.host.processes. --- pkg/definition/compile_spec_test.go | 4 +- pkg/definition/coverage_spec_test.go | 5 +- pkg/definition/crd.go | 2 +- pkg/definition/definition_suite_test.go | 6 + pkg/definition/entries_host.go | 9 -- pkg/definition/entries_runtime.go | 6 +- pkg/definition/sections.go | 4 +- pkg/definition/start_spec_test.go | 4 +- pkg/definition/testdata/all-kinds.yaml | 6 +- pkg/traceserve/records/feed.go | 199 ++++++++++++++++++++++++ pkg/traceserve/records/handler.go | 20 ++- pkg/traceserve/records/handler_test.go | 65 +++++++- pkg/traceserve/records/process.go | 55 +++++++ pkg/traceserve/traceserve.go | 12 +- 14 files changed, 355 insertions(+), 42 deletions(-) create mode 100644 pkg/traceserve/records/feed.go create mode 100644 pkg/traceserve/records/process.go diff --git a/pkg/definition/compile_spec_test.go b/pkg/definition/compile_spec_test.go index 1ff5e11..422fe55 100644 --- a/pkg/definition/compile_spec_test.go +++ b/pkg/definition/compile_spec_test.go @@ -40,8 +40,8 @@ var _ = Describe("a compiled definition", func() { "jvm_jfr", `{"target":{"seam":"agent","selector":{"service.name":"pricing"},"wait":true,"allowMutation":true},"engine":"jfr","settings":"profile","threads":true,"maxStackDepth":64}`, ""), Entry("native thread stacks", " collect: {process: {nativeStacks: [{}]}}", "stacks", `{"target":{"seam":"process"}}`, `{"transport":"native"}`), - Entry("process resources", " collect: {process: {resources: [{interval: 1s, facets: [ports, connections]}]}}", - "process_samples", `{"target":{"seam":"process"},"interval":"1s","facets":["ports","connections"]}`, ""), + Entry("process resources", " collect: {process: {resources: [{interval: 1s, facets: [sockets, connections]}]}}", + "process", `{"target":{"seam":"process"},"interval":"1s","facets":["sockets","connections"]}`, ""), Entry("a Prometheus scrape", " collect: {prometheus: {scrape: [{endpoints: ['http://localhost:8080/metrics'], interval: 15s, labels: {env: dev}}]}}", "prometheus", `{"target":{"seam":"host"},"endpoints":["http://localhost:8080/metrics"],"interval":"15s","labels":{"env":"dev"}}`, ""), Entry("kubernetes logs", " collect: {logs: {kubernetes: [{namespace: checkout, podSelector: app=checkout, container: api}]}}", diff --git a/pkg/definition/coverage_spec_test.go b/pkg/definition/coverage_spec_test.go index 90aecd1..912c13a 100644 --- a/pkg/definition/coverage_spec_test.go +++ b/pkg/definition/coverage_spec_test.go @@ -12,7 +12,6 @@ import ( "github.com/flanksource/telltale/pkg/definition" "github.com/flanksource/telltale/pkg/traces" - "github.com/flanksource/telltale/pkg/tracing/process" ) // path is a list's path, section.group.type. @@ -41,9 +40,7 @@ var _ = Describe("the typed lists", func() { lists := definition.Lists() It("map every registered kind to a list", func() { - // collect.process.tree configures the run-wide process tree, which - // every command or pid run records, rather than arming a capture. - covered := map[string]bool{process.TreeKind: true} + covered := map[string]bool{} for _, at := range lists { covered[at.Kind] = true } diff --git a/pkg/definition/crd.go b/pkg/definition/crd.go index 1fa4e9c..cee7bbb 100644 --- a/pkg/definition/crd.go +++ b/pkg/definition/crd.go @@ -58,7 +58,7 @@ func structural(node map[string]any, path string) (map[string]any, error) { if ref, ok := node["$ref"]; ok { return nil, fmt.Errorf("schema %s refers to %v: the reflector inlines every type, so a $ref is a schema the CRD cannot carry", path, ref) } - if node["description"] == dynamicValue || strings.HasPrefix(fmt.Sprint(node["description"]), "Recursive reference to ") { + if len(node) == 0 || node["description"] == dynamicValue || strings.HasPrefix(fmt.Sprint(node["description"]), "Recursive reference to ") { return map[string]any{"x-kubernetes-preserve-unknown-fields": true}, nil } out := map[string]any{} diff --git a/pkg/definition/definition_suite_test.go b/pkg/definition/definition_suite_test.go index 2e5aadb..84258bc 100644 --- a/pkg/definition/definition_suite_test.go +++ b/pkg/definition/definition_suite_test.go @@ -37,5 +37,11 @@ func decode(yaml string) *definition.TraceDefinition { var examples = []string{ filepath.Join("..", "..", "examples", "definitions", "checkout.yaml"), filepath.Join("..", "..", "examples", "definitions", "logs-and-queries.yaml"), + filepath.Join("..", "..", "examples", "definitions", "java-app.yaml"), + filepath.Join("..", "..", "examples", "definitions", "java-build.yaml"), + filepath.Join("..", "..", "examples", "definitions", "go-app.yaml"), + filepath.Join("..", "..", "examples", "definitions", "go-build.yaml"), + filepath.Join("..", "..", "examples", "definitions", "node-app.yaml"), + filepath.Join("..", "..", "examples", "definitions", "node-build.yaml"), filepath.Join("testdata", "all-kinds.yaml"), } diff --git a/pkg/definition/entries_host.go b/pkg/definition/entries_host.go index 14cf556..1aca37d 100644 --- a/pkg/definition/entries_host.go +++ b/pkg/definition/entries_host.go @@ -4,7 +4,6 @@ import ( "errors" "github.com/flanksource/commons-db/models" - "github.com/flanksource/telltale/pkg/tracing/groups" "github.com/flanksource/telltale/pkg/tracing/logs" "github.com/flanksource/telltale/pkg/tracing/opensearch" "github.com/flanksource/telltale/pkg/tracing/prometheus" @@ -15,14 +14,6 @@ import ( "github.com/flanksource/telltale/pkg/tracing/sqlserver/xevent" ) -// ProcessGroups records what each tool's processes on the host use. -type ProcessGroups struct { - Named - groups.Options -} - -func (p *ProcessGroups) options(Located) (any, any, error) { return p.Options, nil, nil } - // Scrape scrapes Prometheus endpoints into the managed Prometheus. type Scrape struct { Named diff --git a/pkg/definition/entries_runtime.go b/pkg/definition/entries_runtime.go index 4f46f10..ec062f9 100644 --- a/pkg/definition/entries_runtime.go +++ b/pkg/definition/entries_runtime.go @@ -10,7 +10,7 @@ import ( "github.com/flanksource/telltale/pkg/tracing/jfr" "github.com/flanksource/telltale/pkg/tracing/llm" "github.com/flanksource/telltale/pkg/tracing/logs" - "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" "github.com/flanksource/telltale/pkg/tracing/spans" tracesql "github.com/flanksource/telltale/pkg/tracing/sql" "github.com/flanksource/telltale/pkg/tracing/stacks" @@ -113,10 +113,10 @@ func (*NativeStacks) options(Located) (any, any, error) { // Resources samples every process of the tree. type Resources struct { Named - process.SampleOptions + processcapture.Options } -func (r *Resources) options(Located) (any, any, error) { return r.SampleOptions, nil, nil } +func (r *Resources) options(Located) (any, any, error) { return r.Options, nil, nil } // FlightRecorder starts a JFR recording in a JVM. type FlightRecorder struct { diff --git a/pkg/definition/sections.go b/pkg/definition/sections.go index f3fc30a..185f4cd 100644 --- a/pkg/definition/sections.go +++ b/pkg/definition/sections.go @@ -69,7 +69,7 @@ type CollectProcess struct { // is one object, not a capture list, and absent reads no facets. Tree *traces.TreeOptions `json:"tree,omitempty" clicky:"title=Process tree,desc=What the run-wide process tree reads of each process"` NativeStacks []NativeStacks `json:"nativeStacks,omitempty" clicky:"title=Native stacks,desc=Thread stacks of any process: sample (darwin) eu-stack or gdb (linux)" telltale:"kind=stacks"` - Resources []Resources `json:"resources,omitempty" clicky:"title=Resources,desc=CPU memory disk IO and descriptors of every process" telltale:"kind=process_samples"` + Resources []Resources `json:"resources,omitempty" clicky:"title=Processes,desc=Startup metadata resource changes and metrics" telltale:"kind=process"` } // CollectLogs reads log sources outside the process, by the backend that @@ -101,7 +101,7 @@ type CollectQuery struct { } type CollectHost struct { - ProcessGroups []ProcessGroups `json:"processGroups,omitempty" clicky:"title=Process groups" telltale:"kind=process_groups"` + Processes []Resources `json:"processes,omitempty" clicky:"title=Processes" telltale:"kind=process"` } type CollectPrometheus struct { diff --git a/pkg/definition/start_spec_test.go b/pkg/definition/start_spec_test.go index 49198d1..f5a848e 100644 --- a/pkg/definition/start_spec_test.go +++ b/pkg/definition/start_spec_test.go @@ -16,7 +16,7 @@ import ( "github.com/flanksource/telltale/pkg/definition" "github.com/flanksource/telltale/pkg/traces" "github.com/flanksource/telltale/pkg/tracing/goprof" - "github.com/flanksource/telltale/pkg/tracing/process" + "github.com/flanksource/telltale/pkg/tracing/processcapture" "github.com/flanksource/telltale/pkg/tracing/stacks" "github.com/flanksource/telltale/pkg/tracing/tracingtest" ) @@ -79,7 +79,7 @@ var _ = Describe("the built-in definitions", func() { result, err := run.Wait() Expect(err).ToNot(HaveOccurred()) Expect(result.PID).To(Equal(target.Process.Pid)) - Expect(result.Process.Tree.Kind).To(Equal(process.TreeKind)) + Expect(result.Process.Tree.Kind).To(Equal(processcapture.Kind)) Expect(result.CheckpointErrors).To(BeEmpty()) }) diff --git a/pkg/definition/testdata/all-kinds.yaml b/pkg/definition/testdata/all-kinds.yaml index 8e876df..314a3b9 100644 --- a/pkg/definition/testdata/all-kinds.yaml +++ b/pkg/definition/testdata/all-kinds.yaml @@ -69,7 +69,7 @@ spec: - {} resources: - interval: 1s - facets: [ports] + facets: [sockets] logs: kubernetes: - namespace: checkout @@ -125,8 +125,8 @@ spec: params: {namespace: checkout} every: 30s host: - processGroups: - - groups: [claude] + processes: + - facets: [files, sockets, connections] prometheus: scrape: - endpoints: [http://localhost:8080/metrics] diff --git a/pkg/traceserve/records/feed.go b/pkg/traceserve/records/feed.go new file mode 100644 index 0000000..c5c278c --- /dev/null +++ b/pkg/traceserve/records/feed.go @@ -0,0 +1,199 @@ +package records + +import ( + "encoding/base64" + "encoding/json" + "fmt" + "net/http" + "strconv" + "time" + + "github.com/flanksource/telltale/pkg/traces/read" +) + +// FeedHandler serves the combined records of a single run, never arbitrary +// streams selected by the client. +func FeedHandler(dataDir string) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + selected, err := selectFeed(dataDir, r.PathValue("run")) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + defer func() { + if err := selected.Close(); err != nil { + panic(http.ErrAbortHandler) + } + }() + refs, err := filterFeed(selected.Refs, r) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + values := r.URL.Query() + for key := range values { + switch key { + case "kind", "stream", "limit", "sort", "cursor", "follow", "format", "resume", "from", "until": + default: + http.Error(w, "unknown feed parameter: "+key, http.StatusBadRequest) + return + } + } + q := read.FeedQuery{Sort: values.Get("sort"), Query: read.Query{Cursor: values.Get("cursor")}} + if q.Sort != "" && q.Sort != "seq" && q.Sort != "timestamp" { + http.Error(w, "invalid record sort", http.StatusBadRequest) + return + } + for name, destination := range map[string]*time.Time{"from": &q.From, "until": &q.Until} { + if raw := values.Get(name); raw != "" { + *destination, err = time.Parse(time.RFC3339Nano, raw) + if err != nil { + http.Error(w, err.Error(), 400) + return + } + } + } + if err := q.Validate(); err != nil { + http.Error(w, err.Error(), 400) + return + } + if raw := values.Get("follow"); raw != "" { + follow, parseErr := strconv.ParseBool(raw) + if parseErr != nil { + http.Error(w, parseErr.Error(), 400) + return + } + if follow { + if q.Cursor != "" || (values.Get("format") != "" && values.Get("format") != "ndjson") { + http.Error(w, "invalid follow cursor or format", 400) + return + } + streamFeed(w, r, refs, q.Query) + return + } + } + if raw := values.Get("limit"); raw != "" { + q.Limit, err = strconv.Atoi(raw) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + } + page, err := read.FeedPage(r.Context(), refs, q) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + w.Header().Set("Content-Type", "application/json") + if err := json.NewEncoder(w).Encode(page); err != nil { + panic(http.ErrAbortHandler) + } + }) +} + +func selectFeed(dataDir, id string) (*read.Selection, error) { + return read.ResolveRuns(read.Scope{DataDir: dataDir, Run: id}) +} + +func filterFeed(refs []read.Ref, r *http.Request) ([]read.Ref, error) { + selected := []read.Ref{} + for _, ref := range refs { + owner, _ := ref.Runtime.Kinds.ResultOf(ref.Kind) + if kind := r.URL.Query().Get("kind"); kind != "" && ref.Kind != kind && owner != kind { + continue + } + if stream := r.URL.Query().Get("stream"); stream != "" && ref.Stream != stream { + continue + } + selected = append(selected, ref) + } + if len(selected) == 0 && len(refs) != 0 { + return nil, fmt.Errorf("capture selection is not armed by this run") + } + return selected, nil +} + +type feedResume struct { + From time.Time `json:"from"` + Until time.Time `json:"until"` + Run string `json:"run"` + Positions map[string]int64 `json:"positions"` + Generations map[string]string `json:"generations"` +} + +func streamFeed(w http.ResponseWriter, r *http.Request, refs []read.Ref, q read.Query) { + if r.Header.Get("Last-Event-ID") == "" && r.URL.Query().Get("resume") != "" { + r.Header.Set("Last-Event-ID", r.URL.Query().Get("resume")) + } + resume := feedResume{From: q.From, Until: q.Until, Run: r.PathValue("run"), Positions: map[string]int64{}, Generations: map[string]string{}} + if last := r.Header.Get("Last-Event-ID"); last != "" { + data, err := base64.RawURLEncoding.DecodeString(last) + if err != nil || json.Unmarshal(data, &resume) != nil || resume.Run != r.PathValue("run") || len(resume.Positions) != len(refs) || !resume.From.Equal(q.From) || !resume.Until.Equal(q.Until) { + http.Error(w, "invalid feed resume token", http.StatusBadRequest) + return + } + } + for i, ref := range refs { + key := ref.Stream + meta, err := ref.Runtime.Results.Backend.Meta(r.Context(), ref.Stream) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + _, hasPosition := resume.Positions[key] + if last := r.Header.Get("Last-Event-ID"); last != "" && (!hasPosition || resume.Generations[key] != meta.Generation || resume.Positions[key] < 0 || resume.Positions[key] > meta.HighSeq) { + http.Error(w, "feed resume stream changed", http.StatusBadRequest) + return + } + refs[i].AfterSeq = max(ref.AfterSeq, resume.Positions[key]) + resume.Positions[key] = refs[i].AfterSeq + resume.Generations[key] = meta.Generation + } + ndjson := r.URL.Query().Get("format") == "ndjson" + w.Header().Set("Content-Type", "text/event-stream") + if ndjson { + w.Header().Set("Content-Type", "application/x-ndjson") + } + w.Header().Set("Cache-Control", "no-cache") + w.Header().Set("X-Accel-Buffering", "no") + controller := http.NewResponseController(w) + if err := controller.Flush(); err != nil { + return + } + err := read.Feed(r.Context(), refs, q, func(record read.Record) error { + data, err := json.Marshal(record) + if err != nil { + return err + } + resume.Positions[record.Stream] = record.Seq + if ndjson { + _, err = fmt.Fprintf(w, "%s\n", data) + } else { + token, marshalErr := json.Marshal(resume) + if marshalErr != nil { + return marshalErr + } + _, err = fmt.Fprintf(w, "id: %s\ndata: %s\n\n", base64.RawURLEncoding.EncodeToString(token), data) + } + if err != nil { + return err + } + return controller.Flush() + }) + if r.Context().Err() != nil { + return + } + if err != nil { + if ndjson { + panic(http.ErrAbortHandler) + } + payload, marshalErr := json.Marshal(map[string]string{"error": err.Error()}) + if marshalErr != nil { + panic(http.ErrAbortHandler) + } + _, _ = fmt.Fprintf(w, "event: error\ndata: %s\n\n", payload) + } else if !ndjson { + _, _ = fmt.Fprint(w, "event: end\ndata: {}\n\n") + } + _ = controller.Flush() +} diff --git a/pkg/traceserve/records/handler.go b/pkg/traceserve/records/handler.go index dabb4bf..997f929 100644 --- a/pkg/traceserve/records/handler.go +++ b/pkg/traceserve/records/handler.go @@ -77,7 +77,7 @@ func recordValues(r *http.Request) (url.Values, error) { } for name := range values { switch name { - case "stream", "from", "until", "afterSeq", "toSeq", "filter", "where", "q", "limit", "cursor", "stats", "groupBy", "view", "follow", "format", "all": + case "stream", "result", "from", "until", "afterSeq", "toSeq", "filter", "where", "q", "limit", "cursor", "stats", "groupBy", "view", "follow", "format", "all": default: return nil, fmt.Errorf("unknown records parameter %q", name) } @@ -114,13 +114,25 @@ func selectRun(kind string, scope read.Scope) (*read.Selection, error) { return read.Resolve(kind, scope) } runtime := run.Runtime() + if scope.Result != "" { + storage := kind + "_" + scope.Result + owner, result := runtime.Kinds.ResultOf(storage) + if owner != kind || result == "" { + return nil, fmt.Errorf("kind %s has no result %q", kind, scope.Result) + } + kind = storage + } if _, ok := runtime.Kinds.Get(kind); !ok { return nil, fmt.Errorf("unknown trace kind %q", kind) } selected := &read.Selection{} - for _, capture := range run.Info().Captures { - if capture.Kind == kind { - selected.Refs = append(selected.Refs, read.Ref{RunID: scope.Run, Runtime: runtime, TraceRef: capture.Ref}) + refs, err := read.RunRefs(run.Info(), runtime) + if err != nil { + return nil, err + } + for _, ref := range refs { + if ref.Kind == kind { + selected.Refs = append(selected.Refs, ref) } } if len(selected.Refs) == 0 { diff --git a/pkg/traceserve/records/handler_test.go b/pkg/traceserve/records/handler_test.go index 7ca1c0c..9e6f475 100644 --- a/pkg/traceserve/records/handler_test.go +++ b/pkg/traceserve/records/handler_test.go @@ -90,6 +90,7 @@ var _ = Describe("run records route", func() { Expect(os.WriteFile(filepath.Join(host.Dir(), telltale.ManifestFile), data, 0o600)).To(Succeed()) mux := http.NewServeMux() mux.Handle("GET /api/traces/{run}/traces/{kind}/records", records.Handler(dir)) + mux.Handle("GET /api/traces/{run}/records", records.FeedHandler(dir)) server = httptest.NewServer(mux) DeferCleanup(server.Close) path = server.URL + "/api/traces/run-http/traces/" + fixtureKind + "/records" @@ -114,6 +115,66 @@ var _ = Describe("run records route", func() { Expect(json.Unmarshal(body, &result)).To(Succeed(), string(body)) return result } + It("resumes a unified SSE feed after the last record without replaying it", func() { + appendRows(1, 2) + _, err := capture.Stop(context.Background()) + Expect(err).NotTo(HaveOccurred()) + endpoint := server.URL + "/api/traces/run-http/records?follow=1" + response, err := server.Client().Get(endpoint) + Expect(err).NotTo(HaveOccurred()) + scanner := bufio.NewScanner(response.Body) + last := "" + count := 0 + for scanner.Scan() { + line := scanner.Text() + if strings.HasPrefix(line, "id: ") { + last = strings.TrimPrefix(line, "id: ") + } + if strings.HasPrefix(line, "data: ") && line != "data: {}" { + count++ + } + } + Expect(scanner.Err()).NotTo(HaveOccurred()) + Expect(response.Body.Close()).To(Succeed()) + Expect(count).To(Equal(2)) + Expect(last).NotTo(BeEmpty()) + request, err := http.NewRequest(http.MethodGet, endpoint, nil) + Expect(err).NotTo(HaveOccurred()) + request.Header.Set("Last-Event-ID", last) + response, err = server.Client().Do(request) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(response.Body.Close) + body, err := io.ReadAll(response.Body) + Expect(err).NotTo(HaveOccurred()) + Expect(string(body)).To(Equal("event: end\ndata: {}\n\n")) + }) + + It("serves the unified feed with native payloads and resumable sequence pages", func() { + appendRows(2, 1) + response, err := server.Client().Get(server.URL + "/api/traces/run-http/records?limit=1") + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(response.Body.Close) + Expect(response.StatusCode).To(Equal(http.StatusOK)) + var result struct { + Rows []struct { + Kind string `json:"kind"` + Seq int64 `json:"seq"` + Record query.Row `json:"record"` + } + NextCursor string `json:"nextCursor"` + } + Expect(json.NewDecoder(response.Body).Decode(&result)).To(Succeed()) + Expect(result.Rows).To(HaveLen(1)) + Expect(result.Rows[0].Seq).To(Equal(int64(1))) + Expect(result.Rows[0].Kind).To(Equal(fixtureKind)) + Expect(result.Rows[0].Record).To(HaveKeyWithValue("value", float64(2))) + Expect(result.NextCursor).NotTo(BeEmpty()) + response, err = server.Client().Get(server.URL + "/api/traces/run-http/records?sort=timestamp&cursor=" + url.QueryEscape(result.NextCursor)) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(response.Body.Close) + Expect(response.StatusCode).To(Equal(http.StatusBadRequest)) + }) + It("pages in profile order and applies repeated filters, time, seq, search and CEL before limit", func() { appendRows(0, 1, 2, 3) first := get(url.Values{"limit": {"2"}}) @@ -269,7 +330,7 @@ var _ = Describe("run records route", func() { }) It("reads and follows an in-process live run until it finishes", func() { dir := GinkgoT().TempDir() - run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: dir, PID: os.Getpid(), Duration: time.Second, Traces: []telltale.TraceSpec{{Kind: "process_samples"}}}) + run, err := telltale.Start(context.Background(), telltale.StartOptions{DataDir: dir, PID: os.Getpid(), Duration: time.Second, Traces: []telltale.TraceSpec{{Kind: "process"}}}) Expect(err).NotTo(HaveOccurred()) DeferCleanup(func() { Expect(run.Stop()).To(Succeed()); _, err := run.Wait(); Expect(err).NotTo(HaveOccurred()) }) mux := http.NewServeMux() @@ -278,7 +339,7 @@ var _ = Describe("run records route", func() { DeferCleanup(liveServer.Close) ctx, cancel := context.WithTimeout(context.Background(), 6*time.Second) defer cancel() - request, err := http.NewRequestWithContext(ctx, http.MethodGet, liveServer.URL+"/api/traces/"+run.ID()+"/traces/process_samples/records?follow=1", nil) + request, err := http.NewRequestWithContext(ctx, http.MethodGet, liveServer.URL+"/api/traces/"+run.ID()+"/traces/process/records?result=metrics&follow=1", nil) Expect(err).NotTo(HaveOccurred()) response, err := liveServer.Client().Do(request) Expect(err).NotTo(HaveOccurred()) diff --git a/pkg/traceserve/records/process.go b/pkg/traceserve/records/process.go new file mode 100644 index 0000000..2823a20 --- /dev/null +++ b/pkg/traceserve/records/process.go @@ -0,0 +1,55 @@ +package records + +import ( + "encoding/json" + "fmt" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/flanksource/telltale/pkg/tracing/processcapture" + "net/http" + "strconv" +) + +func ProcessGroupsHandler(dataDir string) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + for key := range r.URL.Query() { + if key != "stream" && key != "afterSeq" { + http.Error(w, "unknown process groups parameter: "+key, 400) + return + } + } + selected, err := selectRun(processcapture.Kind, read.Scope{DataDir: dataDir, Run: r.PathValue("run")}) + if err != nil { + http.Error(w, err.Error(), 400) + return + } + defer func() { + if selected.Close() != nil { + panic(http.ErrAbortHandler) + } + }() + refs, err := selectStreams(selected.Refs, r.URL.Query().Get("stream")) + if err != nil || len(refs) != 1 { + http.Error(w, fmt.Sprintf("select one process capture: %v", err), 400) + return + } + after := int64(0) + if value := r.URL.Query().Get("afterSeq"); value != "" { + after, err = strconv.ParseInt(value, 10, 64) + } + if err != nil || after < 0 { + http.Error(w, "invalid afterSeq", 400) + return + } + ref := refs[0].TraceRef + ref.AfterSeq = after + frames, err := processcapture.ReadFrames(r.Context(), refs[0].Runtime, ref) + if err != nil { + http.Error(w, err.Error(), 400) + return + } + w.Header().Set("Content-Type", "application/json") + if json.NewEncoder(w).Encode(frames) != nil { + panic(http.ErrAbortHandler) + } + }) +} diff --git a/pkg/traceserve/traceserve.go b/pkg/traceserve/traceserve.go index 493b635..31d49d4 100644 --- a/pkg/traceserve/traceserve.go +++ b/pkg/traceserve/traceserve.go @@ -69,20 +69,12 @@ func Open(options OpenOptions) (*tracing.Runtime, func() error, error) { // A shared SQLite backend retains the first opener's resolver. Fill it before // opening the backend so concurrent registries cannot see half its catalog. func storeSchemas(kinds *tracing.Kinds) (*recordstore.Schemas, error) { - infos, err := kinds.List() + definitions, err := kinds.Schemas() if err != nil { return nil, err } schemas := recordstore.NewSchemas() - for _, info := range infos { - plugin, ok := kinds.Get(info.Name) - if !ok { - return nil, fmt.Errorf("trace kind %q disappeared from catalog", info.Name) - } - schema, err := plugin.Schema(info.Name) - if err != nil { - return nil, err - } + for _, schema := range definitions { if err := schemas.Register(schema.Kind, schema.Columns, schema.Options); err != nil { return nil, err } From 8eaa92f52c1da26f2931fdd826d36ff320069016 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 22:48:04 +0200 Subject: [PATCH 12/89] feat(tracing): add clicky preset definition with entity and task probes Arm a clicky process's agent probes (exec, entity, task, HTTP, logs, heap) through one built-in definition so a single selector records its whole workload. The new entity and task kinds exist only over an agent; telltale registers no such probe itself. Preset collect groups hold kinds other groups also arm, so an ad-hoc capture lands there only when no other list takes it. The records feed gains excludeKind and an optional ANSI presentation, and a process endpoint returns each identity's latest measurements instead of the paged history. An empty capture selection now errors only when a kind or stream was requested. --- pkg/definition/builtin/clicky.yaml | 31 ++++++ pkg/definition/entries_runtime.go | 25 +++++ pkg/definition/inline.go | 9 ++ pkg/definition/inline_spec_test.go | 26 +++++ pkg/definition/sections.go | 18 +++- pkg/definition/start_spec_test.go | 2 +- pkg/definition/store_spec_test.go | 1 + pkg/definition/testdata/all-kinds.yaml | 16 +++ pkg/definition/walk.go | 8 +- pkg/traces/builtin_clicky.go | 27 +++++ pkg/traces/pretty_records_test.go | 2 + pkg/traces/read/processes.go | 36 +++++++ pkg/traces/read/processes_test.go | 36 +++++++ pkg/traceserve/records/feed.go | 20 +++- pkg/traceserve/records/handler_test.go | 18 ++++ pkg/traceserve/records/presentation.go | 29 ++++++ pkg/traceserve/records/processes.go | 36 +++++++ pkg/tracing/entity/entity.go | 100 ++++++++++++++++++ pkg/tracing/entity/pretty.go | 33 ++++++ pkg/tracing/processcapture/kind.go | 2 +- pkg/tracing/processcapture/latest.go | 119 ++++++++++++++++++++++ pkg/tracing/processcapture/latest_test.go | 32 ++++++ pkg/tracing/task/pretty.go | 32 ++++++ pkg/tracing/task/task.go | 95 +++++++++++++++++ 24 files changed, 745 insertions(+), 8 deletions(-) create mode 100644 pkg/definition/builtin/clicky.yaml create mode 100644 pkg/definition/inline_spec_test.go create mode 100644 pkg/traces/builtin_clicky.go create mode 100644 pkg/traces/read/processes.go create mode 100644 pkg/traces/read/processes_test.go create mode 100644 pkg/traceserve/records/presentation.go create mode 100644 pkg/traceserve/records/processes.go create mode 100644 pkg/tracing/entity/entity.go create mode 100644 pkg/tracing/entity/pretty.go create mode 100644 pkg/tracing/processcapture/latest.go create mode 100644 pkg/tracing/processcapture/latest_test.go create mode 100644 pkg/tracing/task/pretty.go create mode 100644 pkg/tracing/task/task.go diff --git a/pkg/definition/builtin/clicky.yaml b/pkg/definition/builtin/clicky.yaml new file mode 100644 index 0000000..2a1ed82 --- /dev/null +++ b/pkg/definition/builtin/clicky.yaml @@ -0,0 +1,31 @@ +apiVersion: telltale.flanksource.com/v1alpha1 +kind: TraceDefinition +metadata: + name: clicky + annotations: + telltale.flanksource.com/summary: Record a clicky process's executions, entity operations, tasks, HTTP, logs and heap through its telltale agent + telltale.flanksource.com/examples: | + 1234 # record process 1234 until Ctrl+C + 1234 --duration 1m # record it for a minute + 1234 --every 5s # read its heap every 5 seconds +spec: + description: >- + Arms every probe github.com/flanksource/clicky/telltale registers in a clicky process: the commands it runs, its entity + operations, its tasks' transitions and progress, its commons HTTP exchanges and its commons logs. The process must run + the agent (telltale.Start, or the auto import with TELLTALE_AGENT=1); a process without one is refused. Its heap + profile is read through the agent every 30s and as the run stops. + every: 30s + collect: + clicky: + exec: + - {} + entity: + - {} + task: + - {} + http: + - features: [http] + logs: + - {} + pprof: + - profile: heap diff --git a/pkg/definition/entries_runtime.go b/pkg/definition/entries_runtime.go index ec062f9..eb7e24c 100644 --- a/pkg/definition/entries_runtime.go +++ b/pkg/definition/entries_runtime.go @@ -4,6 +4,7 @@ import ( "errors" "fmt" + "github.com/flanksource/telltale/pkg/tracing/entity" "github.com/flanksource/telltale/pkg/tracing/exec" "github.com/flanksource/telltale/pkg/tracing/goprof" tracehttp "github.com/flanksource/telltale/pkg/tracing/http" @@ -14,6 +15,7 @@ import ( "github.com/flanksource/telltale/pkg/tracing/spans" tracesql "github.com/flanksource/telltale/pkg/tracing/sql" "github.com/flanksource/telltale/pkg/tracing/stacks" + "github.com/flanksource/telltale/pkg/tracing/task" "github.com/flanksource/telltale/pkg/tracing/terminal" ) @@ -180,6 +182,29 @@ func (p *ExecProbe) options(Located) (any, any, error) { return exec.Options{Name: p.Executable, TailBytes: p.TailBytes}, nil, nil } +// EntityProbe records the entity operations a clicky agent runs. +type EntityProbe struct { + Named + Agent + entity.Options +} + +func (p *EntityProbe) options(Located) (any, any, error) { return p.Options, nil, nil } + +// TaskProbe records the tasks a clicky agent runs. TaskName is the task +// kind's name glob, renamed so it does not take the entry's name. +type TaskProbe struct { + Named + Agent + TaskName string `json:"taskName,omitempty" clicky:"title=Task name,desc=Task name glob"` + Group string `json:"group,omitempty" clicky:"title=Group,desc=Parent group name glob"` + ProgressIntervalMs int `json:"progressIntervalMs,omitempty" clicky:"title=Progress interval,desc=Minimum milliseconds between progress records of a task"` +} + +func (p *TaskProbe) options(Located) (any, any, error) { + return task.Options{Name: p.TaskName, Group: p.Group, ProgressIntervalMs: p.ProgressIntervalMs}, nil, nil +} + // LLMProbe records the provider calls an agent or telltale makes. type LLMProbe struct { Named diff --git a/pkg/definition/inline.go b/pkg/definition/inline.go index a8b6788..34cc6ea 100644 --- a/pkg/definition/inline.go +++ b/pkg/definition/inline.go @@ -69,6 +69,9 @@ func placeCapture(spec *Spec, capture telltale.RequestedCapture) (Located, error } matches = append(matches, at) } + if own := slices.DeleteFunc(slices.Clone(matches), func(at Located) bool { return at.Preset }); len(own) > 0 { + matches = own + } switch { case len(tried) == 0: return Located{}, unarmable(capture) @@ -195,6 +198,12 @@ func (p *ExecProbe) inline(map[string]any) error { return nil } +// inline takes the task kind's name glob, which decodes as the entry's name. +func (p *TaskProbe) inline(map[string]any) error { + p.TaskName, p.Name = p.Name, "" + return nil +} + // inline takes the spans kind's opensearch block. func (s *OpenSearchSpans) inline(params map[string]any) error { data, err := json.Marshal(params["opensearch"]) diff --git a/pkg/definition/inline_spec_test.go b/pkg/definition/inline_spec_test.go new file mode 100644 index 0000000..0cbb365 --- /dev/null +++ b/pkg/definition/inline_spec_test.go @@ -0,0 +1,26 @@ +package definition_test + +import ( + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + + "github.com/flanksource/telltale" + "github.com/flanksource/telltale/pkg/definition" + "github.com/flanksource/telltale/pkg/tracing/target" +) + +var _ = Describe("an ad-hoc capture through an agent", func() { + agent := target.Target{Seam: target.Agent, Selector: map[string]string{"service.name": "example"}} + + DescribeTable("lands in the one list that takes it, a preset group's only when no other does", + func(kind string, params map[string]any, list string) { + _, pointers, fields := definition.Inline([]telltale.RequestedCapture{{Kind: kind, Params: params, Target: agent, Seam: target.Agent}}) + Expect(fields).To(BeEmpty()) + Expect(pointers).To(Equal(map[string]string{"/spec/collect/" + list + "/0": "/traces/" + kind})) + }, + Entry("http, which collect.go also arms", "http", map[string]any{"features": []any{"http"}}, "go/http"), + Entry("exec, which collect.go also arms", "exec", map[string]any{"name": "git"}, "go/exec"), + Entry("entity, which only the clicky preset arms", "entity", map[string]any{"entity": "widget"}, "clicky/entity"), + Entry("task, which only the clicky preset arms", "task", map[string]any{"name": "deploy *"}, "clicky/task"), + ) +}) diff --git a/pkg/definition/sections.go b/pkg/definition/sections.go index 185f4cd..c9be631 100644 --- a/pkg/definition/sections.go +++ b/pkg/definition/sections.go @@ -5,7 +5,9 @@ import "github.com/flanksource/telltale/pkg/traces" // Each typed list carries the kind it compiles to in its telltale tag // (kind=), and may fix the seam (seam=) or the logs backend // (backend=). A group's tag gives the seam its lists are aimed at -// unless a list fixes its own. The tags are read by the walker (walk.go); +// unless a list fixes its own. A preset group (preset) gathers lists of kinds +// other groups also arm, so an ad-hoc capture lands in it only when no other +// list takes it. The tags are read by the walker (walk.go); // the field's json name is the path segment and the default-name part. // Proxy are the proxies a command is routed through, each on its own port @@ -40,6 +42,7 @@ type InstrumentSQLServer struct { // runtime or the servers it reaches. type Collect struct { Go CollectGo `json:"go,omitzero" clicky:"title=Go" telltale:"seam=process"` + Clicky CollectClicky `json:"clicky,omitzero" clicky:"title=Clicky" telltale:"seam=agent,preset"` Process CollectProcess `json:"process,omitzero" clicky:"title=Process" telltale:"seam=process"` Logs CollectLogs `json:"logs,omitzero" clicky:"title=Logs" telltale:"seam=host"` Query CollectQuery `json:"query,omitzero" clicky:"title=Query" telltale:"seam=host"` @@ -63,6 +66,19 @@ type CollectGo struct { Spans []SpansProbe `json:"spans,omitempty" clicky:"title=Spans" telltale:"kind=spans,seam=agent"` } +// CollectClicky reads the probes github.com/flanksource/clicky/telltale +// registers in a clicky process: its executions, entity operations, tasks, +// commons HTTP and commons logs, and the SDK's Go profiles. The agent is the run's pid's, or the one an +// entry names. +type CollectClicky struct { + Exec []ExecProbe `json:"exec,omitempty" clicky:"title=Executions" telltale:"kind=exec"` + Entity []EntityProbe `json:"entity,omitempty" clicky:"title=Entity operations" telltale:"kind=entity"` + Task []TaskProbe `json:"task,omitempty" clicky:"title=Tasks" telltale:"kind=task"` + HTTP []HTTPProbe `json:"http,omitempty" clicky:"title=HTTP" telltale:"kind=http"` + Logs []LogsProbe `json:"logs,omitempty" clicky:"title=Logs" telltale:"kind=logs"` + PProf []CollectPProf `json:"pprof,omitempty" clicky:"title=pprof,desc=Heap cpu allocs or goroutine profiles read through the agent at each checkpoint" telltale:"kind=goprof"` +} + // CollectProcess reads the execution's process tree. type CollectProcess struct { // Tree is the run-wide process tree every command or pid run records; it diff --git a/pkg/definition/start_spec_test.go b/pkg/definition/start_spec_test.go index f5a848e..9031e3d 100644 --- a/pkg/definition/start_spec_test.go +++ b/pkg/definition/start_spec_test.go @@ -63,7 +63,7 @@ var _ = Describe("the built-in definitions", func() { It("each have the summary, description and examples their command's help shows", func() { defs, err := definition.Builtins() Expect(err).ToNot(HaveOccurred()) - Expect(defs).To(HaveExactElements(HaveField("Name", "gops"), HaveField("Name", "ps"))) + Expect(defs).To(HaveExactElements(HaveField("Name", "clicky"), HaveField("Name", "gops"), HaveField("Name", "ps"))) for _, def := range defs { Expect(def.Summary()).ToNot(Equal(def.Spec.Description), def.Name) Expect(def.Spec.Description).ToNot(BeEmpty(), def.Name) diff --git a/pkg/definition/store_spec_test.go b/pkg/definition/store_spec_test.go index a410971..56cc5c7 100644 --- a/pkg/definition/store_spec_test.go +++ b/pkg/definition/store_spec_test.go @@ -48,6 +48,7 @@ var _ = Describe("the definition store", func() { HaveField("Definition.Spec.Collect.Prometheus.Scrape", HaveExactElements(HaveField("Endpoints", ConsistOf("http://cwd:8080/metrics"))))), And(HaveField("Name", "ps"), HaveField("Layer", datadir.ConfigGlobal)), And(HaveField("Name", "gops"), HaveField("Layer", definition.LayerBuiltin)), + And(HaveField("Name", "clicky"), HaveField("Layer", definition.LayerBuiltin)), )) }) diff --git a/pkg/definition/testdata/all-kinds.yaml b/pkg/definition/testdata/all-kinds.yaml index 314a3b9..2060116 100644 --- a/pkg/definition/testdata/all-kinds.yaml +++ b/pkg/definition/testdata/all-kinds.yaml @@ -61,6 +61,22 @@ spec: - minLevel: warn spans: - {} + clicky: + exec: + - executable: git + entity: + - entity: widget + errorsOnly: true + task: + - taskName: "deploy *" + progressIntervalMs: 5000 + http: + - features: [http] + logs: + - minLevel: warn + pprof: + - source: pprof + profile: goroutine process: tree: facets: true diff --git a/pkg/definition/walk.go b/pkg/definition/walk.go index 13fd4ef..6df75d0 100644 --- a/pkg/definition/walk.go +++ b/pkg/definition/walk.go @@ -29,6 +29,9 @@ type Located struct { Seam target.Seam // Backend fixes a logs list's cloud backend; Provider a query list's. Backend, Provider string + // Preset is a list of a preset group, which an ad-hoc capture another + // list also takes does not land in. + Preset bool // Title and Description are the list's, as its form shows them. Title, Description string // Name is the entry's name, or its default once Resolve filled it. @@ -71,6 +74,7 @@ func (l Located) DefaultName(definition string) string { // listTag is a typed list's telltale tag, or a group's (seam alone). type listTag struct { kind, seam, backend, provider string + preset bool } func parseTag(field reflect.StructField) listTag { @@ -86,6 +90,8 @@ func parseTag(field reflect.StructField) listTag { tag.backend = value case "provider": tag.provider = value + case "preset": + tag.preset = true } } return tag @@ -147,7 +153,7 @@ func walkGroup(section, group string, groupTag listTag, value reflect.Value) []L } found = append(found, Located{ Section: section, Group: group, Type: jsonName(field), Index: index, Count: list.Len(), - Kind: tag.kind, Seam: target.Seam(seam), Backend: tag.backend, Provider: tag.provider, + Kind: tag.kind, Seam: target.Seam(seam), Backend: tag.backend, Provider: tag.provider, Preset: groupTag.preset, Title: clickyTag(field, "title"), Description: clickyTag(field, "desc"), Name: entry.EntryName(), Entry: entry, }) diff --git a/pkg/traces/builtin_clicky.go b/pkg/traces/builtin_clicky.go new file mode 100644 index 0000000..2ce970a --- /dev/null +++ b/pkg/traces/builtin_clicky.go @@ -0,0 +1,27 @@ +package traces + +import ( + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/entity" + "github.com/flanksource/telltale/pkg/tracing/target" + "github.com/flanksource/telltale/pkg/tracing/task" +) + +// The clicky kinds read the probes github.com/flanksource/clicky/telltale +// registers in a clicky process; telltale itself registers neither. +func init() { + MustRegister(Registration{ + Name: entity.Kind, Title: "Entity operations", Summary: "Record a clicky agent's entity operations", + Description: "Records the clicky entity operations (list, get, create, actions) an agent runs over the CLI, HTTP or MCP, with masked parameters and never their results.", + Examples: []Example{{Args: "--pid 1234 --entity widget --errors-only --duration 1m", Says: "record failed widget operations in process 1234"}}, + Seams: []target.Seam{target.Agent}, DefaultSeam: target.Agent, Armable: true, + New: func(KindDeps) tracing.TracePlugin { return entity.NewKind(nil) }, + }) + MustRegister(Registration{ + Name: task.Kind, Title: "Tasks", Summary: "Record a clicky agent's task transitions and progress", + Description: "Records the clicky tasks an agent already runs as it arms, then each status transition and throttled progress. Task logs and output are left to the logs and exec kinds.", + Examples: []Example{{Args: "--pid 1234 --duration 1m", Says: "record the tasks of process 1234"}}, + Seams: []target.Seam{target.Agent}, DefaultSeam: target.Agent, Armable: true, + New: func(KindDeps) tracing.TracePlugin { return task.NewKind(nil) }, + }) +} diff --git a/pkg/traces/pretty_records_test.go b/pkg/traces/pretty_records_test.go index 2bd411a..bd565c4 100644 --- a/pkg/traces/pretty_records_test.go +++ b/pkg/traces/pretty_records_test.go @@ -31,6 +31,8 @@ var _ = Describe("styled trace records", func() { {"sql_plancache", query.Row{"sql": "SELECT id FROM orders", "executions": 4, "avgElapsedMs": 12.0, "database": "checkout"}, []string{"SELECT id FROM orders", "4", "checkout"}}, {"sql_deadlock", query.Row{"database": "checkout", "victims": 1, "participants": 2, "victimStatement": "UPDATE orders SET total = 1"}, []string{"deadlock", "checkout", "UPDATE orders"}}, {"exec", query.Row{"name": "git", "args": []string{"status"}, "exitCode": 0}, []string{"git", "status"}}, + {"entity", query.Row{"entity": "widget", "verb": "update", "targetId": "w-1", "surface": "http", "durationMs": 12.0, "error": "update rejected"}, []string{"widget", "update", "w-1", "http", "update rejected"}}, + {"task", query.Row{"phase": "status", "name": "deploy api", "status": "running", "progress": 2, "maxValue": 5}, []string{"status", "deploy api", "running", "2/5"}}, {"terminal", query.Row{"kind": "r", "width": 120, "height": 40}, []string{"resize", "120", "40"}}, {"llm", query.Row{"phase": "response", "model": "example-model", "usage": map[string]any{"inputTokens": 12, "outputTokens": 3}, "cost": 0.004}, []string{"response", "example-model", "12", "3", "$0.004"}}, {"logs", query.Row{"severity": "error", "logger": "checkout", "message": "payment declined"}, []string{"ERROR", "checkout", "payment declined"}}, diff --git a/pkg/traces/read/processes.go b/pkg/traces/read/processes.go new file mode 100644 index 0000000..52f5017 --- /dev/null +++ b/pkg/traces/read/processes.go @@ -0,0 +1,36 @@ +package read + +import ( + "context" + + "github.com/flanksource/telltale/pkg/tracing/processcapture" +) + +type ProcessRow struct { + processcapture.ProcessRow + RunID string `json:"runId"` + Stream string `json:"stream"` +} + +type ProcessSnapshot struct { + Armed bool `json:"armed"` + Rows []ProcessRow `json:"rows"` +} + +func Processes(ctx context.Context, refs []Ref) (ProcessSnapshot, error) { + result := ProcessSnapshot{Rows: []ProcessRow{}} + for _, ref := range refs { + if ref.Kind != processcapture.Kind { + continue + } + result.Armed = true + rows, err := processcapture.ReadLatest(ctx, ref.Runtime, ref.TraceRef) + if err != nil { + return result, err + } + for _, row := range rows { + result.Rows = append(result.Rows, ProcessRow{ProcessRow: row, RunID: ref.RunID, Stream: ref.Stream}) + } + } + return result, nil +} diff --git a/pkg/traces/read/processes_test.go b/pkg/traces/read/processes_test.go new file mode 100644 index 0000000..d5cf79d --- /dev/null +++ b/pkg/traces/read/processes_test.go @@ -0,0 +1,36 @@ +package read_test + +import ( + "context" + "time" + + "github.com/flanksource/commons-db/recordstore/metrics" + "github.com/flanksource/telltale/pkg/traces" + "github.com/flanksource/telltale/pkg/traces/read" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/processcapture" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("process header reader", func() { + It("returns latest measurements for every process without the history page limit", func() { + host, err := traces.Open(traces.OpenOptions{DataDir: GinkgoT().TempDir(), RunID: "header"}) + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(func() { Expect(host.Close(context.Background())).To(Succeed()) }) + store, err := processcapture.NewStore(processcapture.StoreOptions{Backend: host.Runtime().Results.Backend, Stream: "process-header"}) + Expect(err).NotTo(HaveOccurred()) + at := time.Unix(100, 0).UTC() + for tick := int64(1); tick <= 501; tick++ { + Expect(store.Apply(context.Background(), processcapture.Observation{At: at.Add(time.Duration(tick) * time.Second), Tick: tick, + Processes: []processcapture.Identity{{Key: "7@start", PID: 7, Name: "worker", FirstObservedAt: at}}, + Metrics: []metrics.Sample{{Entity: "7@start", Values: map[string]any{"rssBytes": uint64(tick * 1024), "memoryPercent": 2.0, "cpuPercent": 12.5}}}, + })).To(Succeed()) + } + refs := []read.Ref{{RunID: "header", Runtime: host.Runtime(), TraceRef: tracing.TraceRef{Kind: "process", Stream: "process-header"}}} + snapshot, err := read.Processes(context.Background(), refs) + Expect(err).NotTo(HaveOccurred()) + Expect(snapshot.Armed).To(BeTrue()) + Expect(snapshot.Rows).To(HaveExactElements(And(HaveField("PID", 7), HaveField("RSSBytes", HaveValue(Equal(uint64(501*1024)))), HaveField("Stream", "process-header")))) + }) +}) diff --git a/pkg/traceserve/records/feed.go b/pkg/traceserve/records/feed.go index c5c278c..d453cdb 100644 --- a/pkg/traceserve/records/feed.go +++ b/pkg/traceserve/records/feed.go @@ -33,12 +33,16 @@ func FeedHandler(dataDir string) http.Handler { values := r.URL.Query() for key := range values { switch key { - case "kind", "stream", "limit", "sort", "cursor", "follow", "format", "resume", "from", "until": + case "kind", "excludeKind", "presentation", "stream", "limit", "sort", "cursor", "follow", "format", "resume", "from", "until": default: http.Error(w, "unknown feed parameter: "+key, http.StatusBadRequest) return } } + if presentation := values.Get("presentation"); presentation != "" && presentation != "ansi" { + http.Error(w, "unknown feed presentation", http.StatusBadRequest) + return + } q := read.FeedQuery{Sort: values.Get("sort"), Query: read.Query{Cursor: values.Get("cursor")}} if q.Sort != "" && q.Sort != "seq" && q.Sort != "timestamp" { http.Error(w, "invalid record sort", http.StatusBadRequest) @@ -85,7 +89,7 @@ func FeedHandler(dataDir string) http.Handler { return } w.Header().Set("Content-Type", "application/json") - if err := json.NewEncoder(w).Encode(page); err != nil { + if err := json.NewEncoder(w).Encode(presentFeedPage(page, values.Get("presentation"))); err != nil { panic(http.ErrAbortHandler) } }) @@ -97,8 +101,16 @@ func selectFeed(dataDir, id string) (*read.Selection, error) { func filterFeed(refs []read.Ref, r *http.Request) ([]read.Ref, error) { selected := []read.Ref{} + if excluded := r.URL.Query().Get("excludeKind"); excluded != "" && len(refs) > 0 { + if _, ok := refs[0].Runtime.Kinds.Get(excluded); !ok { + return nil, fmt.Errorf("unknown excluded capture kind %q", excluded) + } + } for _, ref := range refs { owner, _ := ref.Runtime.Kinds.ResultOf(ref.Kind) + if excluded := r.URL.Query().Get("excludeKind"); excluded != "" && (ref.Kind == excluded || owner == excluded) { + continue + } if kind := r.URL.Query().Get("kind"); kind != "" && ref.Kind != kind && owner != kind { continue } @@ -107,7 +119,7 @@ func filterFeed(refs []read.Ref, r *http.Request) ([]read.Ref, error) { } selected = append(selected, ref) } - if len(selected) == 0 && len(refs) != 0 { + if len(selected) == 0 && len(refs) != 0 && (r.URL.Query().Get("kind") != "" || r.URL.Query().Get("stream") != "") { return nil, fmt.Errorf("capture selection is not armed by this run") } return selected, nil @@ -161,7 +173,7 @@ func streamFeed(w http.ResponseWriter, r *http.Request, refs []read.Ref, q read. return } err := read.Feed(r.Context(), refs, q, func(record read.Record) error { - data, err := json.Marshal(record) + data, err := json.Marshal(presentFeedRecord(record, r.URL.Query().Get("presentation"))) if err != nil { return err } diff --git a/pkg/traceserve/records/handler_test.go b/pkg/traceserve/records/handler_test.go index 9e6f475..65b69d3 100644 --- a/pkg/traceserve/records/handler_test.go +++ b/pkg/traceserve/records/handler_test.go @@ -115,6 +115,24 @@ var _ = Describe("run records route", func() { Expect(json.Unmarshal(body, &result)).To(Succeed(), string(body)) return result } + It("adds styled presentation only when requested and permits excluding an unarmed kind", func() { + appendRows(1) + endpoint := server.URL + "/api/traces/run-http/records?excludeKind=process&presentation=ansi&limit=1" + response, err := server.Client().Get(endpoint) + Expect(err).NotTo(HaveOccurred()) + body, err := io.ReadAll(response.Body) + Expect(err).NotTo(HaveOccurred()) + Expect(response.Body.Close()).To(Succeed()) + Expect(response.StatusCode).To(Equal(http.StatusOK), string(body)) + var result struct { + Rows []struct { + ANSI string `json:"ansi"` + } `json:"rows"` + } + Expect(json.Unmarshal(body, &result)).To(Succeed()) + Expect(result.Rows).To(HaveLen(1)) + Expect(result.Rows[0].ANSI).To(ContainSubstring("worker")) + }) It("resumes a unified SSE feed after the last record without replaying it", func() { appendRows(1, 2) _, err := capture.Stop(context.Background()) diff --git a/pkg/traceserve/records/presentation.go b/pkg/traceserve/records/presentation.go new file mode 100644 index 0000000..06460db --- /dev/null +++ b/pkg/traceserve/records/presentation.go @@ -0,0 +1,29 @@ +package records + +import "github.com/flanksource/telltale/pkg/traces/read" + +type styledRecord struct { + read.Record + ANSI string `json:"ansi"` +} + +func presentFeedRecord(record read.Record, presentation string) any { + if presentation == "ansi" { + return styledRecord{Record: record, ANSI: record.Pretty().ANSI()} + } + return record +} + +func presentFeedPage(page read.FeedResult, presentation string) any { + if presentation != "ansi" { + return page + } + rows := make([]any, len(page.Rows)) + for i, row := range page.Rows { + rows[i] = presentFeedRecord(row, presentation) + } + return struct { + Rows []any `json:"rows"` + NextCursor string `json:"nextCursor"` + }{Rows: rows, NextCursor: page.NextCursor} +} diff --git a/pkg/traceserve/records/processes.go b/pkg/traceserve/records/processes.go new file mode 100644 index 0000000..4f4e4c8 --- /dev/null +++ b/pkg/traceserve/records/processes.go @@ -0,0 +1,36 @@ +package records + +import ( + "encoding/json" + "net/http" + + "github.com/flanksource/telltale/pkg/traces/read" +) + +func ProcessesHandler(dataDir string) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.RawQuery != "" { + http.Error(w, "process snapshot takes no query parameters", http.StatusBadRequest) + return + } + selected, err := selectFeed(dataDir, r.PathValue("run")) + if err != nil { + http.Error(w, err.Error(), http.StatusBadRequest) + return + } + defer func() { + if selected.Close() != nil { + panic(http.ErrAbortHandler) + } + }() + snapshot, err := read.Processes(r.Context(), selected.Refs) + if err != nil { + http.Error(w, err.Error(), http.StatusInternalServerError) + return + } + w.Header().Set("Content-Type", "application/json") + if json.NewEncoder(w).Encode(snapshot) != nil { + panic(http.ErrAbortHandler) + } + }) +} diff --git a/pkg/tracing/entity/entity.go b/pkg/tracing/entity/entity.go new file mode 100644 index 0000000..3ee59e7 --- /dev/null +++ b/pkg/tracing/entity/entity.go @@ -0,0 +1,100 @@ +// Package entity records the clicky entity operations an agent runs, armed +// on the entity probe github.com/flanksource/clicky/telltale registers. +package entity + +import ( + "encoding/json" + "fmt" + "iter" + "path/filepath" + "time" + + dbcontext "github.com/flanksource/commons-db/context" + "github.com/flanksource/commons-db/recordstore/recordresults" + "github.com/flanksource/telltale/pkg/agentclient" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/seam" + "github.com/flanksource/telltale/pkg/tracing/target" +) + +const Kind = "entity" + +// Options choose the operations a capture records. +type Options struct { + Entity string `json:"entity,omitempty" clicky:"desc=Entity name glob"` + Verb string `json:"verb,omitempty" clicky:"desc=Verb glob"` + ErrorsOnly bool `json:"errorsOnly,omitempty" clicky:"desc=Record failed operations only"` +} + +// Params are a capture's Options in the agent its target names. +type Params struct { + Target target.Target `json:"target,omitzero"` + Options +} + +// Validate is the static check of the entity and verb globs. +func (p Options) Validate() error { + for _, glob := range []string{p.Entity, p.Verb} { + if _, err := filepath.Match(glob, ""); err != nil { + return fmt.Errorf("glob %q: %w", glob, err) + } + } + return nil +} + +// Operation mirrors clicky/telltale's EntityRecord: one completed operation, +// with masked parameters and never its result. +type Operation struct { + tracing.Truncation + Entity string `json:"entity"` + Verb string `json:"verb"` + Surface string `json:"surface,omitempty"` + TargetID string `json:"targetId,omitempty"` + Admin bool `json:"admin,omitempty"` + ReadOnly *bool `json:"readOnly,omitempty"` + Parameters map[string]string `json:"parameters,omitempty"` + Args []string `json:"args,omitempty"` + StartedAt time.Time `json:"startedAt"` + DurationMs float64 `json:"durationMs"` + Error string `json:"error,omitempty"` + Resource map[string]string `json:"resource,omitempty"` +} + +type capture struct { + agent seam.AgentSeam[Params, Operation] +} + +func (c capture) AgentAvailable(probe string, t target.Target) (bool, error) { + return c.agent.Available(probe, t) +} +func (capture) Params() Params { return Params{} } +func (capture) Schema() recordresults.ResultType[Operation] { + return recordresults.ResultType[Operation]{Title: "Entity operations", TimeColumn: "startedAt", Follow: true} +} +func (c capture) Prepare(ctx dbcontext.Context, p Params, out tracing.Emitter[Operation]) (dbcontext.Context, func() error, error) { + return c.agent.Prepare(ctx, p, out) +} +func (c capture) Handle(ctx dbcontext.Context, p Params, out tracing.Emitter[Operation], _ tracing.Records[Operation]) error { + return c.agent.Handle(ctx, p, out) +} + +func (capture) Summarize(rows iter.Seq[Operation]) (map[string]any, error) { + count, failed, duration := 0, 0, 0.0 + entities := map[string]int{} + for row := range rows { + count++ + duration += row.DurationMs + entities[row.Entity]++ + if row.Error != "" { + failed++ + } + } + return map[string]any{"operations": count, "failures": failed, "durationMs": duration, "entities": entities}, nil +} + +// NewKind is the entity kind, armed only through an agent: telltale itself +// registers no entity probe. +func NewKind(registry *agentclient.Registry) *tracing.Handler[Params, Operation] { + agent := seam.AgentSeam[Params, Operation]{Probe: Kind, Registry: registry, Target: func(p Params) target.Target { return p.Target }, ArmParams: func(p Params) (json.RawMessage, error) { return json.Marshal(p) }} + return tracing.NewHandler[Params, Operation](capture{agent}, tracing.Capabilities{Live: true}, target.Agent).WithSecretMasking() +} diff --git a/pkg/tracing/entity/pretty.go b/pkg/tracing/entity/pretty.go new file mode 100644 index 0000000..80e8d98 --- /dev/null +++ b/pkg/tracing/entity/pretty.go @@ -0,0 +1,33 @@ +package entity + +import ( + "maps" + "slices" + "time" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +func (r Operation) Pretty() api.Text { + t := clicky.Text(r.Entity, "font-bold").Space().Append(r.Verb, "text-blue-500 font-bold") + if r.TargetID != "" { + t = t.Space().Append(r.TargetID) + } + if r.Surface != "" { + t = t.Space().Append(r.Surface, "text-muted") + } + t = t.Space().Add(api.Human(time.Duration(r.DurationMs*float64(time.Millisecond)), "text-muted")) + if r.Error != "" { + t = t.Space().Append(r.Error, "text-red-500") + } + return t +} + +func (r Operation) PrettyFull() api.Textable { + t := r.Pretty() + for _, key := range slices.Sorted(maps.Keys(r.Parameters)) { + t = t.NewLine().Append(key, "text-muted").Append(": ").Append(r.Parameters[key]) + } + return t +} diff --git a/pkg/tracing/processcapture/kind.go b/pkg/tracing/processcapture/kind.go index 9b1e2f7..779bf49 100644 --- a/pkg/tracing/processcapture/kind.go +++ b/pkg/tracing/processcapture/kind.go @@ -166,7 +166,7 @@ func (collector) Checkpoint(ctx dbcontext.Context, _ Params, _ tracing.Emitter[I func NewKind(sampler *process.Sampler, options KindOptions) *tracing.Handler[Params, Identity] { return tracing.NewHandler[Params, Identity](collector{sampler: sampler, options: options}, tracing.Capabilities{Live: true}, target.Process, target.Host).WithResults( tracing.NewResultTable("facets", recordresults.ResultType[FacetEvent]{Title: "Process facets", TimeColumn: "observedAt", Follow: true, Indexes: []recordstore.IndexDef{{Columns: []string{"process", "facet", "entity", "tick"}}}}), - tracing.NewResultTable("metrics", recordresults.ResultType[MetricRow]{Title: "Process metrics", TimeColumn: "observedAt", Dynamic: true, Follow: true, Indexes: []recordstore.IndexDef{{Columns: []string{"entity", "observedAt"}}}}), + tracing.NewResultTable("metrics", recordresults.ResultType[MetricRow]{Title: "Process metrics", TimeColumn: "observedAt", Dynamic: true, Follow: true, Indexes: []recordstore.IndexDef{{Columns: []string{"entity", "observedAt"}}}, Views: []recordresults.ResultView{latestMetricsView()}}), ) } diff --git a/pkg/tracing/processcapture/latest.go b/pkg/tracing/processcapture/latest.go new file mode 100644 index 0000000..4033c9e --- /dev/null +++ b/pkg/tracing/processcapture/latest.go @@ -0,0 +1,119 @@ +package processcapture + +import ( + "cmp" + "context" + "encoding/json" + "fmt" + "slices" + "time" + + dbcontext "github.com/flanksource/commons-db/context" + "github.com/flanksource/commons-db/query" + "github.com/flanksource/commons-db/query/profilestore" + "github.com/flanksource/commons-db/recordstore/recordresults" + "github.com/flanksource/telltale/pkg/tracing" +) + +type ProcessRow struct { + Key string `json:"key"` + PID int `json:"pid"` + Name string `json:"name"` + Command string `json:"command"` + ExitedAt *time.Time `json:"exitedAt,omitempty"` + SampledAt *time.Time `json:"sampledAt,omitempty"` + CPUPercent *float64 `json:"cpuPercent"` + RSSBytes *uint64 `json:"rssBytes"` + MemoryPercent *float64 `json:"memoryPercent"` +} + +func LatestProcesses(identities []Identity, metrics []MetricRow) ([]ProcessRow, error) { + rows := make([]ProcessRow, len(identities)) + index := map[string]int{} + ticks := map[string]int64{} + for i, p := range identities { + if p.Key == "" || p.PID <= 0 { + return nil, fmt.Errorf("process identity requires key and pid") + } + if _, exists := index[p.Key]; exists { + return nil, fmt.Errorf("duplicate process identity %s", p.Key) + } + index[p.Key] = i + rows[i] = ProcessRow{Key: p.Key, PID: p.PID, Name: p.Name, Command: p.Command, ExitedAt: p.ExitedAt} + } + for _, sample := range metrics { + i, ok := index[sample.Entity] + if !ok { + return nil, fmt.Errorf("metrics reference unknown process %q", sample.Entity) + } + row := &rows[i] + if row.SampledAt == nil || sample.Tick >= ticks[sample.Entity] { + row.SampledAt, row.CPUPercent, row.RSSBytes, row.MemoryPercent = &sample.At, sample.CPUPercent, &sample.RSSBytes, &sample.MemoryPercent + ticks[sample.Entity] = sample.Tick + } + } + slices.SortFunc(rows, func(a, b ProcessRow) int { + if compared := cmp.Compare(a.PID, b.PID); compared != 0 { + return compared + } + return cmp.Compare(a.Key, b.Key) + }) + return rows, nil +} + +func latestMetricsView() recordresults.ResultView { + return recordresults.ResultView{Name: "latest", Title: "Latest process measurements", + Query: `SELECT entity, observedAt, tick, cpuPercent, rssBytes, memoryPercent, MAX(seq) AS seq FROM stream_rows GROUP BY entity`, + Columns: []query.ColumnDef{ + {Name: "entity", Type: query.ColumnTypeString}, {Name: "observedAt", Type: query.ColumnTypeDateTime}, + {Name: "tick", Type: query.ColumnTypeNumber}, {Name: "cpuPercent", Type: query.ColumnTypeNumber}, + {Name: "rssBytes", Type: query.ColumnTypeNumber}, {Name: "memoryPercent", Type: query.ColumnTypeNumber}, {Name: "seq", Type: query.ColumnTypeNumber}, + }, Order: query.Order{{Column: "entity", Unique: true}}} +} + +func ReadLatest(ctx context.Context, runtime *tracing.Runtime, ref tracing.TraceRef) ([]ProcessRow, error) { + if ref.Kind != Kind { + return nil, fmt.Errorf("process snapshot requires a process capture") + } + meta, err := runtime.Results.Backend.Meta(ctx, ref.Stream+"-metrics") + if err != nil { + return nil, err + } + var identities []Identity + if err := tracing.ReadRecords(ctx, runtime, tracing.TraceRef{Kind: Kind, Stream: ref.Stream}, func(p Identity) error { + identities = append(identities, p) + return nil + }); err != nil { + return nil, err + } + if meta.HighSeq == 0 { + return LatestProcesses(identities, nil) + } + profile, err := runtime.Results.Registry.Get(ctx, "traces/"+MetricsTable+"/latest") + if err != nil { + return nil, err + } + params := (tracing.TraceRef{Kind: MetricsTable, Stream: ref.Stream + "-metrics", ToSeq: meta.HighSeq}).Params() + release, err := runtime.Results.Registry.BeforeExecute(ctx, []profilestore.ReadRequest{{Profile: profile, Params: params}}) + if err != nil { + return nil, err + } + defer release() + dbctx := dbcontext.NewContext(ctx).WithConnectionResolver(runtime.Results.Registry.ResolveConnection) + var metrics []MetricRow + for row, err := range query.Rows(query.ExecutePages(dbctx, profile, query.PageRequest{Limit: 500, Strategy: query.PagingCursor}, params)) { + if err != nil { + return nil, err + } + data, err := json.Marshal(row) + if err != nil { + return nil, err + } + var sample MetricRow + if err := json.Unmarshal(data, &sample); err != nil { + return nil, err + } + metrics = append(metrics, sample) + } + return LatestProcesses(identities, metrics) +} diff --git a/pkg/tracing/processcapture/latest_test.go b/pkg/tracing/processcapture/latest_test.go new file mode 100644 index 0000000..808023c --- /dev/null +++ b/pkg/tracing/processcapture/latest_test.go @@ -0,0 +1,32 @@ +package processcapture + +import ( + "time" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +var _ = Describe("latest process header", func() { + It("retains each identity and its last sample including exits and reused PIDs", func() { + at := time.Unix(100, 0).UTC() + exited := at.Add(time.Second) + cpu := 125.0 + rows, err := LatestProcesses([]Identity{ + {Key: "7@new", PID: 7, Name: "new worker"}, + {Key: "7@old", PID: 7, Name: "old worker", ExitedAt: &exited}, + }, []MetricRow{ + {Entity: "7@old", At: at, Tick: 1, RSSBytes: 1024, MemoryPercent: 2}, + {Entity: "7@old", At: exited, Tick: 2, CPUPercent: &cpu, RSSBytes: 2048, MemoryPercent: 4}, + }) + Expect(err).NotTo(HaveOccurred()) + Expect(rows).To(ConsistOf( + And(HaveField("Key", "7@old"), HaveField("ExitedAt", Equal(&exited)), HaveField("CPUPercent", Equal(&cpu)), HaveField("RSSBytes", HaveValue(Equal(uint64(2048))))), + And(HaveField("Key", "7@new"), HaveField("CPUPercent", BeNil()), HaveField("RSSBytes", BeNil())), + )) + }) + It("rejects measurements without their recorded identity", func() { + _, err := LatestProcesses(nil, []MetricRow{{Entity: "missing"}}) + Expect(err).To(MatchError(ContainSubstring("unknown process"))) + }) +}) diff --git a/pkg/tracing/task/pretty.go b/pkg/tracing/task/pretty.go new file mode 100644 index 0000000..da29424 --- /dev/null +++ b/pkg/tracing/task/pretty.go @@ -0,0 +1,32 @@ +package task + +import ( + "fmt" + + "github.com/flanksource/clicky" + "github.com/flanksource/clicky/api" +) + +var statusStyles = map[string]string{"success": "text-green-500", "failed": "text-red-500", "canceled": "text-yellow-500", "running": "text-blue-500"} + +func (r Snapshot) Pretty() api.Text { + t := clicky.Text(r.Phase, "text-muted").Space().Append(r.Name, "font-bold").Space().Append(r.Status, statusStyles[r.Status]+" font-bold") + if r.Group != "" { + t = t.Space().Append(r.Group, "text-muted") + } + if r.MaxValue > 0 { + t = t.Space().Append(fmt.Sprintf("%d/%d", r.Progress, r.MaxValue), "text-blue-500") + } + if r.Error != "" { + t = t.Space().Append(r.Error, "text-red-500") + } + return t +} + +func (r Snapshot) PrettyFull() api.Textable { + t := r.Pretty() + if r.Message != "" { + t = t.NewLine().Append(r.Message, "text-muted") + } + return t +} diff --git a/pkg/tracing/task/task.go b/pkg/tracing/task/task.go new file mode 100644 index 0000000..15c5c52 --- /dev/null +++ b/pkg/tracing/task/task.go @@ -0,0 +1,95 @@ +// Package task records the clicky tasks an agent runs, armed on the task +// probe github.com/flanksource/clicky/telltale registers. +package task + +import ( + "encoding/json" + "errors" + "fmt" + "iter" + "path/filepath" + + clickytask "github.com/flanksource/clicky/task" + dbcontext "github.com/flanksource/commons-db/context" + "github.com/flanksource/commons-db/recordstore/recordresults" + "github.com/flanksource/telltale/pkg/agentclient" + "github.com/flanksource/telltale/pkg/tracing" + "github.com/flanksource/telltale/pkg/tracing/seam" + "github.com/flanksource/telltale/pkg/tracing/target" +) + +const Kind = "task" + +// Options choose the tasks a capture records and how often it keeps progress. +type Options struct { + Name string `json:"name,omitempty" clicky:"desc=Task name glob"` + Group string `json:"group,omitempty" clicky:"desc=Parent group name glob"` + ProgressIntervalMs int `json:"progressIntervalMs,omitempty" clicky:"desc=Minimum milliseconds between progress records of a task; 0 takes the agent's default"` +} + +// Params are a capture's Options in the agent its target names. +type Params struct { + Target target.Target `json:"target,omitzero"` + Options +} + +// Validate is the static check of the globs and the progress interval. +func (p Options) Validate() error { + for _, glob := range []string{p.Name, p.Group} { + if _, err := filepath.Match(glob, ""); err != nil { + return fmt.Errorf("glob %q: %w", glob, err) + } + } + if p.ProgressIntervalMs < 0 { + return errors.New("progressIntervalMs must not be negative") + } + return nil +} + +// Snapshot mirrors clicky/telltale's TaskRecord: a task at a status +// transition, a throttled progress update, or (phase baseline) a task already +// present when the capture armed. It carries no logs or output. +type Snapshot struct { + tracing.Truncation + Phase string `json:"phase"` + clickytask.TaskSnapshot + Resource map[string]string `json:"resource,omitempty"` +} + +type capture struct { + agent seam.AgentSeam[Params, Snapshot] +} + +func (c capture) AgentAvailable(probe string, t target.Target) (bool, error) { + return c.agent.Available(probe, t) +} +func (capture) Params() Params { return Params{} } +func (capture) Schema() recordresults.ResultType[Snapshot] { + return recordresults.ResultType[Snapshot]{Title: "Tasks", Follow: true} +} +func (c capture) Prepare(ctx dbcontext.Context, p Params, out tracing.Emitter[Snapshot]) (dbcontext.Context, func() error, error) { + return c.agent.Prepare(ctx, p, out) +} +func (c capture) Handle(ctx dbcontext.Context, p Params, out tracing.Emitter[Snapshot], _ tracing.Records[Snapshot]) error { + return c.agent.Handle(ctx, p, out) +} + +// Summarize counts the tasks seen and each one's last status. +func (capture) Summarize(rows iter.Seq[Snapshot]) (map[string]any, error) { + last := map[string]string{} + for row := range rows { + last[row.ID] = row.Status + } + statuses := map[string]int{} + for _, status := range last { + statuses[status]++ + } + return map[string]any{"tasks": len(last), "statuses": statuses}, nil +} + +// NewKind is the task kind, armed only through an agent: telltale itself +// registers no task probe. +func NewKind(registry *agentclient.Registry) *tracing.Handler[Params, Snapshot] { + agent := seam.AgentSeam[Params, Snapshot]{Probe: Kind, Registry: registry, Target: func(p Params) target.Target { return p.Target }, ArmParams: func(p Params) (json.RawMessage, error) { return json.Marshal(p) }} + return tracing.NewHandler[Params, Snapshot](capture{agent}, tracing.Capabilities{Live: true}, target.Agent).WithSecretMasking() +} From 6f0a35f6d5f4d1af7a16245deec8651d4617b007 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Sun, 8 Nov 2026 22:48:17 +0200 Subject: [PATCH 13/89] feat(fe): Add combined activity overview and rework run detail into tabs The landing page now lists OpenTelemetry traces and recorded runs together, newest first, with the type, text, source and window filters kept in the URL so a filtered view can be linked and restored. Opening a run from the overview keeps the shell chrome: navigation, header and action areas are portalled into AppShell slots so a run renders full width without duplicating page headings. Run detail is split into events, tasks and process details tabs; clicky task captures render through the clicky-ui task viewer, and process facets, stack collection and Go profiles stay available. The events feed drops process records and renders ANSI, so process data is no longer duplicated outside its own tab. BREAKING CHANGE: the root page no longer shows the backend connection panel, the embedded trace run list or the OpenAPI link; that content is replaced by the new activity overview. --- webapp/src/App.tsx | 30 ++++-- webapp/src/layout/RunShellSlot.tsx | 11 ++ webapp/src/layout/run-shell.ts | 10 ++ webapp/src/overview/OverviewPage.test.tsx | 123 ++++++++++++++++++++++ webapp/src/overview/OverviewPage.tsx | 99 +++++++++++++++++ webapp/src/overview/activity.ts | 45 ++++++++ webapp/src/overview/state.ts | 37 +++++++ webapp/src/routes.test.tsx | 34 +++++- webapp/src/routes.tsx | 23 +--- webapp/src/traces/RunProcessDetail.tsx | 31 ++++++ webapp/src/traces/RunProcesses.tsx | 107 ------------------- webapp/src/traces/RunTasks.test.tsx | 43 ++++++++ webapp/src/traces/RunTasks.tsx | 53 ++++++++++ webapp/src/traces/TracesPage.test.tsx | 17 +-- webapp/src/traces/TracesPage.tsx | 65 ++---------- webapp/src/traces/TracesPanel.test.tsx | 79 ++++++++++++++ webapp/src/traces/TracesPanel.tsx | 106 +++++++++++++++++-- webapp/src/traces/feed.ts | 4 +- webapp/src/traces/taskSnapshots.test.tsx | 35 ++++++ webapp/src/traces/taskSnapshots.ts | 73 +++++++++++++ 20 files changed, 813 insertions(+), 212 deletions(-) create mode 100644 webapp/src/layout/RunShellSlot.tsx create mode 100644 webapp/src/layout/run-shell.ts create mode 100644 webapp/src/overview/OverviewPage.test.tsx create mode 100644 webapp/src/overview/OverviewPage.tsx create mode 100644 webapp/src/overview/activity.ts create mode 100644 webapp/src/overview/state.ts create mode 100644 webapp/src/traces/RunProcessDetail.tsx delete mode 100644 webapp/src/traces/RunProcesses.tsx create mode 100644 webapp/src/traces/RunTasks.test.tsx create mode 100644 webapp/src/traces/RunTasks.tsx create mode 100644 webapp/src/traces/TracesPanel.test.tsx create mode 100644 webapp/src/traces/taskSnapshots.test.tsx create mode 100644 webapp/src/traces/taskSnapshots.ts diff --git a/webapp/src/App.tsx b/webapp/src/App.tsx index 634a0ce..e24fb98 100644 --- a/webapp/src/App.tsx +++ b/webapp/src/App.tsx @@ -1,22 +1,34 @@ +import { useMemo, useState } from "react"; import { AppShell, Button } from "@flanksource/clicky-ui/components"; import { useTheme } from "@flanksource/clicky-ui/hooks"; import { RouterProvider, useBrowserRouter, useRouter } from "@flanksource/clicky-ui/rpc"; import { AppRoutes, matchRoute } from "./routes"; import { CommandSearch } from "./search/CommandSearch"; import TracesPage from "./traces/TracesPage"; +import { RunShellContext } from "./layout/run-shell"; function Shell() { const { resolvedTheme, setTheme } = useTheme(); const { pathname } = useRouter(); const page = matchRoute(pathname).page; - if (new URLSearchParams(window.location.search).get("viewer") === "1") return ; - return ( + const params = new URLSearchParams(window.location.search); + const viewer = params.get("viewer") === "1"; + const framed = viewer || (page === "overview" && !!params.get("run")); + const [nav, setNav] = useState(null); + const [header, setHeader] = useState(null); + const [actions, setActions] = useState(null); + const targets = useMemo(() => framed ? { nav, header, actions } : null, [framed, nav, header, actions]); + return Telltale} - nav={page === "otel" ?

    OpenTelemetry traces

    : undefined} - contentWidth="contained" - search={} - navSections={[{ + nav={framed ?
    : page === "otel" ?

    OpenTelemetry traces

    : undefined} + contentWidth={framed ? "full" : "contained"} + contentClassName={framed ? "flex min-h-0 flex-col overflow-hidden" : ""} + bodyHeader={framed ?
    : undefined} + bodyActions={framed ?
    : undefined} + bodyHeaderClassName={framed ? "[&>[data-slot=app-shell-body-header-content]]:flex-col [&>[data-slot=app-shell-body-header-content]]:items-stretch" : ""} + search={viewer ? undefined : } + navSections={viewer ? [] : [{ items: [ { key: "overview", label: "Overview", to: "/", active: page === "overview" }, { key: "definitions", label: "Definitions", to: "/definitions", active: page === "definitions" }, @@ -30,11 +42,11 @@ function Shell() { }]} actions={} > -
    - +
    + {viewer ? : }
    - ); + ; } export default function App() { diff --git a/webapp/src/layout/RunShellSlot.tsx b/webapp/src/layout/RunShellSlot.tsx new file mode 100644 index 0000000..14a1386 --- /dev/null +++ b/webapp/src/layout/RunShellSlot.tsx @@ -0,0 +1,11 @@ +import type { ReactNode } from "react"; +import { createPortal } from "react-dom"; +import { useRunShell, type RunShellTargets } from "./run-shell"; + +/** Standalone views render inline; an AppShell host owns their slot containers. */ +export function RunShellSlot({ name, children }: { name: keyof RunShellTargets; children: ReactNode }) { + const targets = useRunShell(); + if (!targets) return children; + const container = targets[name]; + return container ? createPortal(children, container) : null; +} diff --git a/webapp/src/layout/run-shell.ts b/webapp/src/layout/run-shell.ts new file mode 100644 index 0000000..75266ec --- /dev/null +++ b/webapp/src/layout/run-shell.ts @@ -0,0 +1,10 @@ +import { createContext, useContext } from "react"; + +export interface RunShellTargets { + nav: HTMLElement | null; + header: HTMLElement | null; + actions: HTMLElement | null; +} + +export const RunShellContext = createContext(null); +export const useRunShell = () => useContext(RunShellContext); diff --git a/webapp/src/overview/OverviewPage.test.tsx b/webapp/src/overview/OverviewPage.test.tsx new file mode 100644 index 0000000..b6a34c6 --- /dev/null +++ b/webapp/src/overview/OverviewPage.test.tsx @@ -0,0 +1,123 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { act, fireEvent, render, screen, waitFor } from "@testing-library/react"; +import { RouterProvider, useBrowserRouter } from "@flanksource/clicky-ui/rpc"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import OverviewPage from "./OverviewPage"; +import type { RunTraces } from "../traces/api"; + +const run: RunTraces = { + runId: "recorded-build", mount: "/api/traces/recorded-build", dir: "/recorded-build", status: "succeeded", + command: ["make", "build"], startedAt: "2026-11-08T12:00:00Z", endedAt: "2026-11-08T12:00:03Z", exitCode: 0, + captures: [{ kind: "http", ref: { kind: "http", stream: "proxy" } }], +}; +const trace = { + traceId: "checkout-trace", service: "checkout", operation: "POST /orders", startedAt: "2026-11-08T12:00:01Z", + durationMs: 125, spanCount: 4, errors: 1, services: ["checkout", "payments"], +}; + +function serve({ traceError = false, empty = false } = {}) { + const fetchMock = vi.fn(async (url: string) => { + if (url === "/health") return Response.json({ status: "healthy", version: "test" }); + if (url === "/api/otel/form") return Response.json({ schema: {}, defaults: { source: "records", lookback: "1h", minSpans: 2, limit: 100 } }); + if (url === "/api/otel/sources") return Response.json([{ id: "records", name: "Recorded traces", type: "records" }, { id: "remote", name: "Remote telemetry", type: "tempo" }]); + if (url.startsWith("/api/otel?")) return traceError + ? new Response("Trace source unavailable", { status: 503 }) + : Response.json({ traces: empty ? [] : [trace], total: empty ? 0 : 1, services: [], rootOperations: [], attributes: [] }); + if (url === "/api/traces") return Response.json({ runs: empty ? [] : [run, { ...run, runId: "receiver", standing: true, status: "running" }] }); + if (url.endsWith("/processes")) return Response.json({ armed: false, rows: [] }); + if (url.includes("/records?")) return Response.json({ rows: [], nextCursor: "" }); + if (url === "/api/traces/start") return Response.json({ schema: { type: "object", required: ["command"], properties: { command: { type: "string", title: "Command" } } }, defaults: { command: "" } }); + if (url === "/api/traces/definitions") return Response.json([]); + return new Response(`Unexpected request: ${url}`, { status: 404 }); + }); + vi.stubGlobal("fetch", fetchMock); + return fetchMock; +} + +function renderPage() { + function Harness() { + const router = useBrowserRouter(); + return ; + } + return render(); +} + +beforeEach(() => window.history.replaceState(null, "", "/")); +afterEach(() => vi.unstubAllGlobals()); + +describe("overview activity", () => { + it("interleaves OpenTelemetry traces and recorded runs newest first with their own detail links", async () => { + serve(); + renderPage(); + await screen.findByText("POST /orders"); + const rows = screen.getAllByRole("row").slice(1); + expect(rows).toHaveLength(2); + expect(rows[0]).toHaveTextContent("POST /orders"); + expect(rows[0]).toHaveTextContent("OpenTelemetry"); + expect(rows[1]).toHaveTextContent("make build"); + expect(rows[1]).toHaveTextContent("Recorded run"); + const links = screen.getAllByRole("link").map(link => link.getAttribute("href")); + expect(links).toContain("/otel/checkout-trace?source=records&lookback=1h&minSpans=2&limit=100"); + expect(links).toContain("/?run=recorded-build"); + expect(screen.queryByText("receiver")).not.toBeInTheDocument(); + }); + + it("persists type and text filters and restores them on navigation without hiding the controls", async () => { + serve(); + renderPage(); + await screen.findByText("POST /orders"); + fireEvent.click(screen.getByRole("tab", { name: /Recorded runs/ })); + fireEvent.change(screen.getByRole("searchbox", { name: "Filter activity" }), { target: { value: "build" } }); + expect(screen.getAllByRole("link").some(link => link.getAttribute("href") === "/?activity=run&activityQ=build&run=recorded-build")).toBe(true); + fireEvent.change(screen.getByRole("searchbox", { name: "Filter activity" }), { target: { value: "missing" } }); + expect(await screen.findByText("No activity matches these filters.")).toBeInTheDocument(); + expect(new URLSearchParams(window.location.search).get("activity")).toBe("run"); + expect(new URLSearchParams(window.location.search).get("activityQ")).toBe("missing"); + act(() => { + window.history.pushState(null, "", "/?activity=otel&activityQ=checkout"); + window.dispatchEvent(new PopStateEvent("popstate")); + }); + expect(await screen.findByText("POST /orders")).toBeInTheDocument(); + expect(screen.queryByText("make build")).not.toBeInTheDocument(); + expect(screen.getByRole("searchbox", { name: "Filter activity" })).toHaveValue("checkout"); + }); + + it("passes the selected telemetry source and window to search and detail links", async () => { + const fetchMock = serve(); + renderPage(); + await screen.findByText("POST /orders"); + fireEvent.change(screen.getByRole("combobox", { name: "Trace source" }), { target: { value: "remote" } }); + fireEvent.change(screen.getByRole("combobox", { name: "Trace window" }), { target: { value: "24h" } }); + await waitFor(() => expect(fetchMock.mock.calls.some(([url]) => url.startsWith("/api/otel?") && new URL(url, window.location.origin).searchParams.get("source") === "remote" && new URL(url, window.location.origin).searchParams.get("lookback") === "24h")).toBe(true)); + await waitFor(() => expect(screen.getAllByRole("link").some(link => link.getAttribute("href")?.includes("/otel/checkout-trace?source=remote&lookback=24h"))).toBe(true)); + }); + + it("shows recorded runs and an explicit retry when telemetry fails", async () => { + serve({ traceError: true }); + renderPage(); + expect(await screen.findByRole("alert")).toHaveTextContent("Trace source unavailable"); + expect(await screen.findByText("make build")).toBeInTheDocument(); + expect(screen.getByRole("button", { name: "Retry OpenTelemetry" })).toBeInTheDocument(); + }); + + it("opens the existing run view from a deep link and returns to the overview", async () => { + window.history.replaceState(null, "", "/?run=recorded-build&activity=run"); + serve(); + renderPage(); + expect(await screen.findByText(/exited with code 0/)).toBeInTheDocument(); + expect(screen.getByRole("link", { name: "Back to overview" })).toHaveAttribute("href", "/?activity=run"); + expect(screen.queryByRole("table")).not.toBeInTheDocument(); + fireEvent.click(screen.getByRole("link", { name: "Back to overview" })); + expect(await screen.findByRole("tab", { name: "Recorded runs" })).toHaveAttribute("aria-selected", "true"); + expect(await screen.findByText("make build")).toBeInTheDocument(); + }); + + it("keeps filters and the record action available when there is no activity", async () => { + serve({ empty: true }); + renderPage(); + expect(await screen.findByText("No traces or recorded runs yet.")).toBeInTheDocument(); + expect(screen.getByRole("searchbox", { name: "Filter activity" })).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Record a run" })); + expect(await screen.findByRole("textbox", { name: /Command/ })).toBeInTheDocument(); + }); +}); diff --git a/webapp/src/overview/OverviewPage.tsx b/webapp/src/overview/OverviewPage.tsx new file mode 100644 index 0000000..aeea133 --- /dev/null +++ b/webapp/src/overview/OverviewPage.tsx @@ -0,0 +1,99 @@ +import { useMemo, useState } from "react"; +import { useQuery, useQueryClient } from "@tanstack/react-query"; +import { Button, Panel, Tabs } from "@flanksource/clicky-ui/components"; +import { Badge, DataTable, type DataTableColumn } from "@flanksource/clicky-ui/data"; +import { formatDuration } from "@flanksource/clicky-ui/utils"; +import { useRouter } from "@flanksource/clicky-ui/rpc"; +import { fetchForm, fetchSources, fetchTraces, searchParams } from "../otel/api"; +import { fetchTraceRuns } from "../traces/api"; +import { RunDetail } from "../traces/TracesPage"; +import { StartRunForm } from "../traces/StartRunForm"; +import { activityRows, type ActivityRow } from "./activity"; +import { useOverviewState } from "./state"; +import { RunShellSlot } from "../layout/RunShellSlot"; + +const inputClass = "min-w-0 rounded border border-border bg-background px-2 py-1 text-sm"; + +function ActivityTable({ rows, loading, filtered }: { rows: ActivityRow[]; loading: boolean; filtered: boolean }) { + const { navigate } = useRouter(); + const columns: DataTableColumn[] = [ + { key: "kind", label: "Type", render: (_, row) => {row.kind === "otel" ? "OpenTelemetry" : "Recorded run"} }, + { key: "title", label: "Trace / run", grow: true, minWidth: 240, render: (_, row) =>
    + {row.title}{row.detail} +
    }, + { key: "status", label: "Status", render: (_, row) => {row.status} }, + { key: "startedAt", label: "Started", render: (_, row) => row.startedAt ? : Not recorded }, + { key: "durationMs", label: "Duration", align: "right", render: (_, row) => {row.durationMs === null ? "—" : formatDuration(row.durationMs)} }, + { key: "contents", label: "Contents", minWidth: 180, render: (_, row) =>
    {row.contents.map(content => {content})}
    }, + ]; + return
    + row.id} + getRowHref={row => row.href} onRowClick={row => navigate(row.href)} loading={loading} showFullscreenControl={false} + emptyMessage={filtered ? "No activity matches these filters." : "No traces or recorded runs yet."} /> +
    ; +} + +export default function OverviewPage() { + const { renderLink } = useRouter(); + const client = useQueryClient(); + const [state, setState, activitySearch] = useOverviewState(); + const [recording, setRecording] = useState(false); + const wantsTraces = !state.run && state.activity !== "run"; + const runs = useQuery({ queryKey: ["trace-runs", {}], queryFn: () => fetchTraceRuns(), retry: false, + refetchInterval: query => query.state.status === "error" ? false : query.state.data?.runs.some(run => run.status === "running" && !run.standing) ? 1000 : 5000 }); + const form = useQuery({ queryKey: ["otel-form"], queryFn: fetchForm, retry: false, staleTime: Infinity, enabled: wantsTraces }); + const sources = useQuery({ queryKey: ["otel-sources"], queryFn: fetchSources, retry: false, enabled: wantsTraces }); + const values = useMemo(() => ({ ...form.data?.defaults, ...(state.otelSource ? { source: state.otelSource } : {}), ...(state.otelWindow ? { lookback: state.otelWindow } : {}) }), [form.data, state.otelSource, state.otelWindow]); + const traces = useQuery({ queryKey: ["overview-traces", values], queryFn: ({ signal }) => fetchTraces(values, signal), retry: false, + enabled: wantsTraces && !!form.data && !!sources.data, refetchInterval: query => wantsTraces && query.state.status !== "error" ? 5000 : false }); + const rows = useMemo(() => activityRows({ runs: runs.data?.runs ?? [], traces: wantsTraces ? traces.data?.traces ?? [] : [], values, search: activitySearch }), [runs.data, traces.data, wantsTraces, values, activitySearch]); + const visible = rows.filter(row => (state.activity === "all" || state.activity === row.kind) && `${row.title} ${row.detail} ${row.status} ${row.contents.join(" ")}`.toLowerCase().includes(state.activityQ.trim().toLowerCase())); + const telemetryError = form.error ?? sources.error ?? traces.error; + const params = new URLSearchParams(activitySearch); + for (const key of ["run", "feedKind", "feedSort", "feedView", "showExited", "runView"]) params.delete(key); + const back = `/${params.size ? `?${params}` : ""}${window.location.hash}`; + if (state.run) { + const run = runs.data?.runs.find(candidate => candidate.runId === state.run); + return
    +
    + {renderLink({ to: back, className: "shrink-0 text-sm text-primary underline", children: "Back to overview" })} +

    Recorded trace run

    +
    + {runs.isPending &&

    Loading trace run…

    } + {runs.error &&

    {runs.error.message}

    } + {runs.data && !run &&

    Run {state.run} is not available.

    } + {run && } +
    ; + } + return
    +
    +

    Overview

    OpenTelemetry traces and recorded trace runs.

    +
    + {renderLink({ to: `/otel?${searchParams(values)}`, className: "text-sm text-primary underline", children: "Search traces" })} + +
    +
    + {recording && { void client.invalidateQueries({ queryKey: ["trace-runs"] }); setRecording(false); setState({ run: run.runId }); }} />} + setState({ activity })} /> +
    + + {wantsTraces && <> + + + } + +
    + {wantsTraces && telemetryError &&
    +

    OpenTelemetry: {telemetryError.message}

    + +
    } + {runs.error &&

    Recorded runs: {runs.error.message}

    } + {!["all", "otel", "run"].includes(state.activity) &&

    Unknown activity type: {state.activity}. Select a tab to reset it.

    } +

    {wantsTraces && traces.data ? `${traces.data.traces.length} of ${traces.data.total} OpenTelemetry traces in the selected window${values.minSpans && values.minSpans > 1 ? ` with at least ${values.minSpans} spans` : ""} · ` : ""}{runs.data ? `${runs.data.runs.filter(run => !run.standing).length} recorded ${runs.data.runs.filter(run => !run.standing).length === 1 ? "run" : "runs"}` : "Loading recorded runs…"} · Newest first

    + +
    ; +} diff --git a/webapp/src/overview/activity.ts b/webapp/src/overview/activity.ts new file mode 100644 index 0000000..76457ee --- /dev/null +++ b/webapp/src/overview/activity.ts @@ -0,0 +1,45 @@ +import type { OtelSummary, OtelSearchValues } from "@flanksource/clicky-ui/data"; +import { searchParams } from "../otel/api"; +import type { RunTraces } from "../traces/api"; + +export type ActivityRow = { + id: string; + kind: "otel" | "run"; + title: string; + detail: string; + status: string; + startedAt?: string; + durationMs: number | null; + contents: string[]; + href: string; +}; + +function started(row: ActivityRow) { + if (!row.startedAt) return -Infinity; + const time = Date.parse(row.startedAt); + if (!Number.isFinite(time)) throw new Error(`Invalid activity start time for ${row.id}: ${row.startedAt}`); + return time; +} + +export function activityRows({ runs, traces, values, search }: { runs: RunTraces[]; traces: OtelSummary[]; values: OtelSearchValues; search: string }): ActivityRow[] { + const rows: ActivityRow[] = runs.filter(run => !run.standing).map(run => { + const params = new URLSearchParams(search); + params.set("run", run.runId); + return { + id: `run:${run.runId}`, kind: "run", title: run.command?.length ? run.command.join(" ") : run.pid ? `pid ${run.pid}` : "Host run", + detail: run.runId, status: run.status, + ...(run.startedAt ? { startedAt: run.startedAt } : {}), + durationMs: run.startedAt && run.endedAt ? Date.parse(run.endedAt) - Date.parse(run.startedAt) : null, + contents: [...new Set([...(run.captures ?? []).map(capture => capture.kind), ...(run.process ? ["process"] : [])])], + href: `/?${params}`, + }; + }); + for (const trace of traces) rows.push({ + id: `otel:${values.source}/${values.run ?? ""}/${trace.traceId}`, kind: "otel", title: trace.operation, + detail: `${trace.service} · ${trace.traceId}`, status: trace.errors > 0 ? `${trace.errors} ${trace.errors === 1 ? "error" : "errors"}` : "ok", + startedAt: trace.startedAt, durationMs: trace.durationMs, + contents: [`${trace.spanCount} spans`, ...trace.services], + href: `/otel/${encodeURIComponent(trace.traceId)}?${searchParams(values)}`, + }); + return rows.sort((a, b) => started(b) - started(a) || a.id.localeCompare(b.id)); +} diff --git a/webapp/src/overview/state.ts b/webapp/src/overview/state.ts new file mode 100644 index 0000000..ab9d608 --- /dev/null +++ b/webapp/src/overview/state.ts @@ -0,0 +1,37 @@ +import { useEffect, useState } from "react"; + +interface OverviewState { + activity: string; + activityQ: string; + otelSource: string; + otelWindow: string; + run: string; +} + +const KEYS = ["activity", "activityQ", "otelSource", "otelWindow", "run"] as const; + +function readState(): OverviewState { + const params = new URLSearchParams(window.location.search); + return { + activity: params.get("activity") ?? "all", activityQ: params.get("activityQ") ?? "", + otelSource: params.get("otelSource") ?? "", otelWindow: params.get("otelWindow") ?? "", run: params.get("run") ?? "", + }; +} + +export function useOverviewState() { + const [state, setState] = useState(readState); + useEffect(() => { + const restore = () => setState(readState()); + window.addEventListener("popstate", restore); + return () => window.removeEventListener("popstate", restore); + }, []); + const params = new URLSearchParams(window.location.search); + for (const key of KEYS) { + if (state[key] && !(key === "activity" && state[key] === "all")) params.set(key, state[key]); else params.delete(key); + } + const search = params.toString(); + useEffect(() => { + window.history.replaceState(null, "", `${window.location.pathname}${search ? `?${search}` : ""}${window.location.hash}`); + }, [search]); + return [state, (next: Partial) => setState(previous => ({ ...previous, ...next })), search] as const; +} diff --git a/webapp/src/routes.test.tsx b/webapp/src/routes.test.tsx index c2af745..0886743 100644 --- a/webapp/src/routes.test.tsx +++ b/webapp/src/routes.test.tsx @@ -11,7 +11,7 @@ afterEach(() => vi.unstubAllGlobals()); // The pages load lazily; load them once up front so no test waits on the first import. beforeAll(async () => { - await Promise.all([import("./Status"), import("./top/TopPage"), import("./top/ProcessPage"), import("./traces/TracesPage")]); + await Promise.all([import("./overview/OverviewPage"), import("./top/TopPage"), import("./top/ProcessPage"), import("./traces/TracesPage")]); }, 30000); describe("matchRoute", () => { @@ -47,6 +47,9 @@ function serve() { if (url.startsWith("/api/top/facets")) return Promise.resolve(new Response("pid 123: not listed at the latest tick", { status: 404 })); if (url.startsWith("/api/top")) return Promise.resolve(json(sampleFrame())); if (url === "/health") return Promise.resolve(json({ status: "healthy", version: "test" })); + if (url === "/api/otel/form") return Promise.resolve(json({ schema: {}, defaults: { source: "records", lookback: "1h", limit: 100, minSpans: 2 } })); + if (url === "/api/otel/sources") return Promise.resolve(json([{ id: "records", name: "Recorded traces", type: "records" }])); + if (url.startsWith("/api/otel?")) return Promise.resolve(json({ traces: [], total: 0, services: [], rootOperations: [], attributes: [] })); if (url === "/api/traces/definitions") return Promise.resolve(json([])); if (url.startsWith("/api/traces")) return Promise.resolve(json({ runs: [] })); return Promise.resolve(new Response("", { status: 404 })); @@ -87,11 +90,12 @@ describe("AppRoutes", () => { expect(await screen.findByRole("row", { name: /^claude/ })).toBeInTheDocument(); }); - it("renders the status and trace runs at /", async () => { + it("brings OpenTelemetry traces and recorded runs together at /", async () => { serve(); renderAt("/"); - expect(await screen.findByText("Backend connection")).toBeInTheDocument(); - expect(await screen.findByText("Trace runs")).toBeInTheDocument(); + expect(await screen.findByRole("heading", { name: "Overview" })).toBeInTheDocument(); + expect(screen.getByRole("tab", { name: "OpenTelemetry traces" })).toBeInTheDocument(); + expect(screen.getByRole("tab", { name: "Recorded runs" })).toBeInTheDocument(); expect(screen.queryByText("Process groups")).not.toBeInTheDocument(); }); @@ -113,6 +117,26 @@ describe("AppRoutes", () => { }); describe("App", () => { + it("places a recorded run's navigation and controls in the AppShell slots", async () => { + window.history.replaceState(null, "", "/?run=recorded-build"); + const fetchMock = serve(); + const fallback = fetchMock.getMockImplementation()!; + fetchMock.mockImplementation((url: string) => { + if (url === "/api/traces") return Promise.resolve(json({ runs: [{ runId: "recorded-build", mount: "/api/traces/recorded-build", dir: "/recorded-build", status: "succeeded", command: ["make", "build"], exitCode: 0, captures: [] }] })); + if (url.endsWith("/processes")) return Promise.resolve(json({ armed: true, rows: [] })); + if (url.includes("/records?")) return Promise.resolve(json({ rows: [], nextCursor: "" })); + return fallback(url); + }); + render(); + const navigation = await screen.findByRole("heading", { name: "Recorded trace run" }); + expect(navigation.closest('[data-slot="app-shell-nav"]')).not.toBeNull(); + expect(screen.getByRole("link", { name: "Back to overview" }).closest("header")).not.toBeNull(); + const usage = await screen.findByRole("region", { name: "Process usage" }); + expect(usage.closest('[data-slot="app-shell-body-header"]')).not.toBeNull(); + expect(screen.getByText(/exited with code 0/).closest('[data-slot="app-shell-body-actions"]')).not.toBeNull(); + expect(screen.getByRole("main").querySelector("h1")).toBeNull(); + }); + it.each(["/otel", "/otel/73748978474d62e1e4f6e744a3c5f605"])("shows the trace title in the AppShell navbar at %s", async pathname => { window.history.replaceState(null, "", pathname); serve(); @@ -136,6 +160,6 @@ describe("App", () => { expect(screen.getAllByRole("link", { name: "Overview" })[0]).not.toHaveClass("bg-sidebar-accent"); fireEvent.click(screen.getAllByRole("link", { name: "Overview" })[0]!); expect(window.location.pathname).toBe("/"); - expect(await screen.findByText("Backend connection")).toBeInTheDocument(); + expect(await screen.findByRole("heading", { name: "Overview" })).toBeInTheDocument(); }); }); diff --git a/webapp/src/routes.tsx b/webapp/src/routes.tsx index 76ca7bd..988c55c 100644 --- a/webapp/src/routes.tsx +++ b/webapp/src/routes.tsx @@ -2,10 +2,9 @@ import { lazy, Suspense } from "react"; import { Panel } from "@flanksource/clicky-ui/components"; import { useRouter } from "@flanksource/clicky-ui/rpc"; -const Status = lazy(() => import("./Status")); +const OverviewPage = lazy(() => import("./overview/OverviewPage")); const TopPage = lazy(() => import("./top/TopPage")); const ProcessPage = lazy(() => import("./top/ProcessPage")); -const TracesPage = lazy(() => import("./traces/TracesPage")); const ConnectionsPage = lazy(() => import("./workspace/ConnectionsPage")); const AgentsPage = lazy(() => import("./workspace/AgentsPage")); const ArmPage = lazy(() => import("./workspace/ArmPage")); @@ -60,24 +59,6 @@ export function matchRoute(pathname: string): Route { return { page: "notFound", pathname }; } -function Overview() { - return ( -
    -
    -

    Telltale

    -

    Your workspace is ready.

    -
    - - Connecting to the backend…

    }>
    -
    - - Loading trace runs…

    }>
    -
    - View the OpenAPI specification -
    - ); -} - /** The page of the current location. */ export function AppRoutes() { const { pathname, renderLink } = useRouter(); @@ -90,7 +71,7 @@ export function AppRoutes() { case "arm": return Loading arming form…

    }>
    ; case "query": return Loading query workspace…

    }>
    ; case "records": return Loading result profile…

    }>
    ; - case "overview": return ; + case "overview": return Loading overview…

    }>
    ; case "top": return ( Loading process groups…

    }>
    diff --git a/webapp/src/traces/RunProcessDetail.tsx b/webapp/src/traces/RunProcessDetail.tsx new file mode 100644 index 0000000..ff38538 --- /dev/null +++ b/webapp/src/traces/RunProcessDetail.tsx @@ -0,0 +1,31 @@ +import { useMemo } from "react"; +import { GoProfileView, ProcessTraceDetail, armedFacets } from "@flanksource/clicky-ui/data"; +import { Button, Section } from "@flanksource/clicky-ui/components"; +import { UiLoader, UiRefresh } from "@flanksource/clicky-ui/icons"; +import type { ProcessTraceState } from "./useProcessTrace"; + +export function RunProcessDetail({ trace, selectedKey }: { trace: ProcessTraceState; selectedKey: string | null }) { + const selected = useMemo(() => trace.nodes.find(node => node.key === selectedKey) ?? null, [trace.nodes, selectedKey]); + const canRefresh = trace.canCollect && armedFacets(trace.samples).length > 0; + const hasProfiles = !!selected && trace.goprof.some(record => record.key === selected.key); + return
    + {selected && canRefresh &&
    + {trace.refreshError && {trace.refreshError}} + +
    } + + {selected && hasProfiles &&
    +
    + + {trace.goprofExportUrl && Download pprof} +
    +
    } +
    ; +} diff --git a/webapp/src/traces/RunProcesses.tsx b/webapp/src/traces/RunProcesses.tsx deleted file mode 100644 index ab085b7..0000000 --- a/webapp/src/traces/RunProcesses.tsx +++ /dev/null @@ -1,107 +0,0 @@ -import { useMemo } from "react"; -import { GoProfileView, ProcessTraceDetail, ProcessTraceTree, armedFacets } from "@flanksource/clicky-ui/data"; -import { Button, Section, SplitPane } from "@flanksource/clicky-ui/components"; -import { UiLoader, UiRefresh } from "@flanksource/clicky-ui/icons"; -import type { ProcessTraceState } from "./useProcessTrace"; - -export interface RunProcessesProps { - /** The run's process capture, as useProcessTrace reads it. */ - trace: ProcessTraceState; - /** The key of the selected process, or null. */ - selectedKey: string | null; - onSelect: (key: string) => void; - hideExited: boolean; - onHideExitedChange: (hide: boolean) => void; - expandAll: boolean | null; - onExpandAllChange: (next: boolean | null) => void; - className?: string; -} - -/** - * The Processes view: the run's process tree beside the selected process's - * detail (command, lifetime, usage, stack dumps, environment and the facet - * tabs the samples carry) and, when the run ingested Go profiles for it, its - * profiles. Collect and refresh need the run's live capture - * (`trace.canCollect`): a stored run shows what was recorded and offers - * neither. - */ -export function RunProcesses({ - trace, - selectedKey, - onSelect, - hideExited, - onHideExitedChange, - expandAll, - onExpandAllChange, - className, -}: RunProcessesProps) { - const selected = useMemo(() => trace.nodes.find(node => node.key === selectedKey) ?? null, [trace.nodes, selectedKey]); - const canRefresh = trace.canCollect && armedFacets(trace.samples).length > 0; - const hasProfiles = !!selected && trace.goprof.some(record => record.key === selected.key); - - return ( - - )} - right={( -
    - {selected && canRefresh && ( -
    - {trace.refreshError && {trace.refreshError}} - -
    - )} - - {selected && hasProfiles && ( -
    -
    - - {trace.goprofExportUrl && ( - - Download pprof - - )} -
    -
    - )} -
    - )} - /> - ); -} diff --git a/webapp/src/traces/RunTasks.test.tsx b/webapp/src/traces/RunTasks.test.tsx new file mode 100644 index 0000000..b2c5426 --- /dev/null +++ b/webapp/src/traces/RunTasks.test.tsx @@ -0,0 +1,43 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { fireEvent, render, screen } from "@testing-library/react"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { TracesPanel } from "./TracesPanel"; +import type { RunTraces } from "./api"; + +const run: RunTraces = { + runId: "clicky-run", mount: "/api/traces/clicky-run", dir: "/clicky-run", status: "succeeded", + captures: [{ kind: "task", ref: { kind: "task", stream: "task-1" } }], +}; + +const records = [ + { seq: 1, phase: "status", id: "t1", name: "deploy api", type: "task", status: "running" }, + { seq: 2, phase: "progress", id: "t1", name: "deploy api", type: "task", status: "running", progress: 1, maxValue: 2 }, + { seq: 3, phase: "status", id: "t1", name: "deploy api", type: "task", status: "success", progress: 2, maxValue: 2 }, + { seq: 4, phase: "status", id: "t2", name: "migrate db", type: "task", status: "failed", error: "lock timeout" }, +]; + +beforeEach(() => { + window.history.replaceState(null, "", "/"); + vi.stubGlobal("fetch", vi.fn(async (url: string) => { + const request = new URL(url, window.location.origin); + if (request.pathname.endsWith("/task/export")) return new Response(records.map(row => JSON.stringify(row)).join("\n")); + if (request.pathname.endsWith("/processes")) return Response.json({ armed: false, rows: [] }); + if (request.pathname.endsWith("/records")) return Response.json({ rows: [], nextCursor: "" }); + return new Response("Unexpected request", { status: 404 }); + })); +}); +afterEach(() => vi.unstubAllGlobals()); + +describe("a run with a clicky task capture", () => { + it("shows its tasks at their latest records in the clicky-ui task viewer", async () => { + render( + + ); + fireEvent.click(screen.getByRole("tab", { name: "Tasks" })); + const panel = await screen.findByRole("tabpanel", { name: "Tasks" }); + expect(await screen.findByText("deploy api")).toBeInTheDocument(); + expect(panel).toHaveTextContent("migrate db"); + expect(panel).toHaveTextContent("lock timeout"); + expect(window.location.search).toContain("runView=tasks"); + }); +}); diff --git a/webapp/src/traces/RunTasks.tsx b/webapp/src/traces/RunTasks.tsx new file mode 100644 index 0000000..db3740f --- /dev/null +++ b/webapp/src/traces/RunTasks.tsx @@ -0,0 +1,53 @@ +import { useEffect, useMemo, useState } from "react"; +import { TaskProgress } from "@flanksource/clicky-ui/data"; +import { fetchTraceRecords, followTraceRecords, TraceStreamNotFound, type CaptureResult, type TraceRecord } from "./api"; +import { taskSnapshots } from "./taskSnapshots"; + +/** A clicky agent's task capture in clicky-ui's task viewer, followed while the run records. */ +export function RunTasks({ mount, capture, live }: { mount: string; capture: CaptureResult; live: boolean }) { + const [records, setRecords] = useState([]); + const [error, setError] = useState(); + const [loading, setLoading] = useState(true); + useEffect(() => { + const controller = new AbortController(); + let stop: (() => void) | undefined; + setRecords([]); + setError(undefined); + setLoading(true); + fetchTraceRecords(mount, capture.ref, controller.signal) + .catch((reason: unknown) => { + if (reason instanceof TraceStreamNotFound) return [] as TraceRecord[]; + throw reason; + }) + .then(initial => { + if (controller.signal.aborted) return; + setRecords(initial); + setLoading(false); + if (!live) return; + const afterSeq = initial.reduce((max, row) => Math.max(max, Number(row.seq) || 0), capture.ref.afterSeq ?? 0); + stop = followTraceRecords({ + mount, ref: { ...capture.ref, afterSeq }, + onRow: row => setRecords(previous => [...previous, row]), + onError: reason => setError(reason.message), + onOpen: () => setError(undefined), + onEnd: () => {}, + }); + }) + .catch((reason: unknown) => { + if (controller.signal.aborted) return; + setLoading(false); + setError(reason instanceof Error ? reason.message : String(reason)); + }); + return () => { controller.abort(); stop?.(); }; + }, [mount, capture.ref, live]); + const projected = useMemo(() => { + try { return { snapshots: taskSnapshots(records) }; } + catch (reason) { return { error: reason instanceof Error ? reason.message : String(reason) }; } + }, [records]); + if (loading) return

    Loading tasks…

    ; + const message = error ?? projected.error; + return
    + {message &&

    {message}

    } + {projected.snapshots && } +
    ; +} diff --git a/webapp/src/traces/TracesPage.test.tsx b/webapp/src/traces/TracesPage.test.tsx index 48ac76f..38796da 100644 --- a/webapp/src/traces/TracesPage.test.tsx +++ b/webapp/src/traces/TracesPage.test.tsx @@ -73,6 +73,8 @@ function serve(status: TracesStatus, started: Response = json(running, 201), lis if (init?.method === "DELETE") return Promise.resolve(new Response(null, { status: 202 })); if (url.endsWith("/traces/kinds")) return Promise.resolve(json([{ name: "http", title: "HTTP traffic", exportFormats: [{ name: "har", ext: "har", mime: "application/json" }] }])); if (url.includes("/seq?")) return Promise.resolve(json({ seq: 0 })); + if (url.endsWith("/processes")) return Promise.resolve(json({ armed: false, rows: [] })); + if (url.includes("/export?")) return Promise.resolve(new Response("")); if (url.includes("/records?")) return Promise.resolve(json({ rows: [], nextCursor: "" })); return Promise.resolve(new Response("", { status: 404 })); }); @@ -95,9 +97,9 @@ describe("trace runs", () => { const fetchMock = serve({ runs: [finished, other] }); renderPage(); expect(await screen.findByRole("combobox", { name: "Run" })).toHaveValue(other.runId); - await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${other.mount}/records?sort=seq&limit=100`, expect.anything())); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${other.mount}/records?sort=timestamp&excludeKind=process&presentation=ansi&limit=100`, expect.anything())); fireEvent.change(screen.getByRole("combobox", { name: "Run" }), { target: { value: runId } }); - await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/records?sort=seq&limit=100`, expect.anything())); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/records?sort=timestamp&excludeKind=process&presentation=ansi&limit=100`, expect.anything())); expect(new URLSearchParams(window.location.search).get("run")).toBe(runId); expect(screen.queryByText("New run")).not.toBeInTheDocument(); }); @@ -105,7 +107,7 @@ describe("trace runs", () => { const fetchMock = serve({ runs: [{ ...finished, command: undefined, process: undefined, captures: [{ kind, ref: { kind, stream: "connection-or-agent", toSeq: 2 }, summary: { count: 2 } }] }] }); renderPage(); expect(await screen.findByText("host run")).toBeInTheDocument(); - await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/records?sort=seq&limit=100`, expect.anything())); + await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(`${mount}/records?sort=timestamp&excludeKind=process&presentation=ansi&limit=100`, expect.anything())); expect(screen.queryByRole("alert")).not.toBeInTheDocument(); }); @@ -121,7 +123,8 @@ describe("trace runs", () => { expect(await screen.findByText("curl https://example.com")).toBeInTheDocument(); expect(screen.getByText(/exited with code 0/)).toBeInTheDocument(); expect(screen.getByRole("option", { name: `${runId} (succeeded)` })).toBeInTheDocument(); - expect(screen.getByRole("option", { name: "http" })).toBeInTheDocument(); + fireEvent.click(screen.getByRole("combobox", { name: "Capture" })); + expect(await screen.findByRole("option", { name: "http" })).toBeInTheDocument(); }); it("names an attached run by its pid and lists the checkpoints that failed", async () => { @@ -236,6 +239,7 @@ describe("host runs recording process groups", () => { if (init?.method === "DELETE") return Promise.resolve(new Response(null, { status: 202 })); if (url.endsWith("/traces/kinds")) return Promise.resolve(json([{ name: "process", title: "Processes", exportFormats: [] }])); if (url.includes("/seq?")) return Promise.resolve(json({ seq: 4 })); + if (url.endsWith("/processes")) return Promise.resolve(json({ armed: true, rows: [] })); if (url.includes("/export?")) return Promise.resolve(new Response(rows)); if (url.includes("/records?")) return Promise.resolve(json({ rows: [], nextCursor: "" })); return Promise.resolve(new Response("", { status: 404 })); @@ -256,6 +260,7 @@ describe("host runs recording process groups", () => { it("shows a stopped host run's groups instead of saying it is unavailable", async () => { serveGroups([{ ...hostRun, status: "succeeded", captures: [{ kind: "process", ref: { ...groupsRef, toSeq: 4 } }] }]); renderPage(); + fireEvent.click(await screen.findByRole("tab", { name: "Process details" })); expect(await screen.findByRole("row", { name: /^claude/ })).toBeInTheDocument(); expect(screen.getByText("host run")).toBeInTheDocument(); expect(screen.getByText(/ended/)).toBeInTheDocument(); @@ -281,7 +286,7 @@ describe("starting a run", () => { await waitFor(() => expect(fetchMock).toHaveBeenCalledWith("/api/traces", expect.objectContaining({ method: "POST", body: JSON.stringify({ command: "sleep 60" }), }))); - await waitFor(() => expect(Object.fromEntries(new URLSearchParams(window.location.search))).toEqual({ run: running.runId, feedSort: "seq" })); + await waitFor(() => expect(Object.fromEntries(new URLSearchParams(window.location.search))).toEqual({ run: running.runId, feedSort: "timestamp" })); }); it("starts a saved definition with only the run's execution fields", async () => { @@ -296,7 +301,7 @@ describe("starting a run", () => { await waitFor(() => expect(fetchMock).toHaveBeenCalledWith("/api/traces", expect.objectContaining({ method: "POST", body: JSON.stringify({ definition: "checkout", command: "./bin/checkout", duration: "20s" }), }))); - await waitFor(() => expect(Object.fromEntries(new URLSearchParams(window.location.search))).toEqual({ run: running.runId, feedSort: "seq" })); + await waitFor(() => expect(Object.fromEntries(new URLSearchParams(window.location.search))).toEqual({ run: running.runId, feedSort: "timestamp" })); }); it("shows a failed definition listing and keeps the inline start", async () => { diff --git a/webapp/src/traces/TracesPage.tsx b/webapp/src/traces/TracesPage.tsx index a9f06aa..f7fb320 100644 --- a/webapp/src/traces/TracesPage.tsx +++ b/webapp/src/traces/TracesPage.tsx @@ -2,12 +2,9 @@ import { useEffect, useState } from "react"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; import { Button, Panel } from "@flanksource/clicky-ui/components"; import { fetchTraceRuns, RUN_STATUSES, stopRun, type RunFilter, type RunStatus, type RunTraces } from "./api"; -import { DEFAULT_VIEW, type GroupsView } from "../top/groups"; -import { processGroupsCapture, RecordedGroups } from "../top/RecordedGroups"; -import { RunProcesses } from "./RunProcesses"; import { StartRunForm } from "./StartRunForm"; import { TracesPanel } from "./TracesPanel"; -import { useProcessTrace } from "./useProcessTrace"; +import { RunShellSlot } from "../layout/RunShellSlot"; const LIVE_POLL_MS = 1000; @@ -72,7 +69,7 @@ function RunFilters({ filter, onChange }: { filter: RunFilter; onChange: (next: ); } -function RunSummary({ run }: { run: RunTraces }) { +function RunSummary({ run, readOnly = false }: { run: RunTraces; readOnly?: boolean }) { const queryClient = useQueryClient(); const stop = useMutation({ mutationFn: () => stopRun(run), @@ -81,7 +78,7 @@ function RunSummary({ run }: { run: RunTraces }) { // A host run traces the host, not a command or a pid, and is live while it is running (it has no live sessions). const hostRun = !run.standing && !run.pid && !run.command?.length; const running = !!run.live || (hostRun && run.status === "running"); - const command = {run.standing ? "standing store" : run.pid ? `pid ${run.pid}` : hostRun ? "host run" : run.command?.join(" ")}; + const command = {run.standing ? "standing store" : run.pid ? `pid ${run.pid}` : hostRun ? "host run" : run.command?.join(" ")}; const errors = [...(run.error ? [run.error] : []), ...(run.checkpointErrors ?? [])]; const failed = errors.length ? (
      @@ -100,55 +97,15 @@ function RunSummary({ run }: { run: RunTraces }) {
      running {command} - + {!readOnly && } {stop.error && {stop.error.message}}
      ); } -/** Captures recorded without a local process tree. */ -function HostRunDetail({ run }: { run: RunTraces }) { - const [view, setView] = useState(DEFAULT_VIEW); - return ( -
      - - {processGroupsCapture(run) && setView(previous => ({ ...previous, ...next }))} />} - -
      - ); -} - -function RunDetail({ run }: { run: RunTraces }) { - const [selectedKey, setSelectedKey] = useState(null); - const [hideExited, setHideExited] = useState(false); - const [expandAll, setExpandAll] = useState(true); - const trace = useProcessTrace({ - mount: run.mount, - ...(run.process && !run.unavailable ? { refs: run.process } : {}), - ...(run.live ? { sessions: run.live.sessions } : {}), - ...(selectedKey ? { selectedKey } : {}), - done: !run.live, - }); +export function RunDetail({ run, readOnly = false }: { run: RunTraces; readOnly?: boolean }) { if (run.unavailable) return

      {run.unavailable}

      ; - if (!run.process) return ; - return ( -
      - - - - - -
      - ); + return } />; } function RunList({ state, setState }: { state: PageState; setState: (next: Partial) => void }) { @@ -188,7 +145,7 @@ function RunList({ state, setState }: { state: PageState; setState: (next: Parti {runs.map(candidate => )} - +
    ); } @@ -201,14 +158,14 @@ function RunViewer({ selected, onSelect }: { selected?: string; onSelect: (id: s const runs = result.data.runs; const run = runs.find(candidate => candidate.runId === selected) ?? runs[0]; if (!run) return

    The viewer has no trace run.

    ; - return
    - {runs.length > 1 &&