Xử lý sự cố

Mục lục

Log không được ghi
Lỗi API Key
Giới hạn tốc độ
Lỗi mạng
Vấn đề hiệu suất
Vấn đề dữ liệu
Môi trường Serverless
Phương pháp Debug

Log không được ghi

Triệu chứng

Đã tích hợp SDK nhưng log không hiển thị trên dashboard.

Kiểm tra các điểm sau

Xác nhận API key đúng
Xác nhận bạn đang sử dụng API key bắt đầu bằng at-.
Xác nhận enabled=True
Kiểm tra xem enabled=False có được đặt khi khởi tạo không.
Xác nhận client đã được wrap
Xác nhận bạn đã wrap client OpenAI bằng tracer.wrap_openai().
Kiểm tra tên dự án
Xác nhận bạn đã chọn đúng dự án trên dashboard.

# Ví dụ cấu hình đúng
from aitracer import AITracer
from openai import OpenAI

tracer = AITracer(
    api_key="at-xxxx",       # ← Bắt đầu bằng at-
    project="my-project",
    enabled=True              # ← Phải là True
)

# Wrap client
client = tracer.wrap_openai(OpenAI())  # ← Không quên wrap

# Log sẽ được ghi
response = client.chat.completions.create(...)

Trường hợp chế độ bất đồng bộ

Trong chế độ bất đồng bộ mặc định, log được buffer trước khi gửi. Nếu bạn muốn kiểm tra log ngay lập tức, hãy gọi flush().

# Gửi log ngay lập tức
tracer.flush()

Lỗi API Key

Thông báo lỗi

Invalid API key hoặc Unauthorized

Cách giải quyết

Kiểm tra định dạng API key
Sử dụng key có định dạng đúng bắt đầu bằng at-.
Kiểm tra xem key có bị vô hiệu hóa không
Kiểm tra trạng thái key trong "Cài đặt" → "API Keys" trên dashboard.
Kiểm tra biến môi trường
Xác nhận biến môi trường AITRACER_API_KEY được đặt đúng.
Tạo lại key
Nếu vấn đề không được giải quyết, hãy tạo API key mới.

# Kiểm tra biến môi trường (Python)
import os
print(os.getenv("AITRACER_API_KEY"))  # Phải hiển thị at-xxxx

# Kiểm tra biến môi trường (Bash)
# echo $AITRACER_API_KEY

Giới hạn tốc độ

Thông báo lỗi

Rate limit exceeded hoặc 429 Too Many Requests

Cách giải quyết

Kiểm tra giới hạn gói
Kiểm tra xem bạn có đạt đến giới hạn log của gói hiện tại không.
Nâng cấp gói
Nếu đã đạt giới hạn, hãy nâng cấp lên gói cao hơn.
Xử lý tạm thời
SDK sẽ tự động retry, nhưng nếu gửi nhiều log, hãy tăng khoảng cách giữa các lần gửi.

Giới hạn log theo gói

Gói	Giới hạn log/tháng
Free	1,000
Starter	10,000
Pro	100,000
Enterprise	Không giới hạn

Lỗi mạng

Thông báo lỗi

Connection error, Timeout, Name resolution failed

Cách giải quyết

Kiểm tra kết nối Internet
Xác nhận bạn có thể kết nối đến api.aitracer.co.
Kiểm tra Firewall/Proxy
Nếu là mạng doanh nghiệp, xác nhận kết nối đến api.aitracer.co:443 được cho phép.
Kiểm tra cài đặt DNS
Xác nhận DNS có thể phân giải đúng.

# Kiểm tra kết nối (Bash)
curl -I https://api.aitracer.co/health

# Kiểm tra phân giải DNS
nslookup api.aitracer.co

Ảnh hưởng đến ứng dụng
Ngay cả khi xảy ra lỗi mạng, SDK sẽ không cản trở hoạt động của ứng dụng. Chỉ việc gửi log thất bại, còn lệnh gọi API LLM vẫn hoạt động bình thường.

Vấn đề hiệu suất

Triệu chứng

Cảm thấy ứng dụng chậm lại sau khi tích hợp AITracer.

Kiểm tra các điểm sau

Xác nhận đang sử dụng chế độ bất đồng bộ
Mặc định là chế độ bất đồng bộ (sync=False). Kiểm tra xem có đang ở chế độ đồng bộ không.
Ảnh hưởng dưới 3ms
Ảnh hưởng trong chế độ bất đồng bộ thường dưới 3ms. Nếu có độ trễ cao hơn, hãy điều tra nguyên nhân khác.

# Xác nhận không ở chế độ đồng bộ
tracer = AITracer(
    api_key="at-xxxx",
    sync=False  # ← Phải là False (mặc định)
)

# Chế độ đồng bộ không được khuyến nghị trừ môi trường serverless

Vấn đề dữ liệu

Số token bằng 0

Triệu chứng

Log được ghi nhưng số token hiển thị là 0.

Nguyên nhân

Một số nhà cung cấp LLM không bao gồm số token trong response. Ngoài ra, trong chế độ streaming, số token có thể không lấy được.

Chi phí không được tính

Triệu chứng

Chi phí hiển thị là 0 hoặc "-".

Nguyên nhân

Không lấy được số token
Tên model không được nhận dạng (trường hợp tên model tùy chỉnh)
Model mới chưa đăng ký thông tin giá

Trong trường hợp log thủ công, hãy chỉ định rõ input_tokens và output_tokens.

Môi trường Serverless

Triệu chứng

Log không được ghi hoặc chỉ được ghi một phần trên AWS Lambda / Cloud Functions / Vercel.

Cách giải quyết

Trong môi trường serverless, process có thể kết thúc trước khi buffer được gửi khi hàm kết thúc. Hãy thực hiện một trong các biện pháp sau.

Biện pháp 1: Sử dụng chế độ đồng bộ

tracer = AITracer(
    api_key="at-xxxx",
    sync=True  # ← Khuyến nghị True cho môi trường serverless
)

Biện pháp 2: Gọi flush() trước khi kết thúc

def handler(event, context):
    try:
        response = client.chat.completions.create(...)
        return {"statusCode": 200, "body": response}
    finally:
        tracer.flush()  # ← Luôn gọi

Ảnh hưởng đến Cold Start
Sử dụng chế độ đồng bộ sẽ thêm một chút latency cho mỗi request. Nếu hiệu suất quan trọng, hãy thử phương pháp sử dụng flush().

Phương pháp Debug

Bật debug log

import logging

# Đặt log level của AITracer thành DEBUG
logging.getLogger("aitracer").setLevel(logging.DEBUG)

# Thêm handler
handler = logging.StreamHandler()
handler.setLevel(logging.DEBUG)
logging.getLogger("aitracer").addHandler(handler)

Kiểm tra dữ liệu trước khi gửi

# Kiểm tra nội dung buffer (dùng cho debug)
print(tracer._buffer)  # Hiển thị internal buffer

# Kiểm tra thống kê
print(tracer.stats())  # Hiển thị số log đã gửi/thất bại

Nếu vẫn không giải quyết được

Vui lòng liên hệ Hỗ trợ với các thông tin sau.

Phiên bản SDK đang sử dụng
Phiên bản Python / PHP / Node.js đang sử dụng
Thông báo lỗi (screenshot hoặc văn bản)
Đoạn code gây ra vấn đề
Môi trường chạy (Local / AWS Lambda / GCP, v.v.)