logging.handlers --- Trình xử lý ghi nhật ký

Source code: Lib/logging/handlers.py

Các trình xử lý hữu ích sau đây được cung cấp trong gói. Lưu ý rằng ba trong số các trình xử lý (StreamHandler, FileHandler và NullHandler) thực sự được xác định trong chính mô-đun logging nhưng đã được ghi lại ở đây cùng với các trình xử lý khác.

Trình xử lý luồng

Lớp StreamHandler, nằm trong gói logging lõi, gửi đầu ra ghi nhật ký tới các luồng như sys.stdout, sys.stderr hoặc bất kỳ đối tượng giống tệp nào (hoặc chính xác hơn là bất kỳ đối tượng nào hỗ trợ các phương thức write() và flush()).

class logging.StreamHandler(stream=None)

Trả về một phiên bản mới của lớp StreamHandler. Nếu stream được chỉ định, phiên bản sẽ sử dụng nó để ghi nhật ký đầu ra; nếu không, sys.stderr sẽ được sử dụng.

emit(record)

Nếu một trình định dạng được chỉ định, nó sẽ được sử dụng để định dạng bản ghi. Bản ghi sau đó được ghi vào luồng theo sau là terminator. Nếu có thông tin ngoại lệ, nó sẽ được định dạng bằng traceback.print_exception() và được thêm vào luồng.

flush()

Xóa luồng bằng cách gọi phương thức flush() của nó. Lưu ý rằng phương thức close() được kế thừa từ Handler và do đó không có đầu ra, do đó đôi khi có thể cần một lệnh gọi flush() rõ ràng.

setStream(stream)

Đặt luồng của phiên bản thành giá trị được chỉ định, nếu nó khác. Luồng cũ bị xóa trước khi luồng mới được thiết lập.

Tham số:

stream -- Luồng mà trình xử lý nên sử dụng.

Trả về:

luồng cũ, nếu luồng đã bị thay đổi hoặc None nếu không.

Added in version 3.7.

terminator

Chuỗi được dùng làm dấu kết thúc khi ghi bản ghi được định dạng vào luồng. Giá trị mặc định là '\n'.

Nếu bạn không muốn chấm dứt dòng mới, bạn có thể đặt thuộc tính terminator của phiên bản trình xử lý thành chuỗi trống.

Trong các phiên bản trước, bộ kết thúc được mã hóa cứng là '\n'.

Added in version 3.2.

Trình xử lý tệp

Lớp FileHandler, nằm trong gói logging lõi, gửi kết quả ghi nhật ký vào một tệp đĩa. Nó kế thừa chức năng đầu ra từ StreamHandler.

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Trả về một phiên bản mới của lớp FileHandler. Tệp được chỉ định sẽ được mở và sử dụng làm luồng để ghi nhật ký. Nếu mode không được chỉ định, 'a' sẽ được sử dụng. Nếu encoding không phải là None thì nó được dùng để mở file có mã hóa đó. Nếu delay là đúng thì việc mở tệp sẽ bị hoãn lại cho đến lần gọi đầu tiên tới emit(). Theo mặc định, tệp sẽ phát triển vô thời hạn. Nếu errors được chỉ định, nó sẽ được sử dụng để xác định cách xử lý lỗi mã hóa.

Thay đổi trong phiên bản 3.6: Ngoài các giá trị chuỗi, đối tượng Path cũng được chấp nhận cho đối số filename.

Thay đổi trong phiên bản 3.9: Tham số errors đã được thêm vào.

close()

Đóng tập tin.

emit(record)

Xuất bản ghi vào tập tin.

Lưu ý rằng nếu tệp bị đóng do tắt nhật ký khi thoát và chế độ tệp là 'w', bản ghi sẽ không được phát ra (xem bpo-42378).

NullHandler

Added in version 3.1.

Lớp NullHandler, nằm trong gói logging lõi, không thực hiện bất kỳ định dạng hoặc đầu ra nào. Về cơ bản, nó là một trình xử lý 'không hoạt động' để các nhà phát triển thư viện sử dụng.

class logging.NullHandler

Trả về một phiên bản mới của lớp NullHandler.

emit(record)

Phương pháp này không làm gì cả.

handle(record)

Phương pháp này không làm gì cả.

createLock()

Phương thức này trả về None cho khóa, vì không có I/O cơ bản nào cần được tuần tự hóa quyền truy cập.

Xem Định cấu hình ghi nhật ký cho thư viện để biết thêm thông tin về cách sử dụng NullHandler.

Đã xemFileHandler

Lớp WatchedFileHandler, nằm trong mô-đun logging.handlers, là một FileHandler theo dõi tệp mà nó đang đăng nhập. Nếu tệp thay đổi, nó sẽ bị đóng và mở lại bằng tên tệp.

Thay đổi tệp có thể xảy ra do sử dụng các chương trình như newsyslog và logrotate thực hiện xoay tệp nhật ký. Trình xử lý này, được thiết kế để sử dụng trong Unix/Linux, theo dõi tệp để xem liệu nó có thay đổi kể từ lần phát hành cuối cùng hay không. (Một tệp được coi là đã thay đổi nếu thiết bị hoặc nút của nó thay đổi.) Nếu tệp đã thay đổi, luồng tệp cũ sẽ bị đóng và tệp sẽ được mở để nhận luồng mới.

Trình xử lý này không thích hợp để sử dụng trong Windows, vì trong Windows, các tệp nhật ký mở không thể được di chuyển hoặc đổi tên - việc ghi nhật ký sẽ mở các tệp có khóa độc quyền - và do đó không cần trình xử lý như vậy. Hơn nữa, ST_INO không được hỗ trợ trên Windows; stat() luôn trả về 0 cho giá trị này.

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Trả về một phiên bản mới của lớp WatchedFileHandler. Tệp được chỉ định sẽ được mở và sử dụng làm luồng để ghi nhật ký. Nếu mode không được chỉ định, 'a' sẽ được sử dụng. Nếu encoding không phải là None thì nó được dùng để mở file có mã hóa đó. Nếu delay là đúng thì việc mở tệp sẽ bị hoãn lại cho đến lần gọi đầu tiên tới emit(). Theo mặc định, tệp sẽ phát triển vô thời hạn. Nếu errors được cung cấp, nó sẽ xác định cách xử lý lỗi mã hóa.

Thay đổi trong phiên bản 3.6: Ngoài các giá trị chuỗi, đối tượng Path cũng được chấp nhận cho đối số filename.

Thay đổi trong phiên bản 3.9: Tham số errors đã được thêm vào.

reopenIfNeeded()

Kiểm tra xem tập tin đã thay đổi chưa. Nếu có, luồng hiện có sẽ bị xóa và đóng và tệp được mở lại, thường là tiền thân để xuất bản ghi vào tệp.

