Đặc tả Kỹ thuật API

API Logger

LOG

Phiên bản	1.0
Base URL	https://api.example.com/v1
Hệ thống	Hệ thống Xác thực
Module	LOG - Logger
Ngày tạo	2026-08-05
Tác giả	Nam Nguyen
SRS liên quan	SRS Logger

Mục lục

1. Tổng quan
2. Định dạng Phản hồi
3. Endpoints
4. Mã lỗi

1. Tổng quan

1.1 Yêu cầu được giải quyết

Yêu cầu SRS	Endpoint API
FR-001 Thu thập Sự kiện Log	RabbitMQ consumer (nội bộ)
FR-002 Truy vấn Log	GET /logs, GET /logs/:id
FR-003 Phân tích Log	GET /logs/analytics
FR-004 Giám sát Thời gian thực	WebSocket /ws/logs

1.2 Xác thực

Tất cả endpoint yêu cầu xác thực JWT cấp admin.

2. Định dạng Phản hồi

2.1 Phản hồi Thành công

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req-abc-123",
    "timestamp": "2026-07-24T10:30:00Z"
  }
}

2.2 Phản hồi Lỗi

{
  "success": false,
  "error": {
    "code": "QUERY_FAILED",
    "message": "Không thể truy vấn log từ OpenSearch"
  }
}

3. Endpoints

3.1 Truy vấn Log

GET /logs FR-002

Truy vấn log với bộ lọc.

Tham số Query:

Tham số	Loại	Mô tả
level	string	Lọc theo mức độ: debug, info, warn, error
source	string	Lọc theo dịch vụ nguồn (auth, sms, v.v.)
action	string	Lọc theo hành động (login, register, v.v.)
userId	string	Lọc theo mã người dùng
traceId	string	Lọc theo mã truy vết
from	datetime	Thời gian bắt đầu (ISO 8601)
to	datetime	Thời gian kết thúc (ISO 8601)
search	string	Tìm kiếm toàn văn trong message
page	int	Số trang (mặc định: 1)
limit	int	Số kết quả mỗi trang (mặc định: 20, tối đa: 100)

Phản hồi 200:

{
  "success": true,
  "data": [
    {
      "eventId": "evt-uuid-123",
      "source": "auth",
      "level": "info",
      "action": "login",
      "message": "Người dùng đã đăng nhập thành công",
      "userId": "user-uuid-456",
      "traceId": "trace-uuid-789",
      "timestamp": "2026-07-24T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1500,
    "totalPages": 75
  }
}

GET /logs/:eventId

Lấy sự kiện log theo mã.

Phản hồi 200:

{
  "success": true,
  "data": {
    "eventId": "evt-uuid-123",
    "source": "auth",
    "level": "info",
    "action": "login",
    "message": "Người dùng đã đăng nhập thành công",
    "input": "{\"email\":\"[email protected]\"}",
    "output": "{\"userId\":\"123\",\"token\":\"...\"}",
    "userId": "user-uuid-456",
    "traceId": "trace-uuid-789",
    "timestamp": "2026-07-24T10:30:00Z"
  }
}

3.2 Phân tích

GET /logs/analytics FR-003

Lấy tổng hợp phân tích log.

Tham số Query:

Tham số	Loại	Mô tả
from	datetime	Thời gian bắt đầu
to	datetime	Thời gian kết thúc
interval	string	Khoảng tổng hợp: minute, hour, day

Phản hồi 200:

{
  "success": true,
  "data": {
    "totalEvents": 150000,
    "byLevel": {
      "info": 120000,
      "warn": 25000,
      "error": 5000
    },
    "bySource": {
      "auth": 100000,
      "sms": 50000
    },
    "timeline": [
      { "timestamp": "2026-07-24T10:00:00Z", "count": 500 },
      { "timestamp": "2026-07-24T11:00:00Z", "count": 750 }
    ]
  }
}

3.3 Phát trực tuyến Thời gian thực

WebSocket /ws/logs FR-004

Phát trực tuyến log thời gian thực qua WebSocket.

Kết nối:

ws://api.example.com/ws/logs?token=jwt_token&level=error&source=auth

Định dạng Tin nhắn:

{
  "type": "log",
  "data": {
    "eventId": "evt-uuid-123",
    "source": "auth",
    "level": "error",
    "message": "Đăng nhập thất bại",
    "timestamp": "2026-07-24T10:30:00Z"
  }
}

4. Mã lỗi

HTTP Status	Mã lỗi	Mô tả
400	VALIDATION_ERROR	Tham số query không hợp lệ
401	UNAUTHORIZED	Yêu cầu xác thực admin
404	LOG_NOT_FOUND	Không tìm thấy sự kiện log
500	QUERY_FAILED	Không thể truy vấn OpenSearch
503	OPENSEARCH_UNAVAILABLE	OpenSearch bị tắt