logbrew-flask 0.1.6 trở lên. Gói này ghi nhận span của yêu cầu và ngoại lệ
chưa xử lý. Logging handler tùy chọn nối log Python với trace của yêu cầu. Chỉ
số thời lượng yêu cầu cũng là tùy chọn.
Gói này cần Python 3.10 trở lên và Flask 3.1 trở lên.
Trong ứng dụng, dùng khóa gửi dữ liệu phía máy chủ theo phạm vi dự án. Không
dùng thông tin xác thực tài khoản mà CLI dùng.
<project_id>, <trace_id> và <issue_id> bằng ID lấy từ LogBrew. Dùng
một dự án phát triển cho các yêu cầu thử. Các ví dụ shell dùng Bash.
Gửi yêu cầu đầu tiên
1
Tạo hoặc chọn khóa dự án
Đăng nhập bằng CLI. Sau đó dùng một dự án mới hoặc một
dự án đã có. Đừng chạy cả hai ví dụ. Với dự án mới, lưu khóa gửi dữ liệu
của nó vào một tệp mới mà chỉ chủ sở hữu truy cập được:Với dự án đã có, lấy ID của dự án từ CLI lưu khóa gửi dữ liệu với quyền chỉ chủ sở hữu truy cập. CLI không in
khóa hay đường dẫn tệp. Trong production, dùng trình quản lý secret của nền
tảng triển khai thay cho tệp cục bộ này.Nếu không rõ yêu cầu tạo đã thành công hay chưa, chạy lại đúng lệnh đó.
logbrew projects --json. Sau đó tạo
một khóa phía máy chủ riêng:2
Cài đặt bản tích hợp đã phát hành
Tạo hoặc kích hoạt môi trường ảo của ứng dụng, rồi cài gói dành cho
framework. Gói này tự cài SDK lõi tương thích làm phụ thuộc.
3
Cấu hình danh tính triển khai
Nạp khóa dự án trên máy cục bộ mà không in ra. Đặt dịch vụ, môi trường và
bản phát hành ổn định để mọi tín hiệu đều có ngữ cảnh triển khai hữu ích.
init_logbrew() kiểm tra các đối số truyền trực tiếp trước, sau đó đến cấu
hình ứng dụng Flask, rồi đến các biến môi trường này. Nếu chưa cấu hình tên
dịch vụ, hàm này dùng import name của Flask.4
Khởi tạo Flask một lần
Với ứng dụng mới, lưu ví dụ thành Gọi
app.py. Thêm phần khởi tạo sau khi tạo
ứng dụng Flask. Logging handler là tùy chọn. Handler này giúp log của ứng
dụng dùng chung trace và span của yêu cầu đang hoạt động.init_logbrew(app) nhiều lần vẫn trả về cùng một extension Flask. Các
lần gọi đó không cài trùng hook cho yêu cầu hoặc ngoại lệ. Phần khởi tạo
không thêm logging handler. Thêm handler vào logger của ứng dụng một lần.5
Chạy một yêu cầu
Khởi động ứng dụng và gọi route từ một terminal khác. Thay Việc gửi dữ liệu chạy trên một worker nền, nên phản hồi không phải chờ.
app trong lệnh
nếu ứng dụng của bạn dùng tên module khác.6
Xác minh bằng chứng đã lưu trên LogBrew
Đọc đúng phạm vi dự án và triển khai. Tìm trace của yêu cầu health và log
tương quan từ logging handler trong ví dụ.Chép trace ID trả về vào lệnh điều tra có giới hạn:Kết quả đọc khớp xác nhận rằng LogBrew đã lưu tín hiệu. Phản hồi
200 trên
máy cục bộ chỉ chứng minh rằng Flask đã xử lý yêu cầu.Chọn tín hiệu bạn cần
Phần khởi tạo bật sẵn trace của yêu cầu và ghi nhận ngoại lệ chưa xử lý. Chỉ số yêu cầu và chuyển tiếp log Python là các lựa chọn riêng.
Bắt đầu với các giá trị mặc định. Thêm chỉ số yêu cầu khi cần xem độ trễ. Chỉ
thêm logging handler vào những logger giúp ích cho việc điều tra.
Theo mặc định, phần khởi tạo tự quản lý một transport HTTP. Transport này đưa
từng sự kiện vào hàng đợi, và một worker nền bắt đầu gửi ngay khi có một sự kiện
trong hàng đợi. Việc gửi không làm phản hồi phải chờ. Lỗi transport không làm hỏng
phản hồi của Flask.
flush_on_response=True thay vào đó gửi các sự kiện trong hàng đợi trên đường
xử lý phản hồi. Khi dùng tùy chọn đó, raise_flush_errors=True sẽ ném ra lỗi gửi
dữ liệu. Chỉ dùng cả hai cho một lần chẩn đoán có kiểm soát.
Kiểm soát nội dung log
Thêm mộtLogBrewLoggingHandler vào logger tạo ra các thông điệp bạn cần.
Handler này không thay thế handler console hoặc handler tệp của ứng dụng. Nó
không patch Flask hay module logging của Python. Thêm cùng một handler 2 lần sẽ
làm log bị trùng. Nếu ứng dụng cũng dùng root logger, kiểm tra cơ chế
propagation trước khi gắn handler thứ hai.
Log ghi bên trong một yêu cầu kế thừa trace và span đang hoạt động. Log ghi bên
ngoài yêu cầu không có trace của yêu cầu.
Handler gửi thông điệp đã định dạng, tên logger và mức log LogBrew. Handler cũng
gửi tên tệp nguồn, module, hàm, dòng, tên thread và tên tiến trình, nhưng không
gửi đường dẫn đầy đủ của tệp nguồn. Các giá trị nguyên thủy trong extra={...}
trở thành metadata. Xem lại các giá trị đó trước khi ghi log từ một yêu cầu của
người dùng.
Bản ghi DEBUG của Python trở thành info trong LogBrew. WARNING trở thành
warning, và CRITICAL trở thành critical. Tên và số của mức log gốc trong
Python được giữ trong metadata. Để gửi ít bản ghi hơn, đặt mức riêng cho
handler, chẳng hạn
LogBrewLoggingHandler(logbrew.client, level=logging.WARNING).
Console và LogBrew có thể nhận cùng một bản ghi. Ví dụ, cấu hình console trước
khi tạo ứng dụng Flask:
exc_info chứa kiểu và thông điệp của ngoại lệ. Toàn bộ nội dung
ngoại lệ chỉ được gửi khi handler có include_exception_text=True. Việc này
tách biệt với tính năng tự động ghi nhận ngoại lệ, vốn không bao giờ gửi
thông điệp của ngoại lệ. Không đưa thông tin xác thực, dữ liệu cá nhân hoặc body của
yêu cầu vào thông điệp log hay thông điệp ngoại lệ.
Những gì tích hợp ghi nhận
Tên span gồm phương thức HTTP và mẫu route đã khớp. Ví dụ,
/orders/100 và
/orders/200 dùng chung tên GET /orders/<int:order_id>. Yêu cầu không khớp
route nào dùng nhãn cố định <unmatched>. Nếu traceparent bị thiếu hoặc không
hợp lệ, một trace mới sẽ được bắt đầu.
Metadata của span chứa phương thức, mẫu route, endpoint, mã trạng thái và thời lượng.
Metadata không chứa đường dẫn cụ thể hay query string.
Từ 0.1.6 trở lên, span của yêu cầu bao trọn toàn bộ quá trình dispatch của
Flask. Hook before-request, error handler và teardown dùng chung trace của yêu
cầu. Với phản hồi dạng stream, span kết thúc khi body hoàn tất hoặc bị đóng.
Kiểm tra việc ghi nhận ngoại lệ
Trạng thái4xx hoặc 5xx xuất hiện trên span của yêu cầu. Riêng trạng thái đó
không chứng minh rằng đã có ngoại lệ. Đọc cả trace và vấn đề trước khi chẩn đoán
lỗi. LogBrew không thay thế error handler của Flask và không đổi trạng thái phản
hồi.
Trong một dự án phát triển, thêm một route tạm thời. Gọi route đó một lần. Xóa
nó trước khi triển khai:
500. Tìm vấn đề mới và chỉ số yêu cầu:
local capture check.
Nối công việc gửi ra ngoài với yêu cầu
SDK Python có các helper do ứng dụng tự gọi chorequests, urllib, httpx,
aiohttp, cơ sở dữ liệu, cache và hàng đợi. Mỗi helper tạo một span con trong
trace của yêu cầu đang hoạt động. SDK không patch toàn cục các thư viện này.
Gói logbrew-flask có ví dụ.
Đặt cho mỗi helper một tên thao tác ổn định và một mẫu route hoặc mẫu câu lệnh.
Không đưa ID bản ghi, giá trị của khách hàng, giá trị bind SQL hoặc payload của
message vào các tên đó. Chỉ thêm span con ở những chỗ mà phụ thuộc đó quan trọng
với yêu cầu. Tạo span cho mọi lệnh gọi nhỏ sẽ làm trace khó đọc hơn. Helper HTTP
gửi ra ngoài thêm một header W3C traceparent. Chúng không ghi nhận URL đầy đủ,
query string, body, cookie hoặc header tùy ý. Helper cho cơ sở dữ liệu, cache và
hàng đợi không ghi nhận giá trị bind, kết quả, giá trị cache hoặc payload của
hàng đợi.
Quyền riêng tư và vòng đời tiến trình
Tính năng tự động ghi nhận của Flask lược bỏ đường dẫn yêu cầu cụ thể, query string, body của yêu cầu và phản hồi, cookie, header tùy ý, giá trịtraceparent thô, baggage và tracestate.
Tính năng tự động ghi nhận ngoại lệ không bao giờ đọc hoặc gửi str(error). Nó
dùng bản tóm tắt cố định Unhandled exception và đánh dấu mọi thông điệp trong
chuỗi ngoại lệ là đã che. Các khung ngăn xếp chứa tên tệp (không kèm thư mục) và
thông tin nhận diện mã có giới hạn. Chúng không chứa văn bản traceback thô, mã
nguồn, biến cục bộ hay đường dẫn tuyệt đối.
Tạo ứng dụng và client LogBrew bên trong từng tiến trình worker. Cách mặc định
của Gunicorn là nạp ứng dụng riêng cho từng worker, và cách này hoạt động tốt.
Không dùng --preload của Gunicorn với client được tạo trong tiến trình cha.
Với uWSGI, dùng cách nạp ứng dụng theo từng worker, chẳng hạn --lazy-apps.
Client Python không cho phép dùng lại sau khi tiến trình fork.
Gọi logbrew.client.shutdown() từ hook tắt worker của trình quản lý tiến trình.
Lệnh này gửi các sự kiện còn lại trong hàng đợi và đóng client. Không gọi lệnh
này sau mỗi yêu cầu. Sau khi tắt, client từ chối sự kiện mới từ worker đó.
Phản hồi có thể hoàn tất trước khi worker gửi xong các sự kiện cuối cùng trong
hàng đợi. Khi triển khai hoặc giảm quy mô, việc tắt tiến trình đúng
cách (graceful shutdown) cho các sự kiện đó thêm một lần gửi cuối.
Khắc phục lỗi thiết lập
Với lỗi truy cập tài khoản, lỗi khóa và lỗi đọc lại, xem
Khắc phục sự cố. Với các runtime khác, xem
Tích hợp SDK.