Added in version 3.6.

emit(record)

Xuất bản ghi vào tệp, nhưng trước tiên hãy gọi reopenIfNeeded() để mở lại tệp nếu nó đã thay đổi.

Cơ sởXử lý xoay

Lớp BaseRotatingHandler, nằm trong mô-đun logging.handlers, là lớp cơ sở cho các trình xử lý tệp xoay, RotatingFileHandler và TimedRotatingFileHandler. Bạn không cần phải khởi tạo lớp này nhưng nó có các thuộc tính và phương thức mà bạn có thể cần ghi đè.

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

Các thông số như đối với FileHandler. Các thuộc tính là:

namer

Nếu thuộc tính này được đặt thành có thể gọi được, thì phương thức rotation_filename() sẽ ủy quyền cho thuộc tính có thể gọi này. Các tham số được truyền cho đối tượng có thể gọi được là các tham số được truyền cho rotation_filename().

Ghi chú

Hàm đặt tên được gọi khá nhiều lần trong quá trình chuyển đổi, vì vậy nó phải đơn giản và nhanh nhất có thể. Nó cũng phải trả về cùng một đầu ra mỗi lần cho một đầu vào nhất định, nếu không thì hành vi cuộn qua có thể không hoạt động như mong đợi.

Cũng cần lưu ý rằng cần cẩn thận khi sử dụng tên đặt tên để bảo toàn các thuộc tính nhất định trong tên tệp được sử dụng trong quá trình xoay. Ví dụ: RotatingFileHandler dự kiến ​​​​sẽ có một tập hợp các tệp nhật ký có tên chứa các số nguyên liên tiếp, để thao tác xoay hoạt động như mong đợi và TimedRotatingFileHandler xóa các tệp nhật ký cũ (dựa trên tham số backupCount được truyền tới trình khởi tạo của trình xử lý) bằng cách xác định các tệp cũ nhất cần xóa. Để điều này xảy ra, tên tệp phải có thể sắp xếp được bằng cách sử dụng phần ngày/giờ của tên tệp và người đặt tên cần phải tôn trọng điều này. (Nếu muốn một người đặt tên không tôn trọng sơ đồ này, thì nó sẽ cần được sử dụng trong lớp con của TimedRotatingFileHandler để ghi đè phương thức getFilesToDelete() để phù hợp với sơ đồ đặt tên tùy chỉnh.)

Added in version 3.3.

rotator

Nếu thuộc tính này được đặt thành có thể gọi được, thì phương thức rotate() sẽ ủy quyền cho thuộc tính có thể gọi này. Các tham số được truyền cho đối tượng có thể gọi được là các tham số được truyền cho rotate().

Added in version 3.3.

rotation_filename(default_name)

Sửa đổi tên tệp của tệp nhật ký khi quay.

Điều này được cung cấp để có thể cung cấp tên tệp tùy chỉnh.

Việc triển khai mặc định gọi thuộc tính 'namer' của trình xử lý, nếu nó có thể gọi được, hãy chuyển tên mặc định cho nó. Nếu thuộc tính không thể gọi được (mặc định là None), tên sẽ được trả về không thay đổi.

Tham số:

default_name -- Tên mặc định cho tệp nhật ký.

Added in version 3.3.

rotate(source, dest)

Khi xoay, hãy xoay nhật ký hiện tại.

Việc triển khai mặc định gọi thuộc tính 'rotator' của trình xử lý, nếu nó có thể gọi được, hãy chuyển các đối số nguồn và đích cho nó. Nếu thuộc tính không thể gọi được (mặc định là None), nguồn sẽ được đổi tên thành đích.

Tham số:

  • source -- Tên tập tin nguồn. Đây thường là tên tệp cơ sở, ví dụ: 'test.log'.

  • dest -- Tên tệp đích. Đây thường là nguồn được xoay sang, ví dụ: 'test.log.1'.

Added in version 3.3.

Lý do các thuộc tính tồn tại là để giúp bạn không phải phân lớp - bạn có thể sử dụng cùng một lệnh gọi cho các phiên bản RotatingFileHandler và TimedRotatingFileHandler. Nếu tên hoặc công cụ quay vòng có thể gọi đưa ra một ngoại lệ, thì điều này sẽ được xử lý theo cách tương tự như bất kỳ ngoại lệ nào khác trong lệnh gọi emit(), tức là thông qua phương thức handleError() của trình xử lý.

Nếu bạn cần thực hiện những thay đổi quan trọng hơn đối với quá trình xử lý xoay vòng, bạn có thể ghi đè các phương thức này.

Để biết ví dụ, hãy xem Sử dụng công cụ quay vòng và trình đặt tên để tùy chỉnh quá trình xử lý xoay vòng nhật ký.

Trình xử lý tệp xoay

Lớp RotatingFileHandler, nằm trong mô-đun logging.handlers, hỗ trợ xoay các tệp nhật ký đĩa.

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Trả về một phiên bản mới của lớp RotatingFileHandler. Tệp được chỉ định sẽ được mở và sử dụng làm luồng để ghi nhật ký. Nếu mode không được chỉ định, 'a' sẽ được sử dụng. Nếu encoding không phải là None thì nó được dùng để mở file có mã hóa đó. Nếu delay là đúng thì việc mở tệp sẽ bị hoãn lại cho đến lần gọi đầu tiên tới emit(). Theo mặc định, tệp sẽ phát triển vô thời hạn. Nếu errors được cung cấp, nó sẽ xác định cách xử lý lỗi mã hóa.

Bạn có thể sử dụng các giá trị maxBytes và backupCount để cho phép tệp rollover ở kích thước được xác định trước. Khi kích thước sắp vượt quá, tệp sẽ bị đóng và tệp mới sẽ được mở âm thầm để xuất. Rollover xảy ra bất cứ khi nào tệp nhật ký hiện tại có độ dài gần maxBytes; nhưng nếu một trong hai maxBytes hoặc backupCount bằng 0 thì việc chuyển đổi sẽ không bao giờ xảy ra, vì vậy, bạn thường muốn đặt backupCount thành ít nhất là 1 và có maxBytes khác 0. Khi backupCount khác 0, hệ thống sẽ lưu các tệp nhật ký cũ bằng cách thêm phần mở rộng '.1', '.2', v.v. vào tên tệp. Ví dụ: với backupCount là 5 và tên tệp cơ sở là app.log, bạn sẽ nhận được app.log, app.log.1, app.log.2, cho đến app.log.5. Tệp được ghi vào luôn là app.log. Khi tệp này được lấp đầy, nó sẽ được đóng và đổi tên thành app.log.1, và nếu các tệp app.log.1, app.log.2, v.v. tồn tại, thì chúng sẽ được đổi tên tương ứng thành app.log.2, app.log.3, v.v.

