Telemetry của Go — Tài liệu Go tiếng Việt

Mục lục:

Bối cảnh
Tổng quan
Cấu hình
Counter
Report và upload
Biểu đồ
Quy trình đề xuất telemetry
Nhắc trong IDE
Câu hỏi thường gặp

Bối cảnh

Go telemetry (thu thập dữ liệu sử dụng) là cách để các chương trình trong Go toolchain thu thập dữ liệu về hiệu năng và cách chúng được sử dụng. Ở đây “Go toolchain” nghĩa là các công cụ dành cho lập trình viên do nhóm Go bảo trì, bao gồm lệnh go và các công cụ bổ trợ như Go language server gopls hay công cụ bảo mật govulncheck. Go telemetry chỉ dành cho các chương trình do nhóm Go bảo trì và một số phụ thuộc được chọn lọc như Delve.

Theo mặc định, dữ liệu telemetry chỉ được giữ trên máy tính của bạn, nhưng người dùng có thể opt-in để upload một tập con dữ liệu telemetry đã được phê duyệt lên telemetry.go.dev. Dữ liệu được upload giúp nhóm Go cải thiện ngôn ngữ Go và các công cụ của nó, bằng cách giúp chúng tôi hiểu cách chúng được sử dụng và chỗ nào bị hỏng.

Từ “telemetry” đã mang những hàm ý tiêu cực trong thế giới phần mềm nguồn mở, và trong nhiều trường hợp thì điều đó là xứng đáng. Tuy vậy, đo lường trải nghiệm người dùng là một phần quan trọng của kỹ nghệ phần mềm hiện đại, còn các nguồn dữ liệu như issue trên GitHub hay khảo sát thường niên thì thô và luôn đi sau thực tế, không đủ cho những loại câu hỏi mà nhóm Go cần trả lời. Go telemetry được thiết kế để giúp các chương trình trong toolchain thu thập dữ liệu hữu ích về độ tin cậy, hiệu năng và cách sử dụng, trong khi vẫn giữ được sự minh bạch và quyền riêng tư mà người dùng mong đợi ở dự án Go. Để tìm hiểu thêm về quá trình thiết kế và động cơ của telemetry, xin xem loạt bài blog về telemetry. Để tìm hiểu thêm về telemetry và quyền riêng tư, xin xem chính sách quyền riêng tư của telemetry.

Trang này giải thích khá chi tiết cách Go telemetry hoạt động. Nếu muốn câu trả lời nhanh cho các câu hỏi thường gặp, xem FAQ.

Với Go 1.23 trở lên, để opt-in vào việc upload dữ liệu telemetry cho nhóm Go, hãy chạy:

go telemetry on

Để tắt hoàn toàn telemetry, kể cả việc thu thập cục bộ, hãy chạy:

go telemetry off

Để quay về chế độ mặc định là chỉ thu thập cục bộ, hãy chạy:

go telemetry local

Trước Go 1.23, bạn cũng có thể làm việc này bằng lệnh golang.org/x/telemetry/cmd/gotelemetry. Xem Cấu hình để biết thêm chi tiết.

Tổng quan

Go telemetry dùng ba kiểu dữ liệu cốt lõi:

Counter là các phép đếm nhẹ cho những sự kiện có tên, được gắn vào trong chương trình của toolchain. Nếu việc thu thập được bật (mode là local hoặc on), counter được ghi vào một tệp ánh xạ bộ nhớ trên hệ thống tệp cục bộ.
Report là các bản tổng hợp counter cho một tuần nhất định. Nếu việc upload được bật (mode là on), report cho các counter đã được phê duyệt sẽ được upload lên telemetry.go.dev, nơi chúng được công khai cho mọi người.
Biểu đồ tóm tắt các report đã upload từ tất cả người dùng. Bạn có thể xem biểu đồ tại telemetry.go.dev.

Toàn bộ dữ liệu và cấu hình Go telemetry cục bộ được lưu trong thư mục os.UserConfigDir()/go/telemetry. Bên dưới, chúng tôi sẽ gọi thư mục này là <gotelemetry>.

Sơ đồ dưới đây minh hoạ luồng dữ liệu này.

Sơ đồ luồng dữ liệu telemetry: chương trình ghi counter cục bộ, dữ liệu được tổng hợp thành báo cáo rồi upload lên telemetry.go.dev

Trong phần còn lại của tài liệu, chúng tôi sẽ đi qua từng thành phần của sơ đồ này. Nhưng trước hết, hãy tìm hiểu về phần cấu hình điều khiển nó.

Cấu hình

Hành vi của Go telemetry được điều khiển bởi một giá trị duy nhất: mode của telemetry. Các giá trị khả dĩ của mode là local (mặc định), on hoặc off:

