Thiết kế Structured Logging và Correlation ID cho Backend nhiều dịch vụ

Khi một request đi qua API gateway, ba service, cache, database và hàng đợi, một dòng log “đã xảy ra lỗi” gần như không giúp điều tra. Đội vận hành cần ghép đúng các sự kiện thuộc cùng một luồng, biết lỗi xuất hiện ở bước nào và tìm được bằng truy vấn ổn định. Structured logging giải quyết phần hình dạng dữ liệu; correlation ID và trace context giải quyết phần liên kết. Hai cơ chế phải được thiết kế như một hợp đồng chung, không phải vài chuỗi được nối tùy hứng trong từng service.

Bài viết này trình bày một thiết kế thực dụng cho backend nhiều dịch vụ: chọn định danh, chuẩn hóa schema JSON, truyền ngữ cảnh qua HTTP và message queue, gắn log với distributed trace, kiểm soát dữ liệu nhạy cảm, giới hạn cardinality, đặt chính sách sampling và kiểm thử đường đi đầu cuối. Mục tiêu là tạo log có thể tìm kiếm khi production gặp sự cố nhưng vẫn an toàn, có chi phí dự đoán được và không khóa chặt hệ thống vào một nhà cung cấp.

1. Phân biệt request ID, correlation ID, trace ID và span ID

Các tên này thường bị dùng lẫn nhau, dẫn đến middleware ghi một ID còn client HTTP lại truyền ID khác. Request ID thường nhận diện một lần nhận request tại một hop. Reverse proxy có thể tạo ID mới khi request đến. Correlation ID là khái niệm nghiệp vụ rộng hơn, dùng để nối nhiều hành động liên quan như một lần đặt hàng gồm HTTP request, job nền và webhook. Trace ID nhận diện toàn bộ trace phân tán; span ID nhận diện một thao tác cụ thể bên trong trace.

Một hệ thống nhỏ có thể dùng trace ID làm khóa tìm log chính. Hệ thống có workflow kéo dài nhiều giờ vẫn cần correlation ID nghiệp vụ vì một workflow có thể tạo nhiều trace độc lập. Không dùng order ID, email hay số điện thoại làm correlation ID: chúng vừa có ý nghĩa nghiệp vụ dễ đoán, vừa tăng rủi ro lộ dữ liệu. ID tương quan nên là giá trị ngẫu nhiên không chứa thông tin người dùng.

2. Định nghĩa schema log trước khi chọn thư viện

Structured logging không chỉ là xuất JSON. Nếu service A dùng requestId, service B dùng request_id, còn service C đặt toàn bộ context trong chuỗi message, hệ thống vẫn khó truy vấn. Hãy xuất bản một schema tối thiểu có kiểu dữ liệu, quy tắc đặt tên và ý nghĩa rõ ràng. Thư viện của từng ngôn ngữ chỉ là lớp triển khai hợp đồng đó.

{
  "timestamp": "2026-09-21T14:20:31.482Z",
  "level": "error",
  "service": "checkout-api",
  "environment": "production",
  "event": "payment_authorization_failed",
  "message": "Payment authorization failed",
  "request_id": "req_01K5...",
  "correlation_id": "cor_01K5...",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "http_method": "POST",
  "route": "/v1/orders/{id}/pay",
  "status_code": 502,
  "duration_ms": 384,
  "error_type": "UpstreamTimeout",
  "retryable": true
}

event nên là mã máy đọc ổn định; message là câu dành cho người đọc và có thể thay đổi. Dùng route đã chuẩn hóa thay vì URL thật có ID để tránh cardinality tăng vô hạn. Giữ số ở dạng số, boolean ở dạng boolean, timestamp theo UTC có timezone, và tránh JSON lồng quá sâu. Khi schema thay đổi không tương thích, thêm schema_version và lập kế hoạch chuyển đổi truy vấn/dashboard.

Các field nền nên được logger gắn tự động: service, phiên bản deploy, môi trường, region và định danh tiến trình. Các field theo request nên đến từ context bất biến. Lập trình viên chỉ cần cung cấp event, kết quả và vài thuộc tính miền cần thiết. Cách này giảm lỗi chính tả, ngăn ghi đè field chuẩn và giúp review code tập trung vào ý nghĩa sự kiện.

3. Tạo và tiếp nhận context tại ranh giới HTTP