Thay đổi trong phiên bản 3.6: Ngoài các giá trị chuỗi, đối tượng Path cũng được chấp nhận cho đối số filename.

Thay đổi trong phiên bản 3.9: Tham số errors đã được thêm vào.

doRollover()

Có một rollover, như được mô tả ở trên.

emit(record)

Xuất bản ghi ra tệp, phục vụ cho việc chuyển đổi như mô tả trước đó.

shouldRollover(record)

Xem liệu bản ghi được cung cấp có khiến tệp vượt quá giới hạn kích thước đã định cấu hình hay không.

TimedRotatingFileHandler

Lớp TimedRotatingFileHandler, nằm trong mô-đun logging.handlers, hỗ trợ xoay các tệp nhật ký đĩa theo các khoảng thời gian nhất định.

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Trả về một phiên bản mới của lớp TimedRotatingFileHandler. Tệp được chỉ định sẽ được mở và sử dụng làm luồng để ghi nhật ký. Khi xoay nó cũng đặt hậu tố tên tệp. Việc xoay vòng diễn ra dựa trên tích của when và interval.

Bạn có thể sử dụng when để chỉ định loại interval. Danh sách các giá trị có thể có dưới đây. Lưu ý rằng chúng không phân biệt chữ hoa chữ thường.

Giá trị

Loại khoảng thời gian

Nếu/làm thế nào atTime được sử dụng

'S'

Giây

Đã bỏ qua

'M'

Phút

Đã bỏ qua

'H'

Giờ

Đã bỏ qua

'D'

Ngày

Đã bỏ qua

'W0'-'W6'

Ngày trong tuần (0=Thứ Hai)

Được sử dụng để tính thời gian tái đầu tư ban đầu

'midnight'

Lăn bánh vào lúc nửa đêm, nếu atTime không được chỉ định, nếu không thì vào thời điểm atTime

Được sử dụng để tính thời gian tái đầu tư ban đầu

Khi sử dụng xoay vòng theo ngày trong tuần, hãy chỉ định 'W0' cho Thứ Hai, 'W1' cho Thứ Ba, v.v. cho đến 'W6' cho Chủ Nhật. Trong trường hợp này, giá trị được chuyển cho interval không được sử dụng.

Hệ thống sẽ lưu các tệp nhật ký cũ bằng cách thêm phần mở rộng vào tên tệp. Các tiện ích mở rộng dựa trên ngày và giờ, sử dụng định dạng strftime %Y-%m-%d_%H-%M-%S hoặc phần đầu của định dạng đó, tùy thuộc vào khoảng thời gian chuyển đổi.

Khi tính toán thời gian chuyển tiếp tiếp theo lần đầu tiên (khi trình xử lý được tạo), thời gian sửa đổi cuối cùng của tệp nhật ký hiện có hoặc thời gian hiện tại được sử dụng để tính toán thời điểm xảy ra lần quay tiếp theo.

Nếu đối số utc là đúng, thời gian trong UTC sẽ được sử dụng; nếu không thì giờ địa phương sẽ được sử dụng.

Nếu backupCount khác 0 thì tối đa các tệp backupCount sẽ được giữ lại và nếu có nhiều tệp hơn được tạo khi quá trình chuyển đổi xảy ra thì tệp cũ nhất sẽ bị xóa. Logic xóa sử dụng khoảng thời gian để xác định tệp nào cần xóa, do đó, việc thay đổi khoảng thời gian có thể khiến các tệp cũ vẫn còn sót lại.

Nếu delay là đúng thì việc mở tệp sẽ bị trì hoãn cho đến lần gọi đầu tiên tới emit().

Nếu atTime không phải là None thì đó phải là một phiên bản datetime.time chỉ định thời gian trong ngày khi quá trình chuyển đổi xảy ra, đối với các trường hợp việc chuyển đổi được đặt diễn ra "vào lúc nửa đêm" hoặc "vào một ngày cụ thể trong tuần". Lưu ý rằng trong những trường hợp này, giá trị atTime được sử dụng một cách hiệu quả để tính toán chuyển đổi initial và các chuyển đổi tiếp theo sẽ được tính thông qua tính toán khoảng thời gian thông thường.

Nếu errors được chỉ định, nó sẽ được sử dụng để xác định cách xử lý lỗi mã hóa.

Ghi chú

Việc tính toán thời gian chuyển đổi ban đầu được thực hiện khi trình xử lý được khởi tạo. Việc tính toán thời gian rollover tiếp theo chỉ được thực hiện khi rollover xảy ra và rollover chỉ xảy ra khi phát ra đầu ra. Nếu điều này không được ghi nhớ, nó có thể dẫn đến một số nhầm lẫn. Ví dụ: nếu khoảng thời gian "mỗi phút" được đặt, điều đó không có nghĩa là bạn sẽ luôn thấy các tệp nhật ký có thời gian (trong tên tệp) cách nhau một phút; nếu trong quá trình thực thi ứng dụng, kết quả ghi nhật ký được tạo ra thường xuyên hơn một lần mỗi phút, then bạn có thể thấy các tệp nhật ký có thời gian cách nhau một phút. Mặt khác, nếu các thông báo ghi nhật ký chỉ được xuất ra cứ năm phút một lần (giả sử), thì sẽ có những khoảng trống về thời gian của tệp tương ứng với số phút không có đầu ra (và do đó không có chuyển đổi) xảy ra.

Thay đổi trong phiên bản 3.4: tham số atTime đã được thêm vào.

Thay đổi trong phiên bản 3.6: Ngoài các giá trị chuỗi, đối tượng Path cũng được chấp nhận cho đối số filename.

Thay đổi trong phiên bản 3.9: Tham số errors đã được thêm vào.

doRollover()

Có một rollover, như được mô tả ở trên.

emit(record)

Xuất bản ghi ra tệp, phục vụ cho việc di chuột qua như mô tả ở trên.

getFilesToDelete()

Trả về danh sách tên tệp cần bị xóa khi di chuột qua. Đây là các đường dẫn tuyệt đối của các tệp nhật ký sao lưu cũ nhất được trình xử lý ghi.

shouldRollover(record)

Xem liệu đã có đủ thời gian để quá trình chuyển đổi xảy ra hay không và nếu có, hãy tính thời gian chuyển đổi tiếp theo.

Trình xử lý ổ cắm

Lớp SocketHandler, nằm trong mô-đun logging.handlers, gửi đầu ra ghi nhật ký đến ổ cắm mạng. Lớp cơ sở sử dụng ổ cắm TCP.

class logging.handlers.SocketHandler(host, port)

Trả về một phiên bản mới của lớp SocketHandler nhằm giao tiếp với một máy từ xa có địa chỉ được cung cấp bởi host và port.