Khi mode là local, dữ liệu telemetry được thu thập và lưu trên máy tính cục bộ, nhưng không bao giờ được upload lên máy chủ từ xa.
Khi mode là on, dữ liệu được thu thập, và có thể được upload tuỳ theo cơ chế lấy mẫu.
Khi mode là off, dữ liệu không được thu thập và cũng không được upload.

Với Go 1.23 trở lên, các câu lệnh sau tương tác với mode của telemetry:

go telemetry: xem mode hiện tại.
go telemetry on: đặt mode thành on.
go telemetry off: đặt mode thành off.
go telemetry local: đặt mode thành local.

Thông tin về cấu hình telemetry cũng có sẵn qua các biến môi trường chỉ đọc của Go:

go env GOTELEMETRY cho biết mode của telemetry.
go env GOTELEMETRYDIR cho biết thư mục chứa cấu hình và dữ liệu telemetry.

Lệnh gotelemetry cũng có thể được dùng để cấu hình mode của telemetry, cũng như để xem dữ liệu telemetry cục bộ. Dùng câu lệnh sau để cài đặt nó:

go install golang.org/x/telemetry/cmd/gotelemetry@latest

Để biết đầy đủ thông tin sử dụng công cụ dòng lệnh gotelemetry, xem tài liệu package của nó.

Counter

Như đã nói ở trên, Go telemetry được gắn đo thông qua counter. Counter có hai biến thể: basic counter và stack counter.

Basic counter

Basic counter là một giá trị có thể tăng dần, kèm một cái tên mô tả sự kiện mà nó đếm. Ví dụ, counter gopls/client:vscode ghi lại số lần một phiên gopls được khởi tạo bởi VS Code. Bên cạnh counter này, chúng ta có thể có gopls/client:neovim, gopls/client:eglot, v.v., để ghi lại các phiên với những trình soạn thảo hoặc language client khác nhau. Nếu bạn dùng nhiều trình soạn thảo trong tuần, dữ liệu counter có thể được ghi lại như sau:

gopls/client:vscode 8
gopls/client:neovim 5
gopls/client:eglot  2

Khi các counter liên quan với nhau theo kiểu này, đôi khi chúng tôi gọi phần trước dấu : là tên biểu đồ (gopls/client trong trường hợp này), và phần sau dấu : là tên bucket (vscode). Chúng ta sẽ thấy vì sao điều này quan trọng khi bàn về biểu đồ.

Basic counter cũng có thể biểu diễn một histogram. Ví dụ, counter gopls/completion/latency:<50ms ghi lại số lần một lần tự động hoàn thành mã mất dưới 50ms.

gopls/completion/latency:<10ms
gopls/completion/latency:<50ms
gopls/completion/latency:<100ms
...

Cách ghi dữ liệu histogram này chỉ là một quy ước: không có gì đặc biệt ở tên bucket <50ms. Những loại counter này thường được dùng để đo hiệu năng.

Stack counter

Stack counter là một counter đồng thời ghi lại cả call stack hiện tại của chương trình trong Go toolchain tại thời điểm giá trị đếm được tăng. Ví dụ, stack counter crash/crash ghi lại call stack khi một chương trình của toolchain bị crash:

crash/crash
golang.org/x/tools/gopls/internal/golang.hoverBuiltin:+22
golang.org/x/tools/gopls/internal/golang.Hover:+94
golang.org/x/tools/gopls/internal/server.Hover:+42
...

Stack counter thường đo các sự kiện mà bất biến của chương trình bị vi phạm. Ví dụ phổ biến nhất là một lần crash, nhưng một ví dụ khác là stack counter gopls/bug, đếm những tình huống bất thường đã được lập trình viên xác định trước, chẳng hạn một panic được recover hoặc một lỗi “không thể xảy ra”. Stack counter chỉ bao gồm tên hàm và số dòng của các hàm bên trong chương trình của Go toolchain. Chúng không chứa bất kỳ thông tin nào về đầu vào của người dùng, như tên hay nội dung mã nguồn của người dùng.

Stack counter có thể giúp truy tìm những bug hiếm gặp hoặc khó nắm bắt mà không được báo cáo bằng cách nào khác. Kể từ khi giới thiệu counter gopls/bug, chúng tôi đã tìm ra hàng chục trường hợp đoạn mã “không thể chạm tới” nhưng lại thực sự được chạm tới trong thực tế, và việc truy tìm những ngoại lệ đó đã dẫn tới việc phát hiện (và sửa) nhiều bug mà người dùng nhìn thấy nhưng hoặc không rõ ràng với họ, hoặc quá khó để báo cáo. Đặc biệt với việc kiểm thử các bản tiền phát hành, stack counter giúp chúng tôi cải thiện sản phẩm hiệu quả hơn so với khi không có tự động hoá.

Tệp counter