Tại điểm vào đáng tin cậy đầu tiên, middleware đọc trace context theo chuẩn, kiểm tra header correlation nếu tổ chức có dùng, rồi tạo giá trị mới khi thiếu hoặc không hợp lệ. Không chấp nhận chuỗi dài tùy ý do client gửi; header không được trở thành kênh log injection hoặc làm tăng chi phí lưu trữ. Giới hạn độ dài, bộ ký tự và số header, sau đó đưa giá trị đã chuẩn hóa vào request context.

function onIncomingRequest(request) {
  trace = tracer.extractValidatedContext(request.headers)
  correlationId = validateId(request.header("x-correlation-id"))
    ? request.header("x-correlation-id")
    : generateRandomId()

  context = new RequestContext(
    requestId = generateRandomId(),
    correlationId = correlationId,
    traceId = trace.traceId,
    spanId = trace.spanId
  )

  return runWithContext(context, () => next(request))
}

W3C Trace Context định nghĩa traceparent để mang version, trace ID, parent ID và trace flags; tracestate dành cho trạng thái riêng của nhà cung cấp. Hãy để SDK tracing parse và tạo các header này thay vì tự cắt chuỗi. Trace header phục vụ tương quan quan sát, không chứng minh danh tính hay quyền hạn; authorization vẫn phải dựa trên credential hợp lệ.

Có thể trả một request ID an toàn trong response để bộ phận hỗ trợ nhận từ người dùng. Không nhất thiết trả toàn bộ trace context, thông tin topology hoặc tên service nội bộ. Khi qua trust boundary, cân nhắc tạo trace mới hoặc chỉ chuyển tập field đã phê duyệt theo chính sách bảo mật.

4. Truyền context qua lời gọi outbound mà không làm rò rỉ dữ liệu

Mọi HTTP/gRPC client dùng chung nên có interceptor tự động inject trace context và correlation ID đã cho phép. Nếu từng lập trình viên phải nhớ thêm header ở mỗi lời gọi, hệ thống chắc chắn sẽ có trace đứt. Đồng thời phải có danh sách đích tin cậy: không gửi baggage nội bộ, tenant metadata hoặc ID người dùng sang API bên thứ ba chỉ vì cùng dùng một HTTP client.

OpenTelemetry mô tả baggage là dữ liệu key-value đi cùng context và có thể được đưa vào span, metric hoặc log. Sự tiện lợi này cũng tạo rủi ro lan truyền: một giá trị thêm ở gateway có thể đi qua nhiều service và ra ngoài biên. Chỉ cho phép các key đã duyệt, giới hạn kích thước, không đặt token, API key, email hay dữ liệu cá nhân vào baggage, và không tự động chép toàn bộ baggage vào mọi dòng log.

• Inject traceparent/tracestate bằng instrumentation chuẩn.
• Truyền correlation ID riêng chỉ khi workflow cần và đích nằm trong ranh giới phù hợp.
• Đặt timeout cho outbound call và ghi outcome, latency, loại dependency thay vì payload.
• Không log nguyên Authorization, Cookie, query string hay body mặc định.
• Ghi tên operation ổn định, không ghi URL chứa ID động làm nhãn chính.

5. Message queue cần một vòng đời context rõ ràng

Async messaging là nơi correlation thường bị mất nhất. Producer cần inject context vào message metadata, không trộn nó vào payload nghiệp vụ nếu không phải một phần contract. Consumer extract context, tạo consumer span mới và mở logging scope cho đúng message. Với batch, mỗi message có thể có trace riêng; gắn cả batch vào một trace giả sẽ làm quan hệ nhân quả sai lệch.

producer.publish(payload, headers = {
  "traceparent": currentTraceParent(),
  "x-correlation-id": context.correlationId,
  "message-id": messageId
})

consumer.handle(message) {
  parent = tracer.extract(message.headers)
  startConsumerSpan(parent, "invoice.generate", () => {
    withLogContext({
      correlation_id: validatedCorrelation(message.headers),
      message_id: message.id,
      delivery_attempt: message.deliveryAttempt
    }, () => process(message))
  })
}

Retry phải giữ message_id hoặc business operation ID để nhận diện cùng một công việc, đồng thời mỗi lần xử lý có span riêng. Log cần phân biệt lần thử, kết quả và quyết định ack/nack/dead-letter. Khi tạo message mới vì một bước nghiệp vụ tiếp theo, giữ correlation ID nếu vẫn cùng workflow nhưng tạo message ID mới. Đối với scheduled job không có parent, tạo trace mới và dùng job execution ID làm khóa vận hành.

6. Logging scope phải sống đúng với concurrency model

