Vanus là một nền tảng sự kiện hiệu năng cao, được thiết kế để hỗ trợ kiến trúc hướng sự kiện (event-driven) trong môi trường phân tán. Để đảm bảo độ tin cậy và khả năng bảo trì, hệ thống tích hợp sẵn cơ chế quan sát toàn diện dựa trên ba trụ cột: Metrics, Tracing, và Logging. Bài viết này trình bày cách thiết lập và khai thác hệ thống truy vết end-to-end — từ việc phát sinh sự kiện tại nguồn đến khi được xử lý bởi người tiêu thụ — nhằm chẩn đoán nhanh, tối ưu hóa luồng dữ liệu và nâng cao tính minh bạch vận hành.

Cấu trúc Quan sát trong Vanus

Các thành phần quan sát được tổ chức theo mô-đun độc lập trong thư mục internal/telemetry, với mỗi lớp chịu trách nhiệm riêng:

• Đo lường hiệu năng: internal/telemetry/metrics — thu thập chỉ số thời gian thực bằng Prometheus exposition format.
• Truy vết phân tán: internal/telemetry/trace — tích hợp OpenTelemetry SDK để truyền ngữ cảnh qua HTTP headers và gRPC metadata.
• Ghi nhật ký có cấu trúc: internal/telemetry/logger — sử dụng định dạng JSON kèm trace ID và span ID để liên kết log với các bước trong chuỗi truy vết.

Kích hoạt Giám sát Chỉ Với Vài Dòng Cấu Hình

Mỗi dịch vụ trong Vanus (controller, store, gateway) chấp nhận cấu hình quan sát thông qua file YAML. Dưới đây là ví dụ cấu hình cho dịch vụ store:

telemetry:
  metrics:
    http_port: 2113
    endpoint: "/actuator/metrics"
    exporters:
      - prometheus
  trace:
    exporter:
      otlp:
        endpoint: "otel-collector:4317"
        insecure: true
    service_name: "vanus-store"
  log:
    level: "info"
    json: true
    rotation:
      max_size_mb: 100
      max_age_days: 7

Lưu ý: Các giá trị như http_port và service_name nên được điều chỉnh phù hợp với topology triển khai thực tế.

Chỉ Số Trọng Tâm Theo Thành Phần

Các chỉ số được đặt tên theo quy ước vanus_{component}_{metric_name}_{unit}, giúp dễ dàng phân nhóm và lập dashboard trong Grafana.

Thành phần Lưu trữ (Store)

• vanus_store_write_bytes_total: Tổng số byte đã ghi vào phân vùng lưu trữ.
• vanus_store_read_latency_seconds_bucket: Phân bố thời gian đọc theo histogram.
• vanus_store_wal_sync_duration_seconds_sum: Tổng thời gian đồng bộ WAL (Write-Ahead Log).

Thành phần Điều khiển (Controller)

• vanus_controller_topic_count: Số chủ đề đang được quản lý.
• vanus_controller_segment_split_count_total: Số lần phân chia phân đoạn do đạt ngưỡng kích thước.
• vanus_controller_subscription_active_gauge: Số đăng ký đang hoạt động (gauge thay vì counter).

Thành phần Kích hoạt (Trigger)

• vanus_trigger_filter_eval_duration_seconds: Thời gian trung bình đánh giá biểu thức lọc trên mỗi sự kiện.
• vanus_trigger_transform_failures_total: Số lần thất bại khi chuyển đổi định dạng sự kiện.
• vanus_trigger_dead_letter_enqueued_total: Số sự kiện bị đẩy vào hàng đợi chết sau hết hạn thử lại.

Triển Khai Truy Vết Phân Tán

Vanus sử dụng OpenTelemetry để tạo và lan truyền ngữ cảnh truy vết. Mỗi yêu cầu HTTP hoặc lệnh gRPC khởi tạo một Span gốc; các lời gọi nội bộ tiếp theo sẽ kế thừa TraceID và ParentSpanID.

Dưới đây là ví dụ mã nguồn trong hàm xử lý yêu cầu append sự kiện:

func (s *EventbusServer) Append(ctx context.Context, req *pb.AppendRequest) (*pb.AppendResponse, error) {
	// Khởi tạo span với tên và thuộc tính
	ctx, span := otel.Tracer("vanus.eventbus").Start(
		ctx,
		"eventbus.append",
		trace.WithAttributes(
			attribute.String("event.type", req.EventType),
			attribute.Int64("event.size.bytes", int64(len(req.Payload))),
		),
	)
	defer span.End()

	// Xử lý logic nghiệp vụ...
	result, err := s.store.Write(ctx, req.Payload)

	if err != nil {
		span.RecordError(err)
		span.SetStatus(codes.Error, err.Error())
	}

	return &pb.AppendResponse{Offset: result.Offset}, nil
}

Sau khi triển khai, dữ liệu truy vết sẽ xuất hiện trong giao diện Jaeger hoặc Tempo nếu được cấu hình làm backend.

Tối Ưu Hóa Hệ Thống Nhật Ký

Để đảm bảo tính khả dụng và khả năng phân tích, cần tuân thủ các nguyên tắc sau:

• Luôn ghi kèm trace_id và span_id trong mọi bản ghi log.
• Không ghi thông tin nhạy cảm (token, mật khẩu) vào log — sử dụng placeholder như [REDACTED].
• Sử dụng log level warn hoặc error cho các tình huống cần can thiệp thủ công; tránh dùng debug ở môi trường production.

Thiết Lập Cảnh Báo Tự Động

Một quy tắc cảnh báo mẫu trong Prometheus cho tỷ lệ lỗi cổng (gateway):

groups:
- name: vanus-gateway-alerts
  rules:
  - alert: GatewayErrorRateSurge
    expr: |
      (rate(vanus_gateway_http_errors_total{job="vanus-gateway"}[3m])
       /
       rate(vanus_gateway_http_requests_total{job="vanus-gateway"}[3m])) > 0.05
    for: 90s
    labels:
      severity: warning
    annotations:
      summary: "Tỷ lệ lỗi cổng tăng đột biến"
      description: "Tỷ lệ lỗi HTTP vượt 5% trong 90 giây liên tiếp."

Cảnh báo này nên được gửi tới kênh Slack hoặc email thông qua Alertmanager đã được cấu hình trước.