Toàn bộ dữ liệu counter được ghi vào thư mục <gotelemetry>/local, trong các tệp được đặt tên theo lược đồ sau:

[program name]@[program version]-[go version]-[GOOS]-[GOARCH]-[date].v1.count

program name là basename của đường dẫn package của chương trình, theo báo cáo của debug.BuildInfo.
program version và go version cũng do debug.BuildInfo báo cáo.
Các giá trị GOOS và GOARCH do runtime.GOOS và runtime.GOARCH báo cáo.
date là ngày tệp counter được tạo, theo định dạng YYYY-MM-DD.

Những tệp này được ánh xạ bộ nhớ vào từng tiến trình đang chạy của các chương trình được gắn đo. Việc dùng tệp ánh xạ bộ nhớ nghĩa là ngay cả khi chương trình crash ngay lập tức, hoặc nhiều bản sao của các công cụ được gắn đo đang chạy đồng thời, các counter vẫn được ghi lại an toàn.

Report và upload

Xấp xỉ mỗi tuần một lần, dữ liệu counter được tổng hợp thành các report có tên <date>.json trong thư mục <gotelemetry>/local. Các report này cộng dồn toàn bộ số đếm của tuần trước, nhóm theo cùng các định danh chương trình đã dùng cho tệp counter (program name, program version, go version, GOOS và GOARCH).

Report cục bộ có thể được xem dưới dạng biểu đồ bằng lệnh gotelemetry view. Dưới đây là một ví dụ tóm tắt của counter gopls/completion/latency:

Biểu đồ tóm tắt counter gopls/completion/latency theo từng khoảng độ trễ

Upload

Nếu việc upload telemetry được bật, quy trình lập report hàng tuần cũng sẽ tạo ra các report chứa tập con các counter có mặt trong cấu hình upload. Các counter này phải được phê duyệt qua quy trình xem xét công khai được mô tả ở phần tiếp theo. Sau khi được upload thành công, một bản sao của các report đã upload sẽ được lưu trong thư mục <gotelemetry>/upload.

Khi đã có đủ số người dùng opt-in vào việc upload dữ liệu telemetry, quy trình upload sẽ ngẫu nhiên bỏ qua việc upload đối với một phần các report, nhằm giảm lượng dữ liệu thu thập và tăng quyền riêng tư trong khi vẫn giữ được ý nghĩa thống kê.

Biểu đồ

Ngoài việc nhận các bản upload, website telemetry.go.dev còn công khai dữ liệu đã upload cho mọi người. Mỗi ngày, các report đã upload được xử lý thành hai kết quả, có sẵn trên trang chủ telemetry.go.dev.

Report merged gộp các counter từ tất cả các bản upload nhận được trong ngày.
Biểu đồ vẽ dữ liệu đã upload theo đặc tả trong [chart config], vốn được tạo ra như một phần của quy trình đề xuất. Nhớ lại phần bàn về counter rằng tên counter dạng foo:bar được tách thành tên biểu đồ foo và tên bucket bar. Mỗi biểu đồ tổng hợp các counter có cùng tên biểu đồ vào các bucket tương ứng.

Biểu đồ được đặc tả theo định dạng của package chartconfig. Ví dụ, dưới đây là chart config cho biểu đồ gopls/client.

title: Editor Distribution
counter: gopls/client:{vscode,vscodium,vscode-insiders,code-server,eglot,govim,neovim,coc.nvim,sublimetext,other}
description: measure editor distribution for gopls users.
type: partition
issue: https://go.dev/issue/61038
issue: https://go.dev/issue/62214 # add vscode-insiders
program: golang.org/x/tools/gopls
version: v0.13.0 # temporarily back-version to demonstrate config generation.

Cấu hình này mô tả biểu đồ sẽ được tạo ra, liệt kê tập các counter cần tổng hợp, và chỉ định những phiên bản chương trình mà biểu đồ áp dụng. Ngoài ra, quy trình đề xuất yêu cầu biểu đồ phải gắn với một đề xuất đã được chấp thuận. Đây là biểu đồ tạo ra từ cấu hình đó:

Biểu đồ cột tần suất các editor dùng gopls, VS Code chiếm khoảng 80%

Quy trình đề xuất telemetry

Mọi thay đổi với cấu hình upload hoặc tập biểu đồ trên telemetry.go.dev đều phải đi qua quy trình đề xuất telemetry, nhằm bảo đảm sự minh bạch với các thay đổi của cấu hình telemetry.

Đáng chú ý là trong quy trình này thực ra không có sự phân biệt giữa cấu hình upload và cấu hình biểu đồ. Bản thân cấu hình upload được diễn đạt theo các phép tổng hợp mà chúng tôi muốn hiển thị trên telemetry.go.dev, dựa trên nguyên tắc rằng chúng tôi chỉ nên thu thập dữ liệu mà chúng tôi muốn nhìn thấy.