Thay đổi trong phiên bản 3.4: Nếu port được chỉ định là None, một ổ cắm tên miền Unix sẽ được tạo bằng cách sử dụng giá trị trong host - nếu không, ổ cắm TCP sẽ được tạo.

close()

Đóng ổ cắm.

emit()

Chọn từ điển thuộc tính của bản ghi và ghi nó vào ổ cắm ở định dạng nhị phân. Nếu có lỗi với ổ cắm, hãy âm thầm thả gói tin. Nếu kết nối bị mất trước đó, hãy thiết lập lại kết nối. Để giải nén bản ghi ở đầu nhận thành LogRecord, hãy sử dụng chức năng makeLogRecord().

handleError()

Xử lý lỗi xảy ra trong quá trình emit(). Nguyên nhân rất có thể là do mất kết nối. Đóng ổ cắm để chúng tôi có thể thử lại ở sự kiện tiếp theo.

makeSocket()

Đây là một phương thức xuất xưởng cho phép các lớp con xác định loại ổ cắm chính xác mà chúng muốn. Việc triển khai mặc định sẽ tạo một ổ cắm TCP (socket.SOCK_STREAM).

makePickle(record)

Chọn từ điển thuộc tính của bản ghi ở định dạng nhị phân với tiền tố độ dài và trả về nó sẵn sàng để truyền qua ổ cắm. Các chi tiết của hoạt động này tương đương với:

dữ liệu = dưa.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
trả về dữ liệu + dữ liệu

Lưu ý rằng dưa chua không hoàn toàn an toàn. Nếu lo ngại về bảo mật, bạn có thể muốn ghi đè phương pháp này để triển khai cơ chế an toàn hơn. Ví dụ: bạn có thể ký các dưa chua bằng HMAC và sau đó xác minh chúng ở đầu nhận hoặc ngoài ra, bạn có thể vô hiệu hóa việc bỏ chọn các đối tượng chung ở đầu nhận.

send(packet)

Gửi một chuỗi byte đã được chọn packet đến ổ cắm. Định dạng của chuỗi byte đã gửi được mô tả trong tài liệu dành cho makePickle().

Chức năng này cho phép gửi một phần, điều này có thể xảy ra khi mạng bận.

createSocket()

Cố gắng tạo một ổ cắm; khi thất bại, sử dụng thuật toán lùi theo cấp số nhân. Trong lần thất bại đầu tiên, trình xử lý sẽ loại bỏ tin nhắn mà nó đang cố gửi. Khi các tin nhắn tiếp theo được xử lý bởi cùng một phiên bản, nó sẽ không thử kết nối cho đến khi một thời gian trôi qua. Các tham số mặc định sao cho độ trễ ban đầu là một giây và nếu sau độ trễ đó mà kết nối vẫn không thể thực hiện được thì trình xử lý sẽ tăng gấp đôi độ trễ mỗi lần lên tối đa là 30 giây.

Hành vi này được kiểm soát bởi các thuộc tính xử lý sau:

  • retryStart (độ trễ ban đầu, mặc định là 1,0 giây).

  • retryFactor (hệ số nhân, mặc định là 2.0).

  • retryMax (độ trễ tối đa, mặc định là 30,0 giây).

Điều này có nghĩa là nếu trình nghe từ xa khởi động after thì trình xử lý đã được sử dụng, bạn có thể mất tin nhắn (vì trình xử lý thậm chí sẽ không thử kết nối cho đến khi hết thời gian trễ mà chỉ âm thầm bỏ tin nhắn trong khoảng thời gian trì hoãn).

DatagramHandler

Lớp DatagramHandler, nằm trong mô-đun logging.handlers, kế thừa từ SocketHandler để hỗ trợ gửi thông báo ghi nhật ký qua ổ cắm UDP.

class logging.handlers.DatagramHandler(host, port)

Trả về một phiên bản mới của lớp DatagramHandler nhằm giao tiếp với một máy từ xa có địa chỉ được cung cấp bởi host và port.

Ghi chú

Vì UDP không phải là giao thức phát trực tuyến nên không có kết nối liên tục giữa phiên bản của trình xử lý này và host. Vì lý do này, khi sử dụng ổ cắm mạng, việc tra cứu DNS có thể phải được thực hiện mỗi khi một sự kiện được ghi lại, điều này có thể gây ra một số độ trễ cho hệ thống. Nếu điều này ảnh hưởng đến bạn, bạn có thể tự tra cứu và khởi chạy trình xử lý này bằng cách sử dụng địa chỉ IP đã tra cứu thay vì tên máy chủ.

Thay đổi trong phiên bản 3.4: Nếu port được chỉ định là None, một ổ cắm tên miền Unix sẽ được tạo bằng cách sử dụng giá trị trong host - nếu không, ổ cắm UDP sẽ được tạo.

emit()

Chọn từ điển thuộc tính của bản ghi và ghi nó vào ổ cắm ở định dạng nhị phân. Nếu có lỗi với ổ cắm, hãy âm thầm thả gói tin. Để giải nén bản ghi ở đầu nhận thành LogRecord, hãy sử dụng chức năng makeLogRecord().

makeSocket()

Phương thức xuất xưởng của SocketHandler ở đây được ghi đè để tạo ổ cắm UDP (socket.SOCK_DGRAM).

send(s)

Gửi một chuỗi byte đã được chọn đến một ổ cắm. Định dạng của chuỗi byte đã gửi được mô tả trong tài liệu dành cho SocketHandler.makePickle().

SysLogHandler

Lớp SysLogHandler, nằm trong mô-đun logging.handlers, hỗ trợ gửi tin nhắn ghi nhật ký đến nhật ký hệ thống Unix từ xa hoặc cục bộ.

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

Trả về một phiên bản mới của lớp SysLogHandler nhằm giao tiếp với một máy Unix từ xa có địa chỉ được cung cấp bởi address dưới dạng bộ dữ liệu (host, port). Nếu address không được chỉ định, ('localhost', 514) sẽ được sử dụng. Địa chỉ được sử dụng để mở một ổ cắm. Một cách khác để cung cấp bộ dữ liệu (host, port) là cung cấp địa chỉ dưới dạng chuỗi, ví dụ: '/dev/log'. Trong trường hợp này, ổ cắm miền Unix được sử dụng để gửi tin nhắn tới nhật ký hệ thống. Nếu facility không được chỉ định, LOG_USER sẽ được sử dụng. Loại ổ cắm được mở phụ thuộc vào đối số socktype, mặc định là socket.SOCK_DGRAM và do đó sẽ mở ổ cắm UDP. Để mở ổ cắm TCP (để sử dụng với các trình nền nhật ký hệ thống mới hơn như rsyslog), hãy chỉ định giá trị socket.SOCK_STREAM. Nếu timeout được chỉ định, nó sẽ đặt thời gian chờ (tính bằng giây) cho các hoạt động của ổ cắm. Điều này có thể giúp ngăn chương trình bị treo vô thời hạn nếu không thể truy cập được máy chủ nhật ký hệ thống. Theo mặc định, timeout là None, nghĩa là không áp dụng thời gian chờ.

