From 11f25408720176f601de1762a9509fe0c4140b64 Mon Sep 17 00:00:00 2001 From: Uzair Chhapra <41239986+uzairchhapra@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:32:20 -0500 Subject: [PATCH] feat: add a Merge Queue Timings query Reconstruct queue attempts from pull request timeline events and expose durations for Grafana dashboards. Refs grafana/github-datasource#866 --- .changeset/quiet-queues-time.md | 5 + docs/sources/query-editor.md | 23 ++++ pkg/github/merge_queue_timings.go | 141 ++++++++++++++++++++++ pkg/github/merge_queue_timings_handler.go | 21 ++++ pkg/github/merge_queue_timings_test.go | 75 ++++++++++++ pkg/github/query_handler.go | 1 + pkg/models/query.go | 2 + src/constants.ts | 1 + src/types/query.ts | 3 + src/validation.test.ts | 19 +++ src/validation.ts | 1 + src/views/QueryEditor.tsx | 1 + 12 files changed, 293 insertions(+) create mode 100644 .changeset/quiet-queues-time.md create mode 100644 pkg/github/merge_queue_timings.go create mode 100644 pkg/github/merge_queue_timings_handler.go create mode 100644 pkg/github/merge_queue_timings_test.go create mode 100644 src/validation.test.ts diff --git a/.changeset/quiet-queues-time.md b/.changeset/quiet-queues-time.md new file mode 100644 index 00000000..27ea3d2c --- /dev/null +++ b/.changeset/quiet-queues-time.md @@ -0,0 +1,5 @@ +--- +'grafana-github-datasource': minor +--- + +Add a Merge Queue Timings query to visualize how long pull requests spend in GitHub's merge queue. diff --git a/docs/sources/query-editor.md b/docs/sources/query-editor.md index 049a3cd9..75822624 100644 --- a/docs/sources/query-editor.md +++ b/docs/sources/query-editor.md @@ -40,6 +40,7 @@ Select a query type from the **Query Type** drop-down in the query editor: - [**Deployments**](#deployments): List deployments for a repository, including environment, ref, and task information. - [**Issues**](#issues): List issues in a repository, using the GitHub query syntax to filter the response. - [**Labels**](#labels): List labels defined in a repository. +- [**Merge queue timings**](#merge-queue-timings): Measure how long each pull request attempt spent in GitHub's merge queue. - [**Milestones**](#milestones): Retrieve milestones for a repository, which can be used to group issues and pull requests. - [**Packages**](#packages): List packages published from a repository in an organization. - [**Projects**](#projects): List projects associated with a user or organization. @@ -426,6 +427,28 @@ Show all labels for the `grafana/grafana` repository: | color | Hexadecimal number | | description | Label description | +### Merge queue timings + +Measure how long pull requests spend in GitHub's merge queue. Select **Merge Queue Timings** and set **Owner** and **Repository**. The query reads queue entry and removal events from each pull request's [GitHub timeline](https://docs.github.com/en/graphql/reference/pulls), rather than using workflow run or check run timestamps. + +The Grafana time range selects pull requests by their **last updated** timestamp. For each matching pull request, the query returns its full queue history, including attempts outside the selected range. A subsequent update can move a pull request out of a historical selection. GitHub search returns up to 1,000 matching pull requests, so use a narrower range for busy repositories. + +#### Response + +The table contains one row per queue attempt. A pull request that leaves and re-enters the queue has multiple rows; a pull request that never entered the queue has none. + +| Name | Description | +|------|-------------| +| `repository` | Repository in `owner/name` format | +| `pull_request_number` | Pull request number | +| `pull_request_url` | Link to the pull request | +| `enqueued_at` | Timestamp of the queue entry | +| `exited_at` | Timestamp of the matching queue removal, or null if no removal was recorded | +| `exit_reason` | Removal reason reported by GitHub, such as `merged`, or null if unavailable | +| `duration_seconds` | Seconds between queue entry and removal, or null for an attempt with no matching removal | + +To see the distribution of time spent in the queue, use a **Histogram** panel with the `duration_seconds` field. To compare merged attempts only, add a **Filter data by values** transformation that keeps rows where `exit_reason` is `merged`. This measures total time in the queue, not time spent running individual checks. + ### Milestones Retrieve milestones for a repository, which can be used to group issues and pull requests. diff --git a/pkg/github/merge_queue_timings.go b/pkg/github/merge_queue_timings.go new file mode 100644 index 00000000..6827efc3 --- /dev/null +++ b/pkg/github/merge_queue_timings.go @@ -0,0 +1,141 @@ +package github + +import ( + "context" + "fmt" + "strings" + "time" + + "github.com/grafana/github-datasource/pkg/models" + "github.com/grafana/grafana-plugin-sdk-go/data" + "github.com/shurcooL/githubv4" +) + +type mergeQueueTimeline struct { + Nodes []struct { + Type string `graphql:"__typename"` + Added struct { + CreatedAt githubv4.DateTime + } `graphql:"... on AddedToMergeQueueEvent"` + Removed struct { + CreatedAt githubv4.DateTime + Reason *string + } `graphql:"... on RemovedFromMergeQueueEvent"` + } + PageInfo models.PageInfo +} + +type mergeQueueSearch struct { + Search struct { + Nodes []struct { + PullRequest struct { + ID githubv4.ID + Number int64 + URL string + Timeline mergeQueueTimeline `graphql:"timelineItems(first: 20, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT])"` + } `graphql:"... on PullRequest"` + } + PageInfo models.PageInfo + } `graphql:"search(query: $query, type: ISSUE, first: 50, after: $searchCursor)"` +} + +type mergeQueueTimelinePage struct { + Node struct { + PullRequest struct { + Timeline mergeQueueTimeline `graphql:"timelineItems(first: 100, after: $timelineCursor, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT])"` + } `graphql:"... on PullRequest"` + } `graphql:"node(id: $id)"` +} + +type mergeQueueAttempt struct { + Number int64 + URL string + EnqueuedAt time.Time + ExitedAt *time.Time + ExitReason *string +} + +type mergeQueueTimings struct { + repository string + attempts []mergeQueueAttempt +} + +func (m mergeQueueTimings) Frames() data.Frames { + duration := data.NewField("duration_seconds", nil, []*float64{}) + duration.Config = &data.FieldConfig{Unit: "s"} + frame := data.NewFrame("merge_queue_timings", + data.NewField("repository", nil, []string{}), + data.NewField("pull_request_number", nil, []int64{}), + data.NewField("pull_request_url", nil, []string{}), + data.NewField("enqueued_at", nil, []time.Time{}), + data.NewField("exited_at", nil, []*time.Time{}), + data.NewField("exit_reason", nil, []*string{}), + duration, + ) + for _, attempt := range m.attempts { + var seconds *float64 + if attempt.ExitedAt != nil { + value := attempt.ExitedAt.Sub(attempt.EnqueuedAt).Seconds() + seconds = &value + } + frame.AppendRow(m.repository, attempt.Number, attempt.URL, attempt.EnqueuedAt, attempt.ExitedAt, attempt.ExitReason, seconds) + } + return data.Frames{frame} +} + +type mergeQueueQuerier interface { + Query(context.Context, any, map[string]any) error +} + +// GetMergeQueueTimings finds PRs updated in the time range and reconstructs their queue attempts from timeline events. +func GetMergeQueueTimings(ctx context.Context, client mergeQueueQuerier, owner, repo string, from, to time.Time) (mergeQueueTimings, error) { + result := mergeQueueTimings{repository: owner + "/" + repo} + if strings.TrimSpace(owner) == "" || strings.TrimSpace(repo) == "" || from.IsZero() || to.Before(from) { + return result, nil + } + + search := fmt.Sprintf("is:pr repo:%s updated:%s..%s", result.repository, from.UTC().Format(time.RFC3339), to.UTC().Format(time.RFC3339)) + variables := map[string]any{"query": githubv4.String(search), "searchCursor": (*githubv4.String)(nil)} + for { + var page mergeQueueSearch + if err := client.Query(ctx, &page, variables); err != nil { + return result, fmt.Errorf("searching for pull requests in %s: %w", result.repository, err) + } + for _, node := range page.Search.Nodes { + pr := node.PullRequest + timeline := pr.Timeline + // Keep the pending enqueue across timeline pages, but never across PRs. + pending := -1 + for { + for _, event := range timeline.Nodes { + switch event.Type { + case "AddedToMergeQueueEvent": + if !event.Added.CreatedAt.IsZero() { + pending = len(result.attempts) + result.attempts = append(result.attempts, mergeQueueAttempt{Number: pr.Number, URL: pr.URL, EnqueuedAt: event.Added.CreatedAt.Time}) + } + case "RemovedFromMergeQueueEvent": + if pending >= 0 && !event.Removed.CreatedAt.Before(result.attempts[pending].EnqueuedAt) { + attempt := &result.attempts[pending] + attempt.ExitedAt = &event.Removed.CreatedAt.Time + attempt.ExitReason = event.Removed.Reason + pending = -1 + } + } + } + if !timeline.PageInfo.HasNextPage { + break + } + var next mergeQueueTimelinePage + if err := client.Query(ctx, &next, map[string]any{"id": pr.ID, "timelineCursor": &timeline.PageInfo.EndCursor}); err != nil { + return result, fmt.Errorf("reading merge queue timeline for %s#%d: %w", result.repository, pr.Number, err) + } + timeline = next.Node.PullRequest.Timeline + } + } + if !page.Search.PageInfo.HasNextPage { + return result, nil + } + variables["searchCursor"] = &page.Search.PageInfo.EndCursor + } +} diff --git a/pkg/github/merge_queue_timings_handler.go b/pkg/github/merge_queue_timings_handler.go new file mode 100644 index 00000000..b19e4560 --- /dev/null +++ b/pkg/github/merge_queue_timings_handler.go @@ -0,0 +1,21 @@ +package github + +import ( + "context" + + "github.com/grafana/github-datasource/pkg/dfutil" + "github.com/grafana/github-datasource/pkg/models" + "github.com/grafana/grafana-plugin-sdk-go/backend" +) + +// HandleMergeQueueTimings handles plugin queries for GitHub merge queue attempts. +func (s *QueryHandler) HandleMergeQueueTimings(ctx context.Context, req *backend.QueryDataRequest) (*backend.QueryDataResponse, error) { + responses := processQueries(ctx, req, func(ctx context.Context, q backend.DataQuery) backend.DataResponse { + var query models.Query + if err := UnmarshalQuery(q.JSON, &query); err != nil { + return *err + } + return dfutil.FrameResponseWithError(GetMergeQueueTimings(ctx, s.Datasource.client, query.Owner, query.Repository, q.TimeRange.From, q.TimeRange.To)) + }) + return &backend.QueryDataResponse{Responses: responses}, nil +} diff --git a/pkg/github/merge_queue_timings_test.go b/pkg/github/merge_queue_timings_test.go new file mode 100644 index 00000000..417089d2 --- /dev/null +++ b/pkg/github/merge_queue_timings_test.go @@ -0,0 +1,75 @@ +package github + +import ( + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/shurcooL/githubv4" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestGetMergeQueueTimings(t *testing.T) { + from := time.Date(2026, 11, 17, 0, 0, 0, 0, time.UTC) + to := from.Add(24 * time.Hour) + requests := make(chan string, 4) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + var request struct { + Query string + Variables map[string]any + } + if err := json.NewDecoder(r.Body).Decode(&request); err != nil { + t.Error(err) + w.WriteHeader(http.StatusBadRequest) + return + } + w.Header().Set("Content-Type", "application/json") + switch { + case request.Variables["query"] != nil && request.Variables["searchCursor"] == nil: + requests <- "first search page" + assert.Equal(t, "is:pr repo:github/docs updated:2026-11-17T00:00:00Z..2026-11-18T00:00:00Z", request.Variables["query"]) + assert.Contains(t, request.Query, "ADDED_TO_MERGE_QUEUE_EVENT, REMOVED_FROM_MERGE_QUEUE_EVENT") + fmt.Fprint(w, `{"data":{"search":{"nodes":[{"id":"PR_1","number":1,"url":"https://github.com/github/docs/pull/1","timelineItems":{"nodes":[{"__typename":"AddedToMergeQueueEvent","createdAt":"2026-11-17T08:00:00Z"}],"pageInfo":{"hasNextPage":true,"endCursor":"more-events"}}}],"pageInfo":{"hasNextPage":true,"endCursor":"more-prs"}}}}`) + case request.Variables["timelineCursor"] == "more-events": + requests <- "next timeline page" + assert.Equal(t, "PR_1", request.Variables["id"]) + assert.Contains(t, request.Query, "$id:ID!") + fmt.Fprint(w, `{"data":{"node":{"timelineItems":{"nodes":[{"__typename":"RemovedFromMergeQueueEvent","createdAt":"2026-11-17T08:01:30Z","reason":"failed checks"},{"__typename":"AddedToMergeQueueEvent","createdAt":"2026-11-17T08:45:01Z"},{"__typename":"RemovedFromMergeQueueEvent","createdAt":"2026-11-17T08:50:56Z","reason":"merged"}],"pageInfo":{"hasNextPage":false}}}}}`) + case request.Variables["searchCursor"] == "more-prs": + requests <- "next search page" + fmt.Fprint(w, `{"data":{"search":{"nodes":[{"id":"PR_2","number":2,"url":"https://github.com/github/docs/pull/2","timelineItems":{"nodes":[{"__typename":"AddedToMergeQueueEvent","createdAt":"2026-11-17T09:00:00Z"}],"pageInfo":{"hasNextPage":false}}},{"id":"PR_3","number":3,"url":"https://github.com/github/docs/pull/3","timelineItems":{"nodes":[],"pageInfo":{"hasNextPage":false}}}],"pageInfo":{"hasNextPage":false}}}}`) + default: + t.Errorf("unexpected query: %s (%v)", request.Query, request.Variables) + w.WriteHeader(http.StatusBadRequest) + } + })) + defer server.Close() + + result, err := GetMergeQueueTimings(t.Context(), githubv4.NewEnterpriseClient(server.URL, server.Client()), "github", "docs", from, to) + require.NoError(t, err) + require.Len(t, requests, 3) + frames := result.Frames() + require.Len(t, frames, 1) + frame := frames[0] + require.Equal(t, "merge_queue_timings", frame.Name) + require.Equal(t, 3, frame.Rows()) + require.Len(t, frame.Fields, 7) + assert.Equal(t, "github/docs", frame.Fields[0].At(1)) + assert.Equal(t, int64(1), frame.Fields[1].At(1)) + assert.Equal(t, "https://github.com/github/docs/pull/1", frame.Fields[2].At(1)) + assert.Equal(t, "duration_seconds", frame.Fields[6].Name) + assert.Equal(t, "s", frame.Fields[6].Config.Unit) + assert.Equal(t, 90.0, *frame.Fields[6].At(0).(*float64)) + assert.Equal(t, "failed checks", *frame.Fields[5].At(0).(*string)) + assert.Equal(t, 355.0, *frame.Fields[6].At(1).(*float64)) + assert.Equal(t, "merged", *frame.Fields[5].At(1).(*string)) + assert.Equal(t, from.Add(8*time.Hour+45*time.Minute+time.Second), frame.Fields[3].At(1)) + assert.Equal(t, int64(2), frame.Fields[1].At(2)) + assert.Nil(t, frame.Fields[4].At(2)) + assert.Nil(t, frame.Fields[5].At(2)) + assert.Nil(t, frame.Fields[6].At(2)) +} diff --git a/pkg/github/query_handler.go b/pkg/github/query_handler.go index fa2728b6..fa299bed 100644 --- a/pkg/github/query_handler.go +++ b/pkg/github/query_handler.go @@ -51,6 +51,7 @@ func GetQueryHandlers(s *QueryHandler) *datasource.QueryTypeMux { register(models.QueryTypeContributors, s.HandleContributors) register(models.QueryTypeLabels, s.HandleLabels) register(models.QueryTypePullRequests, s.HandlePullRequests) + register(models.QueryTypeMergeQueueTimings, s.HandleMergeQueueTimings) register(models.QueryTypePullRequestReviews, s.HandlePullRequestReviews) register(models.QueryTypeReleases, s.HandleReleases) register(models.QueryTypeTags, s.HandleTags) diff --git a/pkg/models/query.go b/pkg/models/query.go index ecaf9d6f..56735ad0 100644 --- a/pkg/models/query.go +++ b/pkg/models/query.go @@ -17,6 +17,8 @@ const ( QueryTypeReleases QueryType = "Releases" // QueryTypePullRequests is used when querying pull requests in a GitHub repository QueryTypePullRequests QueryType = "Pull_Requests" + // QueryTypeMergeQueueTimings is used when querying pull request merge queue attempts. + QueryTypeMergeQueueTimings QueryType = "Merge_Queue_Timings" // QueryTypePullRequestReviews is used when querying pull request reviews in a GitHub repository QueryTypePullRequestReviews = "Pull_Request_Reviews" // QueryTypeLabels is used when querying labels in a GitHub repository diff --git a/src/constants.ts b/src/constants.ts index 19ecb368..d6730b2b 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -10,6 +10,7 @@ export const QueryTypes = [ 'Tags', 'Branches', 'Releases', + 'Merge_Queue_Timings', 'Pull_Requests', 'Pull_Requests_For_Branches', 'Pull_Request_Reviews', diff --git a/src/types/query.ts b/src/types/query.ts index 16998b28..61d34e8e 100644 --- a/src/types/query.ts +++ b/src/types/query.ts @@ -72,6 +72,8 @@ export type Pull_RequestsOptions = Options & { type Pull_RequestsQuery = BaseQuery<'Pull_Requests', Pull_RequestsOptions> //#endregion +type Merge_Queue_TimingsQuery = BaseQuery<'Merge_Queue_Timings', {}> + //#region Pull_Requests_For_Branches Query export type Pull_Requests_For_BranchesOptions = Options & { branches?: string[]; @@ -212,6 +214,7 @@ export type GitHubQuery = ContributorsQuery | TagsQuery | ReleasesQuery | + Merge_Queue_TimingsQuery | Pull_RequestsQuery | Pull_Requests_For_BranchesQuery | Pull_Request_ReviewsQuery | diff --git a/src/validation.test.ts b/src/validation.test.ts new file mode 100644 index 00000000..3c768911 --- /dev/null +++ b/src/validation.test.ts @@ -0,0 +1,19 @@ +import { isValid } from './validation'; +import type { GitHubQuery } from './types/query'; + +const query: GitHubQuery = { + refId: 'A', + queryType: 'Merge_Queue_Timings', + owner: 'github', + repository: 'docs', +}; + +describe('Merge Queue Timings query validation', () => { + it('accepts an owner and repository without extra options', () => { + expect(isValid(query)).toBe(true); + }); + + it.each(['owner', 'repository'] as const)('requires %s', (key) => { + expect(isValid({ ...query, [key]: undefined })).toBe(false); + }); +}); diff --git a/src/validation.ts b/src/validation.ts index 1c32149c..f8c6cc37 100644 --- a/src/validation.ts +++ b/src/validation.ts @@ -12,6 +12,7 @@ export const isValid = (query: GitHubQuery): boolean => { query.queryType === "Commits" || query.queryType === 'Commit_Files' || query.queryType === 'Check_Runs' || + query.queryType === 'Merge_Queue_Timings' || query.queryType === "Contributors" || query.queryType === "Tags" || query.queryType === "Releases" || diff --git a/src/views/QueryEditor.tsx b/src/views/QueryEditor.tsx index d7bb80cc..f4eb968b 100644 --- a/src/views/QueryEditor.tsx +++ b/src/views/QueryEditor.tsx @@ -52,6 +52,7 @@ const queryEditors: Record <> }, + ['Merge_Queue_Timings']: { component: () => <> }, ['Vulnerabilities']: { component: () => <> }, ['Stargazers']: { component: () => <> }, ['Labels']: {