Appender là gì?

• Lịch sử hành động của người dùng.
• Lịch sử đơn hàng.
• Thay đổi trong giỏ hàng.
• Lịch sử đánh giá.
• Lượt xem nội dung.
• Dữ liệu người dùng hoạt động theo thời gian thực.

flowchart LR
    A[Bảng lịch sử] --> B[Đọc một lô dữ liệu mới]
    B --> C[Phân tích và chuẩn hóa]
    C --> D[Gom nhóm trong bộ nhớ]
    D --> E[Tăng record count]
    D --> F[Lưu thống kê theo ngày]
    E --> G[Lưu page token mới]
    F --> G

Cấu trúc bảng record count

ezy_data_record_counts

Cách appender đọc dữ liệu

SELECT *
FROM user_action_history
WHERE id > :last_page_token
ORDER BY id ASC
LIMIT 100;

Token hiện tại: 12.000
Lô vừa đọc:     12.001 → 12.100
Token mới:      12.100

Từ một hành động đến các chỉ số tổng hợp

page_view / ALL               +1
action_count / PAGE_VIEW      +1
device_type / MOBILE          +1
os_name / ANDROID             +1
browser_name / CHROME         +1
traffic_channel / SEARCH      +1
referrer_host / google.com    +1
domain_name / example.com     +1

Ngày
└── Tên chỉ số
    └── Loại bản ghi
        └── Giá trị cần tăng

{
  "2026-10-04": {
    "page_view": {
      "ALL": 75
    },
    "action_count": {
      "CLICK": 24,
      "SCROLL": 42
    },
    "device_type": {
      "MOBILE": 50,
      "DESKTOP": 25
    }
  }
}

Tăng giá trị trong record count

1. Tạo bản ghi nếu khóa tổng hợp chưa tồn tại.
2. Tăng record_count bằng giá trị vừa tính được.

INSERT INTO ezy_data_record_counts (
    data_name,
    record_type,
    record_count
)
VALUES (
    :data_name,
    :record_type,
    :increment
)
ON DUPLICATE KEY UPDATE
    record_count = record_count + :increment;

recordCountService.increment(
    statisticName,
    recordType,
    increment
);

• statisticName là tên ổn định của chỉ số.
• recordType là nhóm đã được chuẩn hóa.
• increment có thể là số dương hoặc âm tùy loại dữ liệu.

Phân biệt record count và thống kê theo ngày

Record count

page_view / ALL → 152.430

• Các KPI tổng quan.
• Số liệu toàn thời gian.
• Biểu đồ phân phối.
• Truy vấn cần tốc độ cao nhưng không cần chia theo ngày.

Thống kê theo ngày

2026-10-02 / page_view / ALL → 1.820
2026-10-03 / page_view / ALL → 2.130
2026-10-04 / page_view / ALL → 1.540

• Biểu đồ tăng trưởng.
• Lọc theo khoảng ngày.
• So sánh với kỳ trước.
• Tính tỷ lệ chuyển đổi theo ngày.

Xác định thời điểm thống kê

1. Thời điểm nghiệp vụ của hành động.
2. Thời điểm bản ghi được tạo.
3. Thời gian hiện tại nếu cả hai giá trị trên đều không có.

Tổng hợp khách duy nhất

• USER: ID của tài khoản đã đăng nhập.
• IP: địa chỉ IP đã được chuẩn hóa.

unique_visitor / USER +1

unique_visitor / IP +1

ngày + loại khách + giá trị định danh

Chuẩn hóa địa chỉ IP

203.0.113.10, 10.0.0.8

• Loại bỏ khoảng trắng.
• Kiểm tra độ dài tối đa.
• Chỉ chấp nhận ký tự hợp lệ của IPv4 hoặc IPv6.
• Bỏ qua nếu trống hoặc không hợp lệ.

Loại bỏ lưu lượng bot

• Lượt xem có thể được ghi vào nhóm thiết bị BOT.
• Hành động không được dùng để tính người dùng, thời gian tương tác và các chỉ số hành vi thông thường.
• Bot không được đưa vào lượng khách hoạt động như một người dùng thực.

Tổng hợp thời gian tương tác

action_time / <loại hành động> + thời gian tính bằng mili giây

Thời gian trung bình
    = Tổng thời gian hành động
    / Tổng lượt xem

engaged_view / ALL +1

Tổng hợp độ sâu cuộn trang

scroll_depth_sum / ALL          + phần trăm cuộn
scroll_depth_sample_count / ALL + 1

scroll_depth_sum = 180
scroll_depth_sample_count = 3

180 / 3 = 60%

Phân tích thiết bị và nguồn truy cập

• Loại thiết bị.
• Hệ điều hành.
• Tên trình duyệt.
• Phiên bản trình duyệt.
• Trình duyệt bên trong ứng dụng.
• Tên miền.
• Nguồn truy cập.
• Kênh truy cập.
• Website giới thiệu.

• Truy cập trực tiếp.
• Liên kết nội bộ.
• Công cụ tìm kiếm.
• Mạng xã hội.
• Website giới thiệu.