Lưu ý rằng nếu máy chủ của bạn không lắng nghe trên cổng UDP 514, SysLogHandler có thể không hoạt động. Trong trường hợp đó, hãy kiểm tra xem bạn nên sử dụng địa chỉ nào cho ổ cắm tên miền - địa chỉ này phụ thuộc vào hệ thống. Ví dụ: trên Linux nó thường là '/dev/log' nhưng trên OS/X nó thường là '/var/run/syslog'. Bạn sẽ cần kiểm tra nền tảng của mình và sử dụng địa chỉ thích hợp (bạn có thể cần thực hiện kiểm tra này trong thời gian chạy nếu ứng dụng của bạn cần chạy trên nhiều nền tảng). Trên Windows, bạn hầu như phải sử dụng tùy chọn UDP.

Ghi chú

Trên macOS 12.x (Monterey), Apple đã thay đổi hoạt động của trình nền nhật ký hệ thống của họ - nó không còn lắng nghe trên ổ cắm tên miền nữa. Vì vậy, bạn không thể mong đợi SysLogHandler hoạt động được trên hệ thống này.

Xem gh-91070 để biết thêm thông tin.

Thay đổi trong phiên bản 3.2: socktype đã được thêm vào.

Thay đổi trong phiên bản 3.14: timeout đã được thêm vào.

close()

Đóng ổ cắm vào máy chủ từ xa.

createSocket()

Cố gắng tạo một ổ cắm và nếu nó không phải là ổ cắm datagram, hãy kết nối nó với đầu kia. Phương thức này được gọi trong quá trình khởi tạo trình xử lý, nhưng nó không bị coi là lỗi nếu đầu bên kia không lắng nghe vào thời điểm này - phương thức sẽ được gọi lại khi phát ra một sự kiện, nếu không có ổ cắm tại thời điểm đó.

Added in version 3.11.

emit(record)

Bản ghi được định dạng và sau đó được gửi đến máy chủ nhật ký hệ thống. Nếu có thông tin ngoại lệ, nó sẽ được gửi đến máy chủ.

Thay đổi trong phiên bản 3.2.1: (Xem: bpo-12168.) Trong các phiên bản trước, thông báo được gửi đến trình nền nhật ký hệ thống luôn được kết thúc bằng byte NUL, vì các phiên bản đầu tiên của các trình nền này mong đợi một thông báo bị chấm dứt NUL - mặc dù nó không có trong thông số kỹ thuật liên quan (RFC 5424). Các phiên bản gần đây hơn của các daemon này không yêu cầu byte NUL nhưng loại bỏ nó nếu nó ở đó và thậm chí các daemon gần đây hơn (tuân thủ chặt chẽ hơn với RFC 5424) chuyển byte NUL như một phần của thông báo.

Để cho phép xử lý các thông báo nhật ký hệ thống dễ dàng hơn khi đối mặt với tất cả các hành vi daemon khác nhau này, việc gắn thêm byte NUL đã được đặt cấu hình, thông qua việc sử dụng thuộc tính cấp độ lớp, append_nul. Giá trị mặc định này là True (duy trì hành vi hiện có) nhưng có thể được đặt thành False trên phiên bản SysLogHandler để phiên bản đó not nối thêm bộ kết thúc NUL.

Thay đổi trong phiên bản 3.3: (Xem: bpo-12419.) Trong các phiên bản trước, không có tiền tố "nhận dạng" hoặc "thẻ" để xác định nguồn của tin nhắn. Điều này hiện có thể được chỉ định bằng cách sử dụng thuộc tính cấp lớp, mặc định là "" để duy trì hành vi hiện có, nhưng có thể được ghi đè trên phiên bản SysLogHandler để phiên bản đó thêm mã nhận dạng vào trước mọi thư được xử lý. Lưu ý rằng mã nhận dạng được cung cấp phải là văn bản, không phải byte và được thêm vào trước tin nhắn một cách chính xác.

encodePriority(facility, priority)

Mã hóa cơ sở và mức độ ưu tiên thành một số nguyên. Bạn có thể truyền chuỗi hoặc số nguyên - nếu chuỗi được truyền, từ điển ánh xạ nội bộ sẽ được sử dụng để chuyển đổi chúng thành số nguyên.

Các giá trị LOG_ tượng trưng được xác định trong SysLogHandler và phản chiếu các giá trị được xác định trong tệp tiêu đề sys/syslog.h.

Priorities

Tên (chuỗi)

Giá trị biểu tượng

alert

LOG_ALERT

crit hoặc critical

LOG_CRIT

debug

LOG_DEBUG

emerg hoặc panic

LOG_EMERG

err hoặc error

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warn hoặc warning

LOG_WARNING

Facilities

Tên (chuỗi)

Giá trị biểu tượng

auth

LOG_AUTH

authpriv

LOG_AUTHPRIV

cron

LOG_CRON

daemon

LOG_DAEMON

ftp

LOG_FTP

kern

LOG_KERN

lpr

LOG_LPR

mail

LOG_MAIL

news

LOG_NEWS

syslog

LOG_SYSLOG

user

LOG_USER

uucp

LOG_UUCP

local0

LOG_LOCAL0

local1

LOG_LOCAL1

local2

LOG_LOCAL2

local3

LOG_LOCAL3

local4

LOG_LOCAL4

local5

LOG_LOCAL5

local6

LOG_LOCAL6

local7

LOG_LOCAL7
mapPriority(levelname)

Ánh xạ tên cấp độ ghi nhật ký thành tên ưu tiên của nhật ký hệ thống. Bạn có thể cần ghi đè điều này nếu bạn đang sử dụng cấp độ tùy chỉnh hoặc nếu thuật toán mặc định không phù hợp với nhu cầu của bạn. Thuật toán mặc định ánh xạ DEBUG, INFO, WARNING, ERROR và CRITICAL tới các tên nhật ký hệ thống tương đương và tất cả các tên cấp độ khác thành 'cảnh báo'.

NTEventLogHandler

Lớp NTEventLogHandler, nằm trong mô-đun logging.handlers, hỗ trợ gửi thông báo ghi nhật ký đến nhật ký sự kiện Windows NT, Windows 2000 hoặc Windows XP cục bộ. Trước khi có thể sử dụng nó, bạn cần cài đặt tiện ích mở rộng Win32 cho Python của Mark Hammond.

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

