Go OpenTelemetry tracing cho nhìn nhận end-to-end của API

Ý nghĩa của tracing end-to-end cho một API Go

Một trace là dòng thời gian của một yêu cầu khi nó đi qua hệ thống của bạn. Nó bắt đầu khi một cuộc gọi API đến và kết thúc khi bạn gửi phản hồi.

Bên trong một trace có các span. Một span là một bước được đo thời gian, như “phân tích yêu cầu”, “chạy SQL”, hoặc “gọi nhà cung cấp thanh toán”. Span cũng có thể chứa thông tin hữu ích, như mã trạng thái HTTP, một định danh người dùng an toàn, hoặc số hàng mà một truy vấn trả về.

“End-to-end” nghĩa là trace không dừng lại ở handler đầu tiên của bạn. Nó theo dõi yêu cầu qua những nơi mà lỗi thường ẩn náu: middleware, truy vấn cơ sở dữ liệu, cache, job nền, API bên thứ ba (thanh toán, email, bản đồ), và các dịch vụ nội bộ khác.

Tracing có giá trị nhất khi các sự cố xảy ra không đều. Nếu một trong 200 yêu cầu bị chậm, logs thường trông giống nhau cho cả trường hợp nhanh và chậm. Một trace làm sự khác biệt rõ ràng: một yêu cầu chờ 800 ms cho một cuộc gọi ngoài, thử lại hai lần, rồi khởi tạo job tiếp theo.

Nhật ký cũng khó liên kết giữa các dịch vụ. Bạn có thể có một dòng log trong API, một dòng khác trong worker, và không có gì ở giữa. Với tracing, những sự kiện đó chia sẻ cùng một trace ID, nên bạn có thể theo dõi chuỗi mà không phải đoán mò.

Trace, metrics và logs: chúng liên quan với nhau ra sao

Trace, metrics và logs trả lời những câu hỏi khác nhau.

Trace cho bạn thấy điều gì đã xảy ra với một yêu cầu thực tế. Chúng cho biết thời gian được phân bổ như thế nào giữa handler, các cuộc gọi cơ sở dữ liệu, tra cứu cache và các yêu cầu bên thứ ba.

Metrics cho thấy xu hướng. Chúng là công cụ tốt nhất cho cảnh báo vì ổn định và rẻ để tổng hợp: phần trăm độ trễ, lưu lượng yêu cầu, tỷ lệ lỗi, độ sâu hàng đợi và độ bão hòa.

Logs là “tại sao” bằng văn bản rõ ràng: lỗi xác thực, đầu vào bất thường, các trường hợp biên và các quyết định mà mã của bạn đưa ra.

Lợi ích thực sự là việc tương quan. Khi cùng một trace ID xuất hiện trong spans và logs có cấu trúc, bạn có thể nhảy từ một log lỗi đến trace chính xác và ngay lập tức thấy phụ thuộc nào bị chậm hay bước nào bị lỗi.

Mô hình tư duy đơn giản

Dùng mỗi loại tín hiệu cho điều nó giỏi nhất:

• Metrics báo cho bạn biết có gì đó không ổn.
• Traces cho thấy thời gian đi đâu cho một yêu cầu.
• Logs giải thích code của bạn đã quyết định gì và vì sao.

Ví dụ: endpoint POST /checkout bắt đầu timeout. Metrics cho thấy p95 độ trễ tăng vọt. Một trace cho thấy phần lớn thời gian nằm trong cuộc gọi tới nhà cung cấp thanh toán. Một dòng log được liên kết trong span đó cho thấy các lần thử lại do 502, điều này hướng bạn tới cài đặt backoff hoặc sự cố phía trên.

Trước khi thêm code: đặt tên, sampling và theo dõi gì

Lên kế hoạch trước giúp cho trace có thể tìm kiếm sau này. Nếu không, bạn vẫn thu thập dữ liệu, nhưng các câu hỏi cơ bản trở nên khó: “Đây là staging hay prod?” “Dịch vụ nào bắt đầu vấn đề?”

Bắt đầu với nhận dạng nhất quán. Chọn một service.name rõ ràng cho mỗi API Go (ví dụ checkout-api) và một trường môi trường duy nhất như deployment.environment=dev|staging|prod. Giữ chúng ổn định. Nếu tên thay đổi giữa tuần, biểu đồ và tìm kiếm trông như là các hệ thống khác nhau.

