GitLabgitlab-org

cli

main
ply6 git calls462 ms98 KiB3 cachedprotocol v2
250 lines7.6 KiBRaw
1package main
3import (
4 "context"
5 "maps"
6 "net/http"
7 "strconv"
8 "strings"
9 "time"
11 "github.com/spf13/cobra"
13 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
15 "gitlab.com/gitlab-org/cli/internal/cmdutils"
16 apiCmd "gitlab.com/gitlab-org/cli/internal/commands/api"
17 "gitlab.com/gitlab-org/cli/internal/config"
18 "gitlab.com/gitlab-org/cli/internal/dbg"
19 "gitlab.com/gitlab-org/cli/internal/utils"
22// telemetrySendTimeout bounds how long glab delays its own exit for the event.
23const telemetrySendTimeout = 2 * time.Second
25// noRetry stops the client's five default retries turning an instant failure,
26// such as a refused connection, into the full timeout.
27func noRetry(ctx context.Context, _ *http.Response, _ error) (bool, error) {
28 if ctx.Err() != nil {
29 return false, ctx.Err()
30 }
31 return false, nil
34func telemetryRequestOptions(ctx context.Context) []gitlab.RequestOptionFunc {
35 return []gitlab.RequestOptionFunc{
36 gitlab.WithContext(ctx),
37 gitlab.WithRequestRetry(noRetry),
38 }
41// telemetrySkippedCommands run from shell startup files and from git, not from
42// a person, so they must not block on the network.
43var telemetrySkippedCommands = map[string]struct{}{
44 cobra.ShellCompRequestCmd: {},
45 "completion": {},
46 "auth git-credential": {},
47 "auth credential-helper": {},
50// agentHookFlags are flags with which a command runs from an agent's hook that
51// waits for it. Such a run sends no telemetry, because the glab that it starts
52// sends its own event, and does not check for updates.
53var agentHookFlags = map[string]string{
54 "minder audit sync": "hook",
55 // Hooks installed before the rename to glab minder still run glab govern.
56 "govern audit sync": "hook",
59// runByAgentHook reports whether cmd ran from an agent's hook that waits for it.
60func runByAgentHook(cmd *cobra.Command) bool {
61 _, _, fullCommand := parseCommand(strings.Split(cmd.CommandPath(), " "))
62 flag, ok := agentHookFlags[fullCommand]
63 return ok && cmd.Flags().Changed(flag)
66func addTelemetryHook(f cmdutils.Factory, rootCmd *cobra.Command, args []string) func() {
67 return func() {
68 // Cobra registers __complete (and its __completeNoDesc alias) during Execute.
69 cmd, _, err := rootCmd.Find(args)
70 if err != nil {
71 dbg.Debug("Could not determine command in telemetry hook: ", err.Error())
72 return
73 }
74 sendTelemetryData(f, cmd)
75 }
78// isTelemetryEnabled checks if usage data is disabled via config or env var
79func isTelemetryEnabled(cfg config.Config) bool {
80 if enabled, found := utils.IsEnvVarEnabled("GLAB_SEND_TELEMETRY"); found {
81 return enabled
82 }
84 // Fall back to config value if env var not set
85 if telemetryEnabled, _ := cfg.Get("", "telemetry"); telemetryEnabled != "" {
86 if telemetryEnabledParsed, err := strconv.ParseBool(telemetryEnabled); err == nil {
87 return telemetryEnabledParsed
88 }
89 }
91 return true
94// parseCommand parses a command string and returns components
95func parseCommand(parts []string) (string, string, string) {
96 if len(parts) < 2 {
97 return "", "", ""
98 }
100 // glab is always the first value, command is the next
101 command := parts[1]
103 subcommandParts := parts[2:]
104 subcommand := strings.Join(subcommandParts, " ")
106 fullCommand := command
107 if subcommand != "" {
108 fullCommand += " " + subcommand
109 }
111 return command, subcommand, fullCommand
114func sendTelemetryData(f cmdutils.Factory, cmd *cobra.Command) {
115 if cmd == nil {
116 return
117 }
119 command, subcommand, fullCommand := parseCommand(strings.Split(cmd.CommandPath(), " "))
120 if _, skip := telemetrySkippedCommands[fullCommand]; skip {
121 dbg.Debug("Telemetry skipped for machine-invoked command: ", fullCommand)
122 return
123 }
124 if runByAgentHook(cmd) {
125 dbg.Debug("Telemetry skipped for command run by an agent hook: ", fullCommand)
126 return
127 }
129 client, event, ok := buildTelemetryEvent(f, command, subcommand, fullCommand)
130 if !ok {
131 return
132 }
133 maps.Copy(event.AdditionalProperties, apiEventProperties(cmd))
135 // Not cmd.Context(): that is already cancelled if the command was interrupted.
136 ctx, cancel := context.WithTimeout(context.Background(), telemetrySendTimeout)
137 defer cancel()
139 if err := trackEvent(client, event, telemetryRequestOptions(ctx)...); err != nil {
140 dbg.Debug("Could not send telemetry data: ", err.Error())
141 }
144// trackEventOptions is gitlab.TrackEventOptions plus project_path, which
145// client-go does not model yet. Sending the path lets the instance resolve the
146// project and namespace IDs, which saves glab an API call of its own.
147type trackEventOptions struct {
148 Event string `json:"event"`
149 SendToSnowplow *bool `json:"send_to_snowplow,omitempty"`
150 ProjectPath string `json:"project_path,omitempty"`
151 AdditionalProperties map[string]string `json:"additional_properties,omitempty"`
154func trackEvent(client *gitlab.Client, event *trackEventOptions, options ...gitlab.RequestOptionFunc) error {
155 req, err := client.NewRequest(http.MethodPost, "usage_data/track_event", event, options)
156 if err != nil {
157 return err
158 }
160 _, err = client.Do(req, nil)
161 return err
164// Reported instead of the path when no route matches, so an unrecognised path
165// is discarded whole rather than partially redacted.
166const unmatchedEndpoint = "unmatched"
168func apiEventProperties(cmd *cobra.Command) map[string]string {
169 if cmd.Name() != "api" {
170 return nil
171 }
173 args := cmd.Flags().Args()
174 if len(args) == 0 {
175 return nil
176 }
178 return map[string]string{
179 "api_endpoint": templateEndpoint(args[0]),
180 "http_method": apiCmd.EffectiveMethod(cmd),
181 }
184// templateEndpoint reduces a request path to the matching route template.
185// Identifiers are not distinguishable from route nouns by shape, so the path is
186// matched rather than rewritten: "users/phikai/projects" must not keep the
187// username.
188func templateEndpoint(path string) string {
189 // Query strings and fragments carry identifiers and sometimes tokens.
190 path, _, _ = strings.Cut(path, "?")
191 path, _, _ = strings.Cut(path, "#")
193 // client-go reaches GraphQL through its own client, so it has no route.
194 if strings.Trim(path, "/") == "graphql" {
195 return "/graphql"
196 }
198 if route, ok := gitlab.MatchRoute(path); ok {
199 return route.String()
200 }
201 return unmatchedEndpoint
204// buildTelemetryEvent assembles the event without making a request of its own.
205func buildTelemetryEvent(f cmdutils.Factory, command, subcommand, fullCommand string) (*gitlab.Client, *trackEventOptions, bool) {
206 var projectPath string
207 var client *gitlab.Client
209 repo, err := f.BaseRepo()
210 if err != nil {
211 dbg.Debug("Could not determine base repo in telemetry hook: ", err.Error())
213 c, err := f.ApiClient("")
214 if err != nil {
215 dbg.Debug("Could not get API client in telemetry hook: ", err.Error())
216 return nil, nil, false
217 }
218 client = c.Lab()
219 } else {
220 c, err := f.GitLabClient()
221 if err != nil {
222 dbg.Debug("Could not get API client in telemetry hook: ", err.Error())
223 return nil, nil, false
224 }
225 client = c
226 projectPath = repo.FullName()
227 }
229 buildInfo := f.BuildInfo()
230 properties := map[string]string{
231 "label": command,
232 "property": subcommand,
233 "command_and_subcommand": fullCommand,
234 "cli_version": buildInfo.Version,
235 "platform": buildInfo.Platform,
236 "architecture": buildInfo.Architecture,
237 }
238 // Absent rather than empty, so "no agent" and "client too old to report
239 // one" stay distinguishable via cli_version.
240 if buildInfo.CodingAgent != "" {
241 properties["coding_agent"] = buildInfo.CodingAgent
242 }
244 return client, &trackEventOptions{
245 Event: "gitlab_cli_command_used",
246 ProjectPath: projectPath,
247 SendToSnowplow: new(true),
248 AdditionalProperties: properties,
249 }, true
Diagnostics6 git calls · 462 ms
CallStatusSizeTime0462 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=5
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=5
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0200195 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=195
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=62ad6b84b990e694d7e6e68667ba67fcbef93a08
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=195
git.pkt.payload.max=168
git.sideband.band1.bytes=168
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=168
git.pack.trailer=946df40edc15e3ab53d2f74cc477577e7e3fbcdc
Open pack map
fetch2002.9 KiB451 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=451
git.response.bytes=2944
git.response.cache=MISS
git.response.duration_ms=451
git.fetch.wants=e608d8f266684678940d349fc80056ab8ef9fcfd
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2944
git.pkt.payload.max=2917
git.sideband.band1.bytes=2917
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e211111e157f3b
Request
fd7c9645…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format