Trả về một phiên bản mới của lớp NTEventLogHandler. Zz006zz được sử dụng để xác định tên ứng dụng xuất hiện trong nhật ký sự kiện. Mục đăng ký thích hợp được tạo bằng tên này. dllname phải cung cấp tên đường dẫn đủ điều kiện của một .dll hoặc .exe chứa các định nghĩa thông báo cần giữ trong nhật ký (nếu không được chỉ định, 'win32service.pyd' sẽ được sử dụng - tên này được cài đặt cùng với các tiện ích mở rộng Win32 và chứa một số định nghĩa thông báo giữ chỗ cơ bản. Lưu ý rằng việc sử dụng các trình giữ chỗ này sẽ làm cho nhật ký sự kiện của bạn trở nên lớn hơn vì toàn bộ nguồn thông báo được giữ trong nhật ký. Nếu bạn muốn nhật ký mỏng hơn, bạn phải chuyển tên .dll hoặc của riêng bạn .exe chứa định nghĩa thông báo bạn muốn sử dụng trong nhật ký sự kiện). Zz008zz là một trong các 'Application', 'System' hoặc 'Security' và mặc định là 'Application'.

close()

Tại thời điểm này, bạn có thể xóa tên ứng dụng khỏi sổ đăng ký làm nguồn của các mục nhật ký sự kiện. Tuy nhiên, nếu thực hiện việc này, bạn sẽ không thể xem các sự kiện như dự định trong Trình xem nhật ký sự kiện - nó cần có khả năng truy cập vào sổ đăng ký để lấy tên .dll. Phiên bản hiện tại không làm được điều này.

emit(record)

Xác định ID thông báo, danh mục sự kiện và loại sự kiện, sau đó ghi thông báo vào nhật ký sự kiện NT.

getEventCategory(record)

Trả về danh mục sự kiện cho bản ghi. Ghi đè điều này nếu bạn muốn chỉ định danh mục của riêng mình. Phiên bản này trả về 0.

getEventType(record)

Trả về loại sự kiện cho bản ghi. Ghi đè điều này nếu bạn muốn chỉ định loại của riêng mình. Phiên bản này thực hiện ánh xạ bằng cách sử dụng thuộc tính sơ đồ kiểu của trình xử lý, thuộc tính này được thiết lập trong __init__() tới một từ điển chứa ánh xạ cho DEBUG, INFO, WARNING, ERROR và CRITICAL. Nếu bạn đang sử dụng các cấp độ của riêng mình, bạn sẽ cần ghi đè phương thức này hoặc đặt một từ điển phù hợp vào thuộc tính typemap của trình xử lý.

getMessageID(record)

Trả về ID tin nhắn cho bản ghi. Nếu bạn đang sử dụng tin nhắn của riêng mình, bạn có thể thực hiện việc này bằng cách chuyển msg tới trình ghi nhật ký dưới dạng ID chứ không phải chuỗi định dạng. Sau đó, tại đây, bạn có thể sử dụng tra cứu từ điển để lấy ID tin nhắn. Phiên bản này trả về 1, là ID thông báo cơ sở trong win32service.pyd.

Trình xử lý SMTP

Lớp SMTPHandler, nằm trong mô-đun logging.handlers, hỗ trợ gửi tin nhắn ghi nhật ký đến địa chỉ email thông qua SMTP.

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Trả về một phiên bản mới của lớp SMTPHandler. Phiên bản này được khởi tạo với địa chỉ từ và đến cũng như dòng chủ đề của email. Zz001zz phải là một danh sách các chuỗi. Để chỉ định cổng SMTP không chuẩn, hãy sử dụng định dạng bộ dữ liệu (máy chủ, cổng) cho đối số mailhost. Nếu bạn sử dụng chuỗi, cổng SMTP tiêu chuẩn sẽ được sử dụng. Nếu máy chủ SMTP của bạn yêu cầu xác thực, bạn có thể chỉ định bộ dữ liệu (tên người dùng, mật khẩu) cho đối số credentials.

Để chỉ định việc sử dụng giao thức bảo mật (TLS), hãy chuyển một bộ dữ liệu vào đối số secure. Điều này sẽ chỉ được sử dụng khi thông tin xác thực được cung cấp. Bộ dữ liệu phải là bộ dữ liệu trống hoặc bộ dữ liệu một giá trị có tên của tệp khóa hoặc bộ dữ liệu 2 giá trị có tên của tệp khóa và tệp chứng chỉ. (Bộ dữ liệu này được truyền cho phương thức smtplib.SMTP.starttls().)

Có thể chỉ định thời gian chờ để liên lạc với máy chủ SMTP bằng cách sử dụng đối số timeout.

Thay đổi trong phiên bản 3.3: Đã thêm tham số timeout.

emit(record)

Định dạng bản ghi và gửi nó đến địa chỉ được chỉ định.

getSubject(record)

Nếu bạn muốn chỉ định dòng chủ đề phụ thuộc vào bản ghi, hãy ghi đè phương pháp này.

Trình xử lý bộ nhớ

Lớp MemoryHandler, nằm trong mô-đun logging.handlers, hỗ trợ đệm các bản ghi ghi nhật ký trong bộ nhớ, chuyển chúng định kỳ sang trình xử lý target. Quá trình xả xảy ra bất cứ khi nào bộ đệm đầy hoặc khi nhìn thấy một sự kiện ở mức độ nghiêm trọng nhất định hoặc lớn hơn.

MemoryHandler là một lớp con của BufferingHandler tổng quát hơn, là một lớp trừu tượng. Điều này đệm các bản ghi ghi nhật ký trong bộ nhớ. Bất cứ khi nào mỗi bản ghi được thêm vào bộ đệm, việc kiểm tra sẽ được thực hiện bằng cách gọi shouldFlush() để xem liệu bộ đệm có bị xóa hay không. Nếu cần thì flush() sẽ thực hiện việc xả nước.

class logging.handlers.BufferingHandler(capacity)

Khởi tạo trình xử lý với bộ đệm có dung lượng được chỉ định. Ở đây, capacity có nghĩa là số lượng bản ghi nhật ký được lưu vào bộ đệm.

emit(record)

Nối bản ghi vào bộ đệm. Nếu shouldFlush() trả về true, hãy gọi flush() để xử lý bộ đệm.

flush()

Đối với phiên bản BufferingHandler, việc xóa có nghĩa là nó đặt bộ đệm vào danh sách trống. Phương pháp này có thể được ghi đè để thực hiện hành vi xả hữu ích hơn.

shouldFlush(record)