Tiếp theo, quyết định sampling. Tracing mọi yêu cầu thì tốt trong phát triển, nhưng thường quá tốn kém trong production. Cách làm phổ biến là lấy mẫu một tỷ lệ nhỏ lưu lượng bình thường và giữ lại traces cho lỗi và các yêu cầu chậm. Nếu bạn đã biết một số endpoint có lưu lượng cao (health checks, polling), hãy trace ít hơn hoặc không trace chúng.

Cuối cùng, thống nhất những gì sẽ đánh dấu trên spans và những gì sẽ không bao giờ thu thập. Giữ một danh sách cho phép ngắn các thuộc tính giúp bạn kết nối sự kiện giữa các dịch vụ, và viết quy tắc riêng tư đơn giản.

Các tag tốt thường bao gồm các ID ổn định và thông tin yêu cầu thô (mẫu route, phương thức, mã trạng thái). Tránh hoàn toàn các payload nhạy cảm: mật khẩu, dữ liệu thanh toán, email đầy đủ, token xác thực và thân yêu cầu thô. Nếu bạn phải bao gồm giá trị liên quan đến người dùng, hãy băm hoặc che đi trước khi thêm.

Hướng dẫn từng bước: thêm OpenTelemetry tracing vào một API HTTP Go

Bạn sẽ thiết lập một tracer provider một lần lúc khởi động. Điều này quyết định nơi các span được gửi và những attribute resource gắn vào mỗi span.

1) Khởi tạo OpenTelemetry

Hãy chắc rằng bạn đặt service.name. Nếu không, các trace từ nhiều dịch vụ khác nhau sẽ lẫn vào nhau và biểu đồ sẽ khó đọc.

// main.go (startup)
exp, _ := stdouttrace.New(stdouttrace.WithPrettyPrint())

res, _ := resource.New(context.Background(),
	resource.WithAttributes(
		semconv.ServiceName("checkout-api"),
	),
)

tp := sdktrace.NewTracerProvider(
	sdktrace.WithBatcher(exp),
	sdktrace.WithResource(res),
)

otel.SetTracerProvider(tp)

Đây là nền tảng cho Go OpenTelemetry tracing. Tiếp theo, bạn cần một span cho mỗi yêu cầu đến.

2) Thêm middleware HTTP và bắt các trường quan trọng

Dùng middleware HTTP bắt đầu span tự động và ghi lại mã trạng thái cùng thời lượng. Đặt tên span theo mẫu route (như /users/:id), không phải URL thô, nếu không bạn sẽ có hàng nghìn đường dẫn duy nhất.

Hướng tới một baseline sạch: một server span cho mỗi yêu cầu, tên span theo route, mã trạng thái HTTP được ghi lại, lỗi handler hiện diện dưới dạng span error, và thời lượng hiển thị trong trình xem trace của bạn.

3) Làm lỗi hiển nhiên

Khi có lỗi, trả về lỗi và đánh dấu span hiện tại là failed. Điều đó giúp trace nổi bật ngay cả trước khi bạn xem logs.

Trong handler, bạn có thể làm:

span := trace.SpanFromContext(r.Context())
span.RecordError(err)
span.SetStatus(codes.Error, err.Error())

4) Xác minh trace ID cục bộ

Chạy API và gọi một endpoint. Log trace ID từ context yêu cầu một lần để xác nhận nó thay đổi theo mỗi yêu cầu. Nếu nó luôn rỗng, middleware của bạn không dùng cùng context mà handler nhận.

Mang context qua DB và các cuộc gọi bên thứ ba

End-to-end visibility bị phá vỡ ngay khi bạn làm mất context.Context. Context của yêu cầu đến nên là sợi chỉ bạn truyền cho mọi gọi DB, HTTP và helper. Nếu bạn thay thế nó bằng context.Background() hoặc quên truyền xuống, trace của bạn biến thành các công việc tách rời, không liên quan.

Với HTTP outbound, dùng transport đã được instrument để mỗi Do(req) thành một child span dưới yêu cầu hiện tại. Chuyển các header W3C trace trên các yêu cầu đi ra để dịch vụ hạ nguồn có thể gắn span của họ vào cùng một trace.