Biến global chứa request ID sẽ gây trộn context giữa request đồng thời. Cần dùng cơ chế context-local của runtime: async-local storage, context variable, coroutine context hoặc request-scoped container. Khi đẩy việc sang thread pool, callback hay task nền, phải xác định framework có tự truyền context hay cần wrapper. Một dòng log đúng nội dung nhưng gắn trace ID của request khác còn nguy hiểm hơn dòng log thiếu ID.

Context cũng phải được dọn khi request kết thúc. Worker tái sử dụng process hoặc coroutine có thể làm ID cũ rò sang job sau nếu scope không đóng trong finally. Test concurrency nên chạy nhiều request có marker khác nhau, cố tình xen kẽ await và xác nhận không có log nào mang marker chéo.

Context propagation là một phần của tính đúng đắn, không chỉ là tiện ích quan sát. Sai context có thể dẫn đội vận hành điều tra nhầm khách hàng, nhầm giao dịch và nhầm nguyên nhân.

7. Thiết kế sự kiện lỗi để điều tra được nhưng không tạo nhiễu

Không cần log cùng một exception ở mọi tầng. Nếu repository log rồi service log rồi controller log, một lỗi sinh ba hoặc bốn sự kiện giống nhau và làm méo cảnh báo. Chọn một tầng sở hữu quyết định: tầng thấp có thể bọc lỗi với context kỹ thuật, tầng biên ghi một sự kiện hoàn chỉnh khi request thất bại. Nếu một tầng thực hiện retry hoặc fallback, nó có lý do riêng để ghi event cho quyết định đó.

Ghi error_type, mã lỗi ổn định, retryable, dependency, operation và stack trace tại điểm có ích. Không dùng toàn bộ message exception làm khóa nhóm vì nó thường chứa ID động. Lỗi do input dự kiến có thể là warn hoặc info tùy chính sách; lỗi bất biến hệ thống mới là error. Severity phải phản ánh hành động vận hành, không chỉ loại exception trong code.

8. Bảo vệ dữ liệu nhạy cảm ngay từ lúc sinh log

Redaction ở hệ thống thu thập là lớp phòng thủ bổ sung, không thay thế việc ứng dụng không ghi bí mật. Theo hướng dẫn OWASP, access token, password, session identifier, connection string, khóa mã hóa và dữ liệu cá nhân nhạy cảm thường không nên được ghi trực tiếp. Xây allowlist field có thể log, thêm filter tập trung cho header/body và kiểm thử bằng các chuỗi canary giống token.

Giá trị do người dùng cung cấp cần được sanitize để tránh ký tự xuống dòng hoặc delimiter tạo log injection. Với JSON logger, vẫn phải bảo đảm serializer escape đúng và log viewer không diễn giải nội dung như HTML. Phân quyền kho log, mã hóa, retention và audit truy cập phải tương xứng với độ nhạy của dữ liệu còn lại.

Khi cần liên kết một chủ thể mà không cần nhận dạng trực tiếp, có thể dùng pseudonymous ID ổn định trong phạm vi hẹp hoặc HMAC với khóa được quản lý. Hash trực tiếp email/số điện thoại thường dễ bị dò từ tập giá trị nhỏ. Thiết kế phải phối hợp với chính sách pháp lý, quyền xóa dữ liệu và thời gian lưu giữ của tổ chức.

9. Kiểm soát volume, cardinality và sampling

Structured logging làm truy vấn tốt hơn nhưng có thể tăng dung lượng. Log một sự kiện success cho mọi hàm nhỏ tạo chi phí lớn mà ít giá trị. Ưu tiên sự kiện tại ranh giới, thay đổi trạng thái, quyết định retry/fallback, lỗi và hành động bảo mật. Metric phù hợp hơn log cho số lượng request, tỷ lệ lỗi và phân phối latency; trace phù hợp hơn cho cây lời gọi chi tiết.

Sampling không nên làm mất toàn bộ lỗi hiếm. Có thể giữ 100% error/security event, lấy mẫu success theo tỷ lệ, và tăng sampling có điều kiện khi latency cao. Quyết định trace sampling và log sampling cần phối hợp: nếu log nói có trace ID nhưng trace đã bị loại, giao diện phải biểu đạt rõ thay vì coi là liên kết hỏng.

• Đặt ngân sách log theo service và theo event, theo dõi bytes/giây chứ không chỉ số dòng.
• Không index mọi field; chỉ index khóa được truy vấn thường xuyên và có cardinality kiểm soát.
• Giới hạn độ dài message, stack trace và mảng dữ liệu.
• Rate-limit sự kiện lặp lại nhưng vẫn có counter cho số lần bị gộp.
• Đặt retention khác nhau cho audit, security, application và debug log.