Giới hạn số nhóm khác nhau

• Phiên bản trình duyệt.
• Website giới thiệu.
• Tên nguồn truy cập.
• Tên miền.

Giá trị đã biết      → giữ nguyên nhóm
Giá trị mới hiếm gặp → gộp vào nhóm OTHER

browser_version / Chrome 140 → 8.500
browser_version / Firefox 142 → 1.200
browser_version / OTHER      → 315

Đánh dấu bản ghi đã xử lý

• Page token giúp đọc tiếp từ ID gần nhất.
• Dấu đã xử lý ngăn cùng một bản ghi bị cộng lại nếu token được nạp lại.
• Bản ghi chưa xử lý vẫn có thể được tìm thấy khi appender tiếp tục chạy.

Tổng hợp và lưu chỉ số
        ↓
Đánh dấu bản ghi đã xử lý
        ↓
Lưu page token mới

Tạo một appender tổng hợp mới

Đọc dữ liệu theo token

@Override
protected List<Event> getValueList(Long pageToken) {
    return eventRepository.findByIdGreaterThan(
        pageToken,
        100
    );
}

Chuyển dữ liệu nguồn thành dữ liệu xử lý

@Override
protected Event toDataRecord(Event value) {
    return value;
}

Gom và lưu số liệu

@Override
protected void addDataRecords(List<Event> records) {
    Map<StatisticKey, Long> increments = new HashMap<>();

    for (Event event : records) {
        StatisticKey key = new StatisticKey(
            resolveStatisticName(event),
            normalizeRecordType(event)
        );

        increments.merge(
            key,
            resolveIncrement(event),
            Long::sum
        );
    }

    increments.forEach((key, value) ->
        recordCountService.increment(
            key.getStatisticName(),
            key.getRecordType(),
            value
        )
    );
}

Trả về token mới

@Override
protected Long extractNewLastPageToken(
    List<Event> values,
    Long currentToken
) {
    return values.isEmpty()
        ? currentToken
        : values.get(values.size() - 1).getId();
}

Khai báo định danh ổn định

@Override
protected String getAppenderNamePrefix() {
    return "my_statistic";
}

@Override
protected Long defaultPageToken() {
    return 0L;
}

@Override
protected Class<Long> pageTokenType() {
    return Long.class;
}

Khởi động appender trong trang quản trị

Start

Stop

Restart

Reload

• Xóa record count cũ.
• Xóa thống kê theo ngày.
• Xóa dấu đã xử lý.
• Tự động xây dựng lại dữ liệu một cách an toàn.

Chu kỳ chạy

• Nó được phép chạy trên máy chủ hiện tại.
• Trạng thái của nó đang là started.

Theo dõi appender sau khi bật

1. Page token có tăng dần hay không.
2. Bảng lịch sử còn bản ghi chưa xử lý hay không.
3. Các dòng record count có được tạo đúng data_name và record_type không.
4. record_count có tăng tương ứng với dữ liệu đầu vào không.
5. Thống kê theo ngày có được ghi đúng ngày phát sinh không.
6. Log có lỗi phân tích dữ liệu hoặc cập nhật cơ sở dữ liệu không.
7. Dashboard có hiển thị các số tổng hợp vừa tạo không.

SELECT
    data_name,
    record_type,
    record_count
FROM ezy_data_record_counts
WHERE data_name LIKE 'ezyrating_statistic_%'
ORDER BY data_name, record_count DESC;

Tái tổng hợp dữ liệu

1. Dừng appender liên quan.
2. Xóa đúng các dòng tổng hợp thuộc chỉ số cần xây dựng lại.
3. Xóa thống kê theo ngày tương ứng nếu có.
4. Xóa dấu đã xử lý của nguồn dữ liệu nếu appender sử dụng cơ chế này.
5. Đưa page token về giá trị ban đầu.
6. Khởi động lại appender.
7. Theo dõi cho tới khi token bắt kịp dữ liệu mới nhất.

Xử lý các thay đổi trạng thái

• Được tạo: +1.
• Bị xóa: -1.
• Được cập nhật nội dung nhưng vẫn hoạt động: 0.

long change;

if (!previousActive && currentActive) {
    change = 1;
} else if (previousActive && !currentActive) {
    change = -1;
} else {
    change = 0;
}

Các nguyên tắc khi phát triển appender

• Nguồn dữ liệu phải có thứ tự phân trang ổn định.
• Token phải được cập nhật sau khi lưu dữ liệu thành công.
• Phép tăng record count phải mang tính nguyên tử.
• Dữ liệu nên được gom theo lô trước khi ghi.
• Giá trị dùng làm record_type phải được chuẩn hóa.
• Giá trị có số lượng biến thể không giới hạn phải có nhóm OTHER.
• Phải phân biệt thống kê toàn thời gian và thống kê theo ngày.
• Các đối tượng có trạng thái phải được tính theo mức thay đổi, không chỉ theo số sự kiện.
• Việc chạy lại phải có chiến lược chống cộng trùng.
• Không đổi tên appender hoặc quy ước khóa thống kê tùy tiện sau khi triển khai.

Kết luận