Các cuộc gọi cơ sở dữ liệu cần được xử lý tương tự. Dùng driver đã instrument hoặc bao quanh các cuộc gọi với span quanh QueryContext và ExecContext. Chỉ ghi các chi tiết an toàn. Bạn muốn tìm truy vấn chậm mà không làm lộ dữ liệu.

Các thuộc tính hữu ích và ít rủi ro bao gồm tên thao tác (ví dụ SELECT user_by_id), tên bảng hoặc model, số hàng (chỉ đếm), thời lượng, số lần thử và loại lỗi thô (timeout, canceled, constraint).

Timeout là một phần của câu chuyện, không chỉ là thất bại. Đặt chúng bằng context.WithTimeout cho DB và các cuộc gọi bên thứ ba, và để các hủy bỏ nổi lên. Khi một cuộc gọi bị hủy, đánh dấu span là lỗi và thêm lý do ngắn như deadline_exceeded.

Tracing job nền và hàng đợi

Công việc nền là nơi traces thường dừng lại. Một yêu cầu HTTP kết thúc, rồi một worker lấy một message sau đó trên máy khác với context không chia sẻ. Nếu bạn không làm gì, bạn sẽ có hai câu chuyện: trace API và một trace job trông như bắt đầu từ hư không.

Cách khắc phục đơn giản: khi enqueue một job, lấy context trace hiện tại và lưu nó vào metadata của job (payload, headers, hoặc attributes, tùy hàng đợi). Khi worker bắt đầu, trích xuất context đó và bắt một span mới là child của yêu cầu gốc.

Truyền context an toàn

Chỉ sao chép context trace, không dữ liệu người dùng.

• Inject chỉ các định danh trace và flag sampling (kiểu W3C traceparent).
• Giữ nó tách biệt khỏi trường nghiệp vụ (ví dụ một trường riêng tên "otel" hoặc "trace").
• Xử lý nó như dữ liệu không tin cậy khi bạn đọc lại (xác thực định dạng, xử lý khi thiếu dữ liệu).
• Tránh bỏ token, email hoặc thân yêu cầu vào metadata job.

Các span nên thêm (không làm trace ồn ào)

Trace đọc được thường có một vài span ý nghĩa, không phải hàng chục span nhỏ. Tạo span quanh ranh giới và các “điểm chờ”. Một khởi điểm tốt là một span enqueue trong handler API và một span job.run trong worker.

Thêm một ít context: số lần thử, tên queue, loại job và kích thước payload (không phải nội dung). Nếu có retry, ghi chúng như span riêng hoặc event để bạn thấy trễ backoff.

Các tác vụ theo lịch cũng cần một parent. Nếu không có yêu cầu đến, tạo một root span mới cho mỗi lần chạy và gắn thẻ với tên lịch.

Tương quan logs với traces (và giữ logs an toàn)

Traces cho bạn thấy thời gian đi đâu. Logs cho bạn biết điều gì đã xảy ra và vì sao. Cách đơn giản nhất để kết nối chúng là thêm trace_id và span_id vào mỗi mục log như các trường có cấu trúc.

Trong Go, lấy span đang hoạt động từ context.Context và bổ sung logger của bạn một lần cho mỗi yêu cầu (hoặc job). Khi đó mọi dòng log đều trỏ tới một trace cụ thể.

span := trace.SpanFromContext(ctx)
sc := span.SpanContext()
logger := baseLogger.With(
  "trace_id", sc.TraceID().String(),
  "span_id",  sc.SpanID().String(),
)
logger.Info("charge_started", "order_id", orderID)

Đó là đủ để nhảy từ một mục log đến span chính xác đang chạy khi nó xảy ra. Nó cũng làm cho context bị thiếu trở nên rõ ràng: trace_id sẽ rỗng.

Giữ logs hữu ích mà không làm lộ PII

Logs thường sống lâu hơn và di chuyển xa hơn traces, nên cần nghiêm ngặt hơn. Ưu tiên các định danh và kết quả ổn định: user_id, order_id, payment_provider, status và error_code. Nếu bạn phải log đầu vào người dùng, hãy redact trước và giới hạn độ dài.

Làm cho lỗi dễ gom nhóm