Quy trình đề xuất như sau:

Người đề xuất tạo một CL sửa config.txt của package chartconfig để chứa các phép tổng hợp counter mới mong muốn.
Người đề xuất mở một proposal để merge CL này.
Khi thảo luận trên issue đã ngã ngũ, đề xuất được một thành viên của nhóm Go chấp thuận hoặc từ chối.
Một quy trình tự động sẽ tái tạo cấu hình upload để cho phép upload các counter cần thiết cho biểu đồ mới. Quy trình này cũng sẽ thường xuyên bổ sung các phiên bản mới của các chương trình liên quan vào cấu hình upload khi chúng được phát hành.

Để được chấp thuận, biểu đồ mới không được mang thông tin nhạy cảm của người dùng, và ngoài ra phải vừa hữu ích vừa khả thi. Để hữu ích, biểu đồ phải phục vụ một mục đích cụ thể, với kết quả có thể hành động được. Để khả thi, phải có khả năng thu thập dữ liệu cần thiết một cách đáng tin cậy, và các phép đo thu được phải có ý nghĩa thống kê. Để chứng minh tính khả thi, người đề xuất có thể được yêu cầu gắn counter vào chương trình đích và thu thập chúng cục bộ trước.

Toàn bộ tập các đề xuất như vậy có tại dự án proposal trên GitHub.

Nhắc trong IDE

Để telemetry trả lời được những loại câu hỏi mà chúng tôi muốn hỏi, tập người dùng opt-in vào việc upload không cần phải lớn — khoảng 16.000 người tham gia là đủ cho các phép đo có ý nghĩa thống kê ở mức độ chi tiết mong muốn. Tuy nhiên, việc gom được mẫu lành mạnh này vẫn có cái giá của nó: chúng tôi cần hỏi một số lượng lớn lập trình viên Go xem họ có muốn opt-in hay không.

Hơn nữa, ngay cả khi một số lượng lớn người dùng chọn opt-in ngay bây giờ (có thể sau khi đọc một bài blog của Go), những người dùng đó có thể thiên lệch về phía các lập trình viên Go giàu kinh nghiệm, và theo thời gian mẫu ban đầu đó sẽ càng thiên lệch hơn. Ngoài ra, khi người ta thay máy tính, họ phải chủ động chọn opt-in lại. Trong loạt bài blog về telemetry, điều này được gọi là “chi phí chiến dịch” của mô hình opt-in.

Để giữ cho mẫu người dùng tham gia luôn tươi mới, Go language server gopls hỗ trợ một lời nhắc hỏi người dùng có muốn opt-in vào Go telemetry hay không. Đây là hình ảnh của nó trong VS Code:

Thông báo trong VS Code hỏi bạn có muốn bật Go telemetry hay không, với hai nút đồng ý và từ chối

Nếu người dùng chọn “Yes”, mode telemetry của họ sẽ được đặt thành on, y như khi họ chạy gotelemetry on. Bằng cách này, việc opt-in trở nên dễ dàng nhất có thể, và chúng tôi có thể liên tục tiếp cận một mẫu lớn và phân tầng gồm các lập trình viên Go.

Câu hỏi thường gặp

Hỏi: Làm sao để bật hoặc tắt Go telemetry?

Đáp: Dùng lệnh gotelemetry, có thể cài đặt bằng go install golang.org/x/telemetry/cmd/gotelemetry@latest. Chạy gotelemetry off để tắt mọi thứ, kể cả việc thu thập cục bộ. Chạy gotelemetry on để bật mọi thứ, bao gồm cả việc upload các counter đã được phê duyệt lên telemetry.go.dev. Xem phần Cấu hình để biết thêm.

Hỏi: Dữ liệu cục bộ được lưu ở đâu?

Đáp: Trong thư mục os.UserConfigDir()/go/telemetry.

Hỏi: Nếu tôi opt-in thì dữ liệu được upload bao lâu một lần?

Đáp: Xấp xỉ mỗi tuần một lần.

Hỏi: Nếu tôi opt-in thì dữ liệu nào được upload?

Đáp: Chỉ những counter được liệt kê trong cấu hình upload mới có thể được upload. Nó được sinh ra từ [chart config], vốn có thể dễ đọc hơn.

Hỏi: Counter được thêm vào cấu hình upload bằng cách nào?

Đáp: Thông qua quy trình đề xuất công khai.

Hỏi: Tôi có thể xem dữ liệu telemetry đã được upload ở đâu?

Đáp: Dữ liệu đã upload có sẵn dưới dạng biểu đồ hoặc bản tóm tắt gộp tại telemetry.go.dev.

Hỏi: Mã nguồn của Go telemetry ở đâu?

Đáp: Tại golang.org/x/telemetry.