Skip to main content
Dùng 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.
Thay <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ừ logbrew projects --json. Sau đó tạo một khóa phía máy chủ riêng:
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 đó.
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 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.
Gọi 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 app trong lệnh nếu ứng dụng của bạn dùng tên module khác.
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ờ.
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ột LogBrewLoggingHandler 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:
Console nhận văn bản đã định dạng. LogBrew giữ thông điệp, mức log, logger và metadata thành các trường riêng. Bản ghi log có 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ái 4xx 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:
Yêu cầu trả về trạng thái 500. Tìm vấn đề mới và chỉ số yêu cầu:
Kiểm tra dịch vụ, môi trường, bản phát hành, kiểu ngoại lệ và trace yêu cầu của vấn đề. Vấn đề không được chứa văn bản 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 cho requests, 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.