Dùng tên sự kiện và loại lỗi nhất quán để bạn có thể đếm và tìm kiếm. Nếu cách diễn đạt thay đổi mỗi lần, cùng một lỗi sẽ trông như nhiều vấn đề khác nhau.

Thêm metrics hữu ích để tìm lỗi

Metrics là hệ thống cảnh báo ban đầu của bạn. Trong một cấu hình đã dùng Go OpenTelemetry tracing, metrics nên trả lời: bao nhiêu lần, tệ đến mức nào, và từ khi nào.

Bắt đầu với một tập nhỏ phù hợp với hầu hết API: số lượng yêu cầu, số lỗi (phân theo lớp trạng thái), phần trăm độ trễ (p50, p95, p99), số yêu cầu đang xử lý, và độ trễ phụ thuộc cho DB và các cuộc gọi bên thứ ba chính.

Để giữ metrics đồng bộ với traces, dùng cùng mẫu route và tên. Nếu spans của bạn dùng /users/{id}, metrics cũng nên như vậy. Khi một biểu đồ hiện “p95 cho /checkout tăng”, bạn có thể nhảy thẳng vào traces lọc theo route đó.

Cẩn thận với label (attribute). Một label tệ có thể làm chi phí tăng vọt và dashboard trở nên vô dụng. Mẫu route, phương thức, lớp trạng thái và tên dịch vụ thường an toàn. ID người dùng, email, URL đầy đủ và thông điệp lỗi thô thường không an toàn.

Thêm vài metrics tùy theo nghiệp vụ quan trọng (ví dụ checkout started/completed, lỗi thanh toán theo nhóm mã kết quả, job nền thành công vs retry). Giữ tập nhỏ và loại bỏ những gì bạn không dùng.

Xuất telemetry và triển khai an toàn

Export là nơi OpenTelemetry trở nên thực tế. Dịch vụ của bạn phải gửi spans, metrics và logs tới nơi đáng tin cậy mà không làm chậm các request.

Cho phát triển cục bộ, giữ đơn giản. Một console exporter (hoặc OTLP tới collector cục bộ) cho phép bạn xem nhanh traces và kiểm tra tên span cùng attribute. Trong production, ưu tiên OTLP tới agent hoặc OpenTelemetry Collector gần dịch vụ. Nó giúp bạn có một nơi duy nhất để xử lý retry, routing và lọc.

Batching quan trọng. Gửi telemetry theo lô trong khoảng thời gian ngắn, với timeout chặt để mạng bị tắc không chặn app. Telemetry không nên là đường đi quan trọng. Nếu exporter không theo kịp, nó nên bỏ dữ liệu thay vì tích tụ trong bộ nhớ.

Sampling giữ chi phí ổn định. Bắt đầu với sampling head-based (ví dụ 1-10% yêu cầu), rồi thêm các quy tắc đơn giản: luôn sample lỗi, và luôn sample yêu cầu chậm vượt ngưỡng. Nếu bạn có job nền lưu lượng cao, sample ở tỷ lệ thấp hơn.

Triển khai theo bước nhỏ: dev với 100% sampling, staging với lưu lượng thực tế và sampling thấp hơn, rồi production với sampling thận trọng và cảnh báo khi exporter lỗi.

Sai lầm thường gặp làm hỏng end-to-end visibility

End-to-end visibility thường thất bại vì những lý do đơn giản: dữ liệu có đó, nhưng không kết nối.

Các vấn đề phá vỡ distributed tracing trong Go thường là:

• Mất context giữa các lớp. Handler tạo span, nhưng cuộc gọi DB, client HTTP hoặc goroutine dùng context.Background() thay vì context của request.
• Trả về lỗi mà không đánh dấu span. Nếu bạn không record lỗi và đặt status cho span, trace trông sẽ “xanh” ngay cả khi người dùng thấy 500.
• Instrument mọi thứ. Nếu mọi helper đều thành span, trace trở nên ồn ào và tốn kém hơn.
• Thêm attribute có cardinality cao. URL đầy đủ với ID, email, giá trị SQL thô, thân yêu cầu hoặc thông điệp lỗi thô có thể tạo ra hàng triệu giá trị duy nhất.
• Đánh giá hiệu năng bằng trung bình. Sự cố xuất hiện ở phần trăm (p95/p99) và tỷ lệ lỗi, không phải độ trễ trung bình.