10. Truy vấn điều tra nên được thiết kế trước sự cố

Một schema chỉ hữu ích khi đội trực có truy vấn và dashboard đã thử. Bắt đầu từ request ID người dùng cung cấp, tìm entry ở gateway, lấy correlation ID/trace ID, rồi mở toàn bộ timeline sắp theo timestamp. Tiếp theo nhóm theo service, event, status và dependency để xác định điểm chuyển từ thành công sang lỗi.

correlation_id = "cor_01K5..."
| sort timestamp asc
| fields timestamp, service, event, level, duration_ms, error_type, span_id

Đồng hồ giữa máy có thể lệch, nên thứ tự log không phải lúc nào cũng chứng minh quan hệ nhân quả. Trace parent-child, message metadata và sequence trong cùng process đáng tin hơn cho việc dựng luồng. Đồng bộ thời gian vẫn cần thiết, nhưng runbook điều tra phải biết giới hạn này.

Tạo saved search cho các tình huống quen thuộc: dependency timeout, retry cạn, dead-letter, lỗi theo phiên bản deploy, correlation ID không hợp lệ và context propagation bị mất. Alert dựa trên tỷ lệ hoặc SLO thường tốt hơn cảnh báo theo một dòng error đơn lẻ.

11. Kiểm thử hợp đồng logging và propagation

Unit test xác nhận logger xuất đúng kiểu field và redaction chặn dữ liệu cấm. Integration test gửi request qua ít nhất hai service, một queue và một consumer rồi kiểm tra correlation ID được giữ, trace/span quan hệ đúng, request ID thay đổi theo hop nếu đó là chính sách. Test lỗi phải chứng minh stack trace có ích nhưng không chứa secret.

1. Gửi request không có header: gateway tạo ID hợp lệ và phản hồi request ID.
2. Gửi header quá dài hoặc có ký tự xuống dòng: hệ thống từ chối hoặc tạo lại, không ghi nguyên chuỗi.
3. Đi qua outbound HTTP: service sau nhận đúng trace context và correlation được cho phép.
4. Đẩy message rồi retry: message ID ổn định, attempt tăng, mỗi lần xử lý có span thích hợp.
5. Chạy nhiều request đồng thời: không có context chéo sau các điểm async.
6. Đưa token giả vào header/body: token không xuất hiện trong log nguồn lẫn kho tập trung.
7. Tắt collector: ứng dụng tiếp tục phục vụ theo chính sách, logger có buffer/backpressure hữu hạn.

Cuối cùng, chạy một bài diễn tập điều tra: chỉ cung cấp cho người trực một request ID và triệu chứng. Đo thời gian họ tìm được service lỗi, dependency liên quan và phiên bản deploy. Nếu phải SSH vào máy hoặc grep chuỗi thủ công trên nhiều nơi, hợp đồng quan sát vẫn chưa hoàn chỉnh.

Checklist triển khai production

• Có tài liệu phân biệt request ID, correlation ID, trace ID và span ID.
• Mọi service dùng cùng quy tắc tên field, kiểu dữ liệu, timestamp và event code.
• Middleware/interceptor tự động extract, validate, inject và đóng logging scope.
• HTTP, gRPC, queue và scheduled job đều có đường propagation được kiểm thử.
• Header từ bên ngoài bị giới hạn; trace/correlation không được dùng để xác thực.
• Secret, session ID và PII bị chặn tại ứng dụng; log input được sanitize.
• Cardinality, sampling, retention và ngân sách volume có owner và cảnh báo.
• Saved search nối log với trace hoạt động trước khi production gặp sự cố.

Thiết kế logging tốt biến một sự cố phân tán thành một timeline có thể kiểm chứng. Hãy bắt đầu từ schema tối thiểu, tự động hóa context propagation ở thư viện dùng chung, kiểm thử rò rỉ dữ liệu và concurrency, rồi mở rộng field khi có câu hỏi vận hành cụ thể. Nhiều log hơn không đồng nghĩa quan sát tốt hơn; điều quan trọng là mỗi sự kiện có cấu trúc ổn định, đúng ngữ cảnh và đủ an toàn để sử dụng lâu dài.

Tài liệu tham khảo

• W3C Trace Context
• OpenTelemetry: Context Propagation
• OpenTelemetry: Baggage
• OWASP Logging Cheat Sheet