Trả về True nếu bộ đệm đã đạt dung lượng. Phương pháp này có thể được ghi đè để thực hiện các chiến lược xả tùy chỉnh.

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Trả về một phiên bản mới của lớp MemoryHandler. Phiên bản được khởi tạo với kích thước bộ đệm là capacity (số lượng bản ghi được lưu vào bộ đệm). Nếu flushLevel không được chỉ định, ERROR sẽ được sử dụng. Nếu không có target nào được chỉ định, mục tiêu sẽ cần được đặt bằng setTarget() trước khi trình xử lý này thực hiện bất kỳ điều gì hữu ích. Nếu flushOnClose được chỉ định là False thì bộ đệm sẽ bị xóa not khi đóng trình xử lý. Nếu không được chỉ định hoặc chỉ định là True, hành vi xóa bộ đệm trước đó sẽ xảy ra khi đóng trình xử lý.

Thay đổi trong phiên bản 3.6: Tham số flushOnClose đã được thêm vào.

close()

Gọi flush(), đặt mục tiêu thành None và xóa bộ đệm.

flush()

Đối với phiên bản MemoryHandler, việc xóa có nghĩa là chỉ gửi các bản ghi được lưu vào bộ đệm đến mục tiêu, nếu có. Bộ đệm cũng bị xóa khi các bản ghi trong bộ đệm được gửi đến mục tiêu. Ghi đè nếu bạn muốn hành vi khác.

setTarget(target)

Đặt trình xử lý đích cho trình xử lý này.

shouldFlush(record)

Kiểm tra bộ đệm đầy hay bản ghi ở flushLevel trở lên.

HTTPHandler

Lớp HTTPHandler, nằm trong mô-đun logging.handlers, hỗ trợ gửi thông báo ghi nhật ký đến máy chủ web, sử dụng ngữ nghĩa GET hoặc POST.

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)

Trả về một phiên bản mới của lớp HTTPHandler. Zz004zz có thể có dạng host:port, nếu bạn cần sử dụng một số cổng cụ thể. Nếu không chỉ định method thì GET sẽ được sử dụng. Nếu secure đúng, kết nối HTTPS sẽ được sử dụng. Tham số context có thể được đặt thành phiên bản ssl.SSLContext để định cấu hình cài đặt SSL được sử dụng cho kết nối HTTPS. Nếu credentials được chỉ định, thì đó phải là một bộ gồm 2 bộ gồm userid và mật khẩu, sẽ được đặt trong tiêu đề 'Ủy quyền' của HTTP bằng cách sử dụng xác thực Cơ bản. Nếu bạn chỉ định thông tin xác thực, bạn cũng nên chỉ định safe=True để userid và mật khẩu của bạn không được chuyển qua dạng văn bản rõ ràng qua mạng.

Thay đổi trong phiên bản 3.5: Tham số context đã được thêm vào.

mapLogRecord(record)

Cung cấp một từ điển dựa trên record, được mã hóa URL và gửi đến máy chủ web. Việc triển khai mặc định chỉ trả về record.__dict__. Phương pháp này có thể được ghi đè nếu ví dụ: chỉ một tập hợp con của LogRecord sẽ được gửi đến máy chủ web hoặc nếu cần tùy chỉnh cụ thể hơn những gì được gửi đến máy chủ.

emit(record)

Gửi bản ghi đến máy chủ web dưới dạng từ điển được mã hóa URL. Phương thức mapLogRecord() được sử dụng để chuyển đổi bản ghi sang từ điển sẽ được gửi.

Ghi chú

Vì việc chuẩn bị bản ghi để gửi nó đến máy chủ web không giống như thao tác định dạng chung nên việc sử dụng setFormatter() để chỉ định Formatter cho HTTPHandler không có tác dụng. Thay vì gọi format(), trình xử lý này gọi mapLogRecord() và sau đó là urllib.parse.urlencode() để mã hóa từ điển ở dạng phù hợp để gửi đến máy chủ web.

Trình xử lý hàng đợi

Added in version 3.2.

Lớp QueueHandler, nằm trong mô-đun logging.handlers, hỗ trợ gửi thông báo ghi nhật ký đến hàng đợi, chẳng hạn như các thông báo được triển khai trong mô-đun queue hoặc multiprocessing.

Cùng với lớp QueueListener, QueueHandler có thể được sử dụng để cho phép trình xử lý thực hiện công việc của họ trên một luồng riêng biệt với luồng thực hiện ghi nhật ký. Điều này rất quan trọng trong các ứng dụng web và cả các ứng dụng dịch vụ khác, nơi các luồng phục vụ máy khách cần phản hồi nhanh nhất có thể, trong khi mọi thao tác có thể bị chậm (chẳng hạn như gửi email qua SMTPHandler) đều được thực hiện trên một luồng riêng biệt.

class logging.handlers.QueueHandler(queue)

Trả về một phiên bản mới của lớp QueueHandler. Phiên bản này được khởi tạo với hàng đợi để gửi tin nhắn tới. Zz003zz có thể là bất kỳ đối tượng giống hàng đợi nào; nó được sử dụng nguyên trạng theo phương thức enqueue(), phương thức này cần biết cách gửi tin nhắn đến nó. Hàng đợi không phải là required để có API theo dõi tác vụ, điều đó có nghĩa là bạn có thể sử dụng các phiên bản SimpleQueue cho queue.

Ghi chú

Nếu bạn đang sử dụng multiprocessing, bạn nên tránh sử dụng SimpleQueue và thay vào đó hãy sử dụng multiprocessing.Queue.

Cảnh báo

Mô-đun multiprocessing sử dụng trình ghi nhật ký nội bộ được tạo và truy cập thông qua get_logger(). multiprocessing.Queue sẽ ghi lại các thông báo ở cấp độ DEBUG khi các mục được xếp hàng đợi. Nếu những thông điệp tường trình đó được QueueHandler xử lý bằng cách sử dụng cùng một phiên bản multiprocessing.Queue, thì điều đó sẽ gây ra bế tắc hoặc đệ quy vô hạn.

emit(record)

Xếp hàng kết quả của việc chuẩn bị LogRecord. Nếu xảy ra ngoại lệ (ví dụ: do hàng đợi giới hạn đã đầy), phương thức handleError() sẽ được gọi để xử lý lỗi. Điều này có thể dẫn đến việc bản ghi bị xóa một cách âm thầm (nếu logging.raiseExceptions là False) hoặc một thông báo được in ra sys.stderr (nếu logging.raiseExceptions là True).

prepare(record)

Chuẩn bị một bản ghi để xếp hàng. Đối tượng được trả về bằng phương thức này được xếp vào hàng đợi.

Việc triển khai cơ sở định dạng bản ghi để hợp nhất thông báo, đối số, ngoại lệ và thông tin ngăn xếp, nếu có. Nó cũng loại bỏ các mục không thể chọn được khỏi bản ghi tại chỗ. Cụ thể, nó ghi đè các thuộc tính msg và message của bản ghi bằng thông báo đã hợp nhất (thu được bằng cách gọi phương thức format() của trình xử lý) và đặt các thuộc tính args, exc_info và exc_text thành None.

Bạn có thể muốn ghi đè phương thức này nếu bạn muốn chuyển đổi bản ghi thành chuỗi dict hoặc JSON hoặc gửi bản sao đã sửa đổi của bản ghi trong khi vẫn giữ nguyên bản gốc.

Ghi chú

Việc triển khai cơ sở định dạng thông báo bằng các đối số, đặt thuộc tính message và msg cho thông báo được định dạng và đặt thuộc tính args và exc_text thành None để cho phép chọn lọc và ngăn chặn các nỗ lực định dạng tiếp theo. Điều này có nghĩa là trình xử lý ở phía QueueListener sẽ không có thông tin để thực hiện định dạng tùy chỉnh, ví dụ: của các trường hợp ngoại lệ. Bạn có thể muốn phân lớp QueueHandler và ghi đè phương thức này thành ví dụ: tránh đặt exc_text thành None. Lưu ý rằng các thay đổi message / msg / args có liên quan đến việc đảm bảo bản ghi có thể chọn được và bạn có thể tránh hoặc không tránh được việc đó tùy thuộc vào việc args của bạn có thể chọn được hay không. (Lưu ý rằng bạn có thể phải xem xét không chỉ mã của riêng mình mà còn phải xem xét mã trong bất kỳ thư viện nào bạn sử dụng.)

enqueue(record)

Xếp bản ghi vào hàng đợi bằng put_nowait(); bạn có thể muốn ghi đè điều này nếu bạn muốn sử dụng hành vi chặn hoặc thời gian chờ hoặc triển khai hàng đợi tùy chỉnh.

listener

Khi được tạo thông qua cấu hình bằng dictConfig(), thuộc tính này sẽ chứa phiên bản QueueListener để sử dụng với trình xử lý này. Nếu không thì sẽ là None.

Added in version 3.12.

Trình nghe hàng đợi

Added in version 3.2.

Lớp QueueListener, nằm trong mô-đun logging.handlers, hỗ trợ nhận thông báo ghi nhật ký từ hàng đợi, chẳng hạn như các thông báo được triển khai trong mô-đun queue hoặc multiprocessing. Các tin nhắn được nhận từ hàng đợi trong một luồng nội bộ và được chuyển trên cùng một luồng đến một hoặc nhiều trình xử lý để xử lý. Mặc dù QueueListener bản thân nó không phải là một trình xử lý nhưng nó được ghi lại ở đây vì nó hoạt động song song với QueueHandler.

Cùng với lớp QueueHandler, QueueListener có thể được sử dụng để cho phép trình xử lý thực hiện công việc của họ trên một luồng riêng biệt với luồng thực hiện ghi nhật ký. Điều này rất quan trọng trong các ứng dụng web và cả các ứng dụng dịch vụ khác, nơi các luồng phục vụ máy khách cần phản hồi nhanh nhất có thể, trong khi mọi thao tác có thể bị chậm (chẳng hạn như gửi email qua SMTPHandler) đều được thực hiện trên một luồng riêng biệt.

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)

Trả về một phiên bản mới của lớp QueueListener. Phiên bản này được khởi tạo với hàng đợi để gửi tin nhắn đến và danh sách các trình xử lý sẽ xử lý các mục được đặt trên hàng đợi. Hàng đợi có thể là bất kỳ đối tượng giống hàng đợi nào; nó được chuyển nguyên trạng sang phương thức dequeue(), phương thức này cần biết cách nhận tin nhắn từ nó. Hàng đợi không phải là required để có tác vụ theo dõi API (mặc dù nó được sử dụng nếu có), điều đó có nghĩa là bạn có thể sử dụng các phiên bản SimpleQueue cho queue.

Ghi chú

Nếu bạn đang sử dụng multiprocessing, bạn nên tránh sử dụng SimpleQueue và thay vào đó hãy sử dụng multiprocessing.Queue.

Nếu respect_handler_level là True, cấp độ của trình xử lý sẽ được tôn trọng (so với cấp độ của thông báo) khi quyết định có chuyển thông báo đến trình xử lý đó hay không; mặt khác, hoạt động giống như trong các phiên bản Python trước - luôn chuyển từng thông báo cho từng trình xử lý.

Thay đổi trong phiên bản 3.5: Đối số respect_handler_level đã được thêm vào.

Thay đổi trong phiên bản 3.14: QueueListener hiện có thể được sử dụng làm trình quản lý bối cảnh thông qua with. Khi vào ngữ cảnh, người nghe được bắt đầu. Khi thoát khỏi bối cảnh, người nghe sẽ dừng lại. __enter__() trả về đối tượng QueueListener.

dequeue(block)

Loại bỏ một bản ghi và trả lại nó, tùy ý chặn.

Việc triển khai cơ sở sử dụng get(). Bạn có thể muốn ghi đè phương pháp này nếu bạn muốn sử dụng thời gian chờ hoặc làm việc với việc triển khai hàng đợi tùy chỉnh.

prepare(record)

Lập biên bản để xử lý.

Việc triển khai này chỉ trả về bản ghi đã được chuyển vào. Bạn có thể muốn ghi đè phương thức này nếu bạn cần thực hiện bất kỳ thao tác sắp xếp hoặc thao tác tùy chỉnh nào đối với bản ghi trước khi chuyển nó đến bộ xử lý.

handle(record)

Xử lý một bản ghi.

Điều này chỉ lặp qua các trình xử lý cung cấp cho họ bản ghi để xử lý. Đối tượng thực tế được truyền cho trình xử lý là đối tượng được trả về từ prepare().

start()

Bắt đầu người nghe.

Thao tác này khởi động một luồng nền để theo dõi hàng đợi để LogRecords xử lý.

Thay đổi trong phiên bản 3.14: Tăng RuntimeError nếu được gọi và trình nghe đang chạy.

stop()

Người nghe dừng lại.

Điều này yêu cầu luồng kết thúc và sau đó đợi nó thực hiện việc đó. Lưu ý rằng nếu bạn không gọi lệnh này trước khi ứng dụng của bạn thoát, có thể có một số bản ghi vẫn còn trong hàng đợi và sẽ không được xử lý.

enqueue_sentinel()

Viết một lệnh canh gác vào hàng đợi để yêu cầu người nghe thoát ra. Việc triển khai này sử dụng put_nowait(). Bạn có thể muốn ghi đè phương pháp này nếu bạn muốn sử dụng thời gian chờ hoặc làm việc với việc triển khai hàng đợi tùy chỉnh.

Added in version 3.3.

Xem thêm

Mô-đun logging

tham chiếu API cho mô-đun ghi nhật ký.

Mô-đun logging.config

Cấu hình API cho mô-đun ghi nhật ký.