Một kiểm tra nhanh là chọn một yêu cầu thực và theo dõi nó qua các ranh giới. Nếu bạn không thấy một trace ID chảy qua request inbound, truy vấn DB, cuộc gọi bên thứ ba và worker bất đồng bộ, bạn chưa có end-to-end visibility.

Checklist thực tế để coi là xong

Bạn gần hoàn thành khi có thể từ báo cáo người dùng đến chính xác yêu cầu, rồi theo nó qua mọi bước.

• Chọn một dòng log API và tìm trace chính xác bằng trace_id. Xác nhận các logs sâu hơn từ cùng yêu cầu (DB, HTTP client, worker) mang cùng context trace.
• Mở trace và xác minh lồng nhau: một HTTP server span ở trên cùng, với child spans cho các cuộc gọi DB và API bên thứ ba. Một danh sách phẳng thường nghĩa là context bị mất.
• Kích hoạt một job nền từ một yêu cầu API (ví dụ gửi biên nhận email) và xác nhận span worker kết nối ngược lại với yêu cầu.
• Kiểm tra metrics cho những cơ bản: số lượng yêu cầu, tỷ lệ lỗi và phần trăm độ trễ. Xác nhận bạn có thể lọc theo route hoặc thao tác.
• Quét attributes và logs để đảm bảo an toàn: không có mật khẩu, token, số thẻ tín dụng đầy đủ hay dữ liệu cá nhân thô.

Một bài kiểm tra thực tế đơn giản là mô phỏng checkout chậm khi nhà cung cấp thanh toán bị trễ. Bạn nên thấy một trace duy nhất với một span gọi ngoài được gắn nhãn rõ ràng, cùng một cú nhảy metric p95 cho route checkout.

Nếu bạn đang sinh backend Go (ví dụ với AppMaster), hữu ích khi biến checklist này thành một phần routine phát hành để các endpoint và worker mới giữ được trace khi ứng dụng lớn lên. AppMaster (appmaster.io) sinh các dịch vụ Go thực tế, nên bạn có thể chuẩn hóa một cài đặt OpenTelemetry và mang nó qua các dịch vụ và job nền.

Ví dụ: gỡ lỗi một checkout chậm qua các dịch vụ

Một khách hàng báo: “Checkout thỉnh thoảng bị treo.” Bạn không thể tái tạo ngay, và đó chính là lúc Go OpenTelemetry tracing phát huy.

Bắt đầu với metrics để hiểu dáng vấn đề. Nhìn vào lưu lượng yêu cầu, tỷ lệ lỗi và p95 hoặc p99 độ trễ cho endpoint checkout. Nếu sự chậm xảy ra theo đợt ngắn và chỉ cho một lát cắt các yêu cầu, thường chỉ ra một phụ thuộc, hàng đợi hoặc hành vi retry hơn là CPU.

Tiếp theo, mở một trace chậm trong cửa sổ thời gian đó. Một trace thường đủ. Một checkout khỏe mạnh có thể 300–600 ms end-to-end. Một yêu cầu xấu có thể 8–12 giây, với phần lớn thời gian ở trong một span duy nhất.

Một mẫu phổ biến trông như sau: handler API nhanh, công việc DB phần lớn ổn, rồi một span nhà cung cấp thanh toán hiển thị các lần thử lại với backoff, và một cuộc gọi hạ nguồn chờ sau một khóa hoặc hàng đợi. Phản hồi có thể vẫn trả 200, nên cảnh báo chỉ dựa trên lỗi sẽ không bật.

Logs tương quan sau đó cho bạn đường đi chính xác bằng ngôn ngữ rõ ràng: “retrying Stripe charge: timeout,” tiếp theo là “db tx aborted: serialization failure,” rồi “retry checkout flow.” Đó là dấu hiệu rõ ràng bạn đang đối mặt với vài vấn đề nhỏ kết hợp lại thành trải nghiệm người dùng tệ.

Khi bạn đã tìm ra nút thắt, tính nhất quán giữ mọi thứ đọc được theo thời gian. Chuẩn hóa tên span, attributes (hash user ID an toàn, order ID, tên phụ thuộc) và quy tắc sampling giữa các dịch vụ để mọi người đọc traces theo cùng một cách.