如果你正在找一個(gè)Python日志庫既不想花一天時(shí)間配logging模塊又不希望輸出像默認(rèn)logging那樣干巴巴的只有一行文字acrilog包會(huì)是一個(gè)值得試一下的選擇。我最早注意到這個(gè)包是因?yàn)槟翘煜挛缗R時(shí)要接手一個(gè)寫了一半的爬蟲項(xiàng)目里面全是print和散落的日志壓根沒辦法定位任務(wù)掛在哪一步。換上acrilog之后結(jié)構(gòu)化輸出、顏色區(qū)分、不同級(jí)別過濾這些事都變簡(jiǎn)單了整個(gè)排錯(cuò)過程舒服不少。這篇文章就把它的語法、常用參數(shù)和實(shí)際項(xiàng)目里的落地用法梳理一遍適合初學(xué)Python的讀者也可以給已經(jīng)在用logging想換換手感的人做參考。1. acrilog包到底是干什么的1.1 為什么不用print也不用默認(rèn)logging很多人寫腳本都喜歡用print調(diào)試這里打印一下那里打印一下好像挺方便。但項(xiàng)目一旦超過幾百行或者在后臺(tái)跑定時(shí)任務(wù)print的弊端就暴露得很明顯沒有時(shí)間戳、沒有日志級(jí)別、不能統(tǒng)一開關(guān)、不好做文件輸出更別提給日志染上顏色來區(qū)分錯(cuò)誤了。Python標(biāo)準(zhǔn)庫的logging功能其實(shí)很強(qiáng)但默認(rèn)配置特別勸退新手。你需要記憶Handler、Formatter、Filter這些組件的用法還要搞清楚Logger、Handler和Propagate之間的關(guān)系。每次換項(xiàng)目都要重新寫一遍配置代碼復(fù)制來復(fù)制去稍不小心就會(huì)遇到日志重復(fù)輸出、等級(jí)不生效這種玄學(xué)問題。我在很多教程里看到最后直接勸退。acrilog這個(gè)包做的事情很簡(jiǎn)單把logging常用的配置壓縮成幾個(gè)參數(shù)讓日志系統(tǒng)開箱即用。它不是要取代標(biāo)準(zhǔn)庫而是把底層細(xì)節(jié)包裝得更好看一點(diǎn)。你用acrilog本質(zhì)上還是在用logging的能力只是不再需要從零搭配置了。1.2 acrilog的設(shè)計(jì)思路和核心價(jià)值第一次看這個(gè)包的結(jié)構(gòu)我感覺它最明顯的特點(diǎn)是把“日志輸出”拆成了兩個(gè)層面一個(gè)是給自己的開發(fā)調(diào)試看的另一個(gè)是給業(yè)務(wù)分析用的。開發(fā)時(shí)你希望看到帶顏色、帶模塊名、帶行號(hào)的信息上線后你希望輸出一段能被日志收集工具直接解析的JSON。acrilog恰恰允許你通過參數(shù)切換這兩種模式不用改業(yè)務(wù)代碼只在初始化Logger的時(shí)候調(diào)整配置就行。我之前在多個(gè)小項(xiàng)目里試過用它整體感受是省心。它解決的核心問題有三個(gè)第一格式化日志時(shí)間、級(jí)別、調(diào)用來源這些重復(fù)勞動(dòng)第二提供更直觀的API比如直接傳ctx上下文信息不用手動(dòng)拼字符串第三保留標(biāo)準(zhǔn)庫logging的Handler體系所以原本你會(huì)用RotatingFileHandler、StreamHandler這些它也都支持。適合用它的人我覺得大概是兩類。一類是剛學(xué)Python不久想快速給腳本加正規(guī)日志但又不想先啃一遍logging源碼的初學(xué)者另一類是像我這樣已經(jīng)寫了不少項(xiàng)目但希望日志模塊的樣板代碼越少越好的開發(fā)者。2. 安裝與基礎(chǔ)語法先跑起來2.1 環(huán)境準(zhǔn)備和安裝步驟安裝沒什么特別的走pip就行。如果你已經(jīng)在虛擬環(huán)境里直接執(zhí)行下面這條命令pip install acrilog如果你用的是比較新的Python環(huán)境有些依賴包可能需要編譯比如帶顏色輸出的平臺(tái)相關(guān)模塊。萬一遇到安裝失敗先升級(jí)一下pip和setuptools再做嘗試python -m pip install --upgrade pip setuptools wheel pip install acrilog我在macOS和Linux系統(tǒng)上都裝過整個(gè)過程沒碰到特別大的問題。Windows環(huán)境我沒深入測(cè)過但考慮到它有顏色輸出功能有條件的話建議在終端里先跑一條簡(jiǎn)單的日志試試確認(rèn)不是所有日志都輸出成亂碼。裝完之后可以看一下包的版本和主要對(duì)象import acrilog print(acrilog.__version__) print(dir(acrilog))如果正常打印出版本號(hào)和函數(shù)列表說明安裝沒問題。2.2 三行代碼上手先跑起來我非常喜歡這個(gè)包的入門方式因?yàn)樗娴目梢宰龅饺写a出日志import acrilog logger acrilog.getLogger(demo) logger.info(hello acrilog)跑下來你會(huì)看到終端里不僅有時(shí)間、日志級(jí)別、Logger名還有帶顏色的輸出。準(zhǔn)確顏色取決于你的終端是否支持ANSI轉(zhuǎn)義序列VSCode終端和macOS的Terminal一般都可以。默認(rèn)配置下acrilog.getLogger()會(huì)返回一個(gè)標(biāo)準(zhǔn)Logger所以函數(shù)名、括號(hào)參數(shù)這些語法和logging.getLogger的使用習(xí)慣是接近的。你不需要在每次調(diào)用時(shí)都指定格式Logger內(nèi)部已經(jīng)幫你配好了默認(rèn)Formatter。這條最基礎(chǔ)的用法適合單獨(dú)腳本或者調(diào)試階段。你只要保證在模塊頂層初始化Logger后面所有地方都能import到同一個(gè)logger實(shí)例。2.3 五種日志級(jí)別怎么選acrilog保留了 logging 的標(biāo)準(zhǔn)級(jí)別從低到高分別是DEBUG、INFO、WARNING、ERROR、CRITICAL。每個(gè)級(jí)別對(duì)應(yīng)一個(gè)同名方法調(diào)用方式跟標(biāo)準(zhǔn)庫一致logger.debug(debug message) logger.info(info message) logger.warning(warning message) logger.error(error message) logger.critical(critical message)不同級(jí)別適合不同場(chǎng)合。在我的習(xí)慣里DEBUG級(jí)別我用來記錄變量值、進(jìn)入某個(gè)函數(shù)、連接狀態(tài)這類細(xì)節(jié)INFO級(jí)別記錄程序的主要流程比如任務(wù)開始、任務(wù)結(jié)束、請(qǐng)求總量WARNING記錄可恢復(fù)的問題比如接口超時(shí)重試ERROR和CRITICAL分別對(duì)應(yīng)單次失敗和程序無法繼續(xù)運(yùn)行的情況。初始Logger默認(rèn)顯示級(jí)別是INFO所以DEBUG日志不會(huì)打出來。要讓它顯示DEBUG級(jí)詳情可以在構(gòu)造時(shí)把level參數(shù)設(shè)為DEBUGlogger acrilog.getLogger(debug_demo, levelDEBUG)如果你只想給某個(gè)業(yè)務(wù)模塊開啟更細(xì)的日志另外建一個(gè)帶獨(dú)立級(jí)別的Logger會(huì)更方便這樣不會(huì)把其他模塊的信息刷得鋪天蓋地。3. 核心參數(shù)解析到底有哪些關(guān)鍵配置3.1 高頻參數(shù)對(duì)照表如果只是無腦用默認(rèn)配置其實(shí)已經(jīng)比print好用了。但要發(fā)揮這個(gè)包的價(jià)值還是要看懂幾個(gè)核心參數(shù)。下面這個(gè)表我按自己使用的頻率整理出來不一定包含包的全部參數(shù)但覆蓋面已經(jīng)能應(yīng)對(duì)大多數(shù)項(xiàng)目。參數(shù)名類型默認(rèn)值作用namestr必傳Logger的名稱位置參數(shù)levelstr/intINFO日志級(jí)別控制輸出下限fmtstr內(nèi)置模板日志輸出格式模板use_colorsboolTrue是否啟用顏色輸出json_outputboolFalse是否輸出為JSON格式handlerslistNone自定義Handler列表propagateboolFalse是否向父Logger傳播日志ctxdictNone綁定的默認(rèn)上下文信息file_pathstrNone直接把日志寫入文件file_modestra寫文件時(shí)的模式初次接觸的人最容易忽略的是propagate參數(shù)。因?yàn)閍crilog內(nèi)部創(chuàng)建Logger后會(huì)默認(rèn)把propagate設(shè)為False避免日志在根Logger上再打印一次造成重復(fù)。如果你自己額外加了一個(gè)根Logger配置就要特別注意這個(gè)行為否則可能要么沒日志要么日志出現(xiàn)兩遍。3.2 自定義輸出格式和JSON格式fmt參數(shù)是控制日志模板的核心。它和logging的format概念類似但acrilog做了一點(diǎn)簡(jiǎn)化。你可以直接寫常規(guī)的Formatter格式字符串logger acrilog.getLogger( custom_fmt, fmt%(asctime)s | %(levelname)s | %(name)s | %(message)s )這樣每條日志會(huì)按照模板里的順序輸出。acrilog內(nèi)部還是會(huì)用標(biāo)準(zhǔn)庫的%格式語法所以你能用的字段名和logging是一致的。比如:%(asctime)s 時(shí)間%(levelname)s 級(jí)別%(name)s Logger名%(message)s 日志正文%(module)s 輸出日志的模塊名%(lineno)d 行號(hào)如果你不想記那么多格式符號(hào)直接把logfmt或者純文本串塞進(jìn)去也行關(guān)鍵是讓它包含你排錯(cuò)需要的信息。我自己排錯(cuò)時(shí)最喜歡帶模塊和行號(hào)所以至少會(huì)在fmt里保留%(name)s和%(lineno)d。在微服務(wù)或者需要接入日志平臺(tái)的場(chǎng)景下JSON輸出會(huì)更有用。設(shè)置json_outputTrue每條日志會(huì)以單行JSON形式輸出這樣ELK、Loki或者自建日志平臺(tái)解析起來更省事logger acrilog.getLogger( json_demo, json_outputTrue, fmt%(asctime)s | %(levelname)s | %(message)s )此時(shí)日志整體會(huì)被封裝成一個(gè)JSON對(duì)象同時(shí)帶上level、time、message這些字段。如果你把context傳進(jìn)去它也會(huì)成為JSON里的一個(gè)獨(dú)立字段。這個(gè)模式對(duì)機(jī)器讀取非常友好人工閱讀雖然有少許犧牲但勝在結(jié)構(gòu)清晰。3.3 上下文綁定與trace_id追蹤我最喜歡acrilog的一點(diǎn)是它設(shè)計(jì)了上下文信息入口。日常寫業(yè)務(wù)日志時(shí)我們經(jīng)常需要把用戶ID、訂單號(hào)、請(qǐng)求ID之類的信息一起打出來。用print或者原生logging時(shí)最容易的做法是拼字符串logger.info(user %s pay %s amount %s, user_id, order_id, amount)拼是能拼但日志一多字段順序容易亂后端要解析也不方便。acrilog可以在創(chuàng)建Logger時(shí)綁定統(tǒng)一的ctx字典也可以在一次日志調(diào)用里覆蓋logger acrilog.getLogger( app_logger, ctx{app: web-server, env: prod} ) logger.info(payment success, ctx{user_id: 12345, order_id: A10086})這樣輸出的內(nèi)容里會(huì)附帶一份上下文信息不管是排查單個(gè)用戶的問題還是做指標(biāo)統(tǒng)計(jì)都比純文本搜索方便得多。更進(jìn)一步你可以把請(qǐng)求進(jìn)入到網(wǎng)關(guān)時(shí)生成的trace_id綁定到ctx里這樣一整條調(diào)用鏈上的日志都能通過同一個(gè)trace_id串起來logger.info(request started, ctx{trace_id: trace_id}) logger.info(db query done, ctx{trace_id: trace_id})如果是在異步框架或者多線程場(chǎng)景里手動(dòng)傳trace_id有點(diǎn)煩。通常我會(huì)在協(xié)程或線程入口處拿一下上下文里的trace_id然后把它塞到Logger的ctx中保證整段處理過程里trace_id始終一致。4. 實(shí)際應(yīng)用案例從接口日志到多線程任務(wù)4.1 案例1FastAPI接口日志在Web開發(fā)里日志不止是給程序員調(diào)試用更多時(shí)候要記錄請(qǐng)求來源、接口耗時(shí)、響應(yīng)狀態(tài)和異常信息。我用FastAPI搭服務(wù)的時(shí)候習(xí)慣在中間件里統(tǒng)一記錄日志這樣不用每個(gè)路由重復(fù)寫。下面是一個(gè)很典型的中間件日志場(chǎng)景import time from fastapi import FastAPI, Request import acrilog logger acrilog.getLogger( api_access, levelINFO, json_outputTrue, ctx{app: shop-api} ) app FastAPI() app.middleware(http) async def access_log(request: Request, call_next): start time.time() try: response await call_next(request) logger.info( request handled, ctx{ method: request.method, path: request.url.path, status: response.status_code, duration_ms: round((time.time() - start) * 1000, 2) } ) return response except Exception as exc: logger.error( request failed, ctx{ method: request.method, path: request.url.path, exception: repr(exc) } ) raise這個(gè)例子用到了json_output和ctx每個(gè)路由的訪問記錄都會(huì)被包裝成一行JSON里面帶上了請(qǐng)求方法和狀態(tài)碼。后來我把日志接入日志收集平臺(tái)解析這批JSON字段時(shí)基本沒做額外清洗。如果你團(tuán)隊(duì)習(xí)慣看純文本日志也可以把json_output關(guān)掉但ctx還是會(huì)以keyvalue的形式拼接在message后面信息不丟只是展示方式不同。4.2 案例2多線程任務(wù)跟蹤用print調(diào)試多線程程序是最痛苦的因?yàn)槎鄠€(gè)線程的日志會(huì)穿插在一起分不清先后順序也不知道每行日志來自哪個(gè)線程。acrilog的context機(jī)制在這里就能發(fā)揮很好的作用。拿一個(gè)簡(jiǎn)單爬蟲任務(wù)舉例我用ThreadPoolExecutor同時(shí)抓取多個(gè)頁面每個(gè)線程需要一個(gè)唯一ID來關(guān)聯(lián)日志import threading import time from concurrent.futures import ThreadPoolExecutor import acrilog logger acrilog.getLogger(crawler, levelINFO, use_colorsFalse) def fetch_page(page_id): thread_name threading.current_thread().name logger.info(start fetch, ctx{thread: thread_name, page_id: page_id}) time.sleep(0.5) if page_id % 3 0: logger.warning(timeout, retry, ctx{thread: thread_name, page_id: page_id}) else: logger.info(finish fetch, ctx{thread: thread_name, page_id: page_id}) with ThreadPoolExecutor(max_workers4) as pool: for pid in range(10): pool.submit(fetch_page, pid)運(yùn)行后日志里的ctx會(huì)帶上thread和page_id兩個(gè)字段。即使多個(gè)線程交錯(cuò)打印只要過濾page_id或者thread字段就能把一趟任務(wù)的生命周期完全還原出來。這在排查并發(fā)請(qǐng)求超時(shí)或資源競(jìng)爭(zhēng)問題的時(shí)候特別管用。4.3 案例3日志落盤與滾動(dòng)開發(fā)環(huán)境看終端生產(chǎn)環(huán)境要落盤這是日志的基本要求。acrilog通過handlers參數(shù)和file_path參數(shù)可以很方便地接入標(biāo)準(zhǔn)libgging的文件Handler。最簡(jiǎn)單的做法是直接把日志寫到指定文件logger acrilog.getLogger( file_demo, file_pathlogs/app.log, file_modea, levelINFO )但這個(gè)寫法只適合日志量小的場(chǎng)景。大量日志會(huì)撐爆磁盤所以生產(chǎn)環(huán)境我一般會(huì)加上RotatingFileHandler按文件大小滾動(dòng)切分import logging from logging.handlers import RotatingFileHandler import acrilog file_handler RotatingFileHandler( logs/app.log, maxBytes10 * 1024 * 1024, backupCount5, encodingutf-8 ) file_handler.setLevel(INFO) logger acrilog.getLogger( file_demo, levelINFO, handlers[file_handler] )這樣單個(gè)日志文件達(dá)到10MB就會(huì)自動(dòng)切一個(gè)備份最多保留5個(gè)歷史文件。手動(dòng)的Handler和acrilog自帶的配置并不沖突它會(huì)把這個(gè)Handler掛到Logger上再用自己的Formatter去格式化輸出。如果你希望文件里的格式和終端里的格式不一樣后續(xù)自定義一個(gè)Formatter覆蓋到handler上就行。對(duì)異常信息我建議用logger.exception代替logger.error。exception方法會(huì)自動(dòng)把當(dāng)前異常堆棧打出來排錯(cuò)省很多時(shí)間。不過example里要展示的話我還是用error加exc_infoTrue更通用try: risky_call() except Exception: logger.error(something broken, exc_infoTrue)5. 常見問題與排查技巧實(shí)錄5.1 日志重復(fù)輸出原因和解決思路這個(gè)問題幾乎所有Python日志庫都會(huì)遇到acrilog也不能免俗。日志重復(fù)輸出通常有兩個(gè)來源一個(gè)是自己又一次手動(dòng)加了StreamHandler到Logger上另一個(gè)是Logger的父級(jí)也有Handler而且propagate被設(shè)為了True。acrilog默認(rèn)propagate是False所以如果你只是單純用getLogger不會(huì)莫名其妙重復(fù)。怕就怕你既用了acrilog又額外給同一個(gè)Logger添加Handler或者在項(xiàng)目里混用了原生logging根配置。我在一個(gè)老項(xiàng)目里就見過輸出控制臺(tái)的日志變成了兩行一模一樣的排查半天才發(fā)現(xiàn)是項(xiàng)目入口處配置了一次日志又在插件代碼里重復(fù)配置。解決方式也很直白檢查Logger.handlers如果列表里已經(jīng)有想要的Handler就不要再次addHandler了。要看得直觀一點(diǎn)可以在啟動(dòng)時(shí)打印一下logger acrilog.getLogger(probe) print(logger.handlers)如果看到兩個(gè)StreamHandler刪掉一個(gè)就好。再有就是確認(rèn)propagate參數(shù)必要時(shí)直接設(shè)成False。5.2 中文亂碼或者輸出顏色在Windows下不對(duì)顏色輸出和編碼問題跨平臺(tái)項(xiàng)目里基本繞不開。Linux和macOS終端對(duì)ANSI顏色支持得比較好Windows上如果是舊版cmd或者PowerShell顏色可能顯示成[32m之類的轉(zhuǎn)義字符看起來非常難受。最簡(jiǎn)單的處理方式是在acrilog初始化時(shí)關(guān)掉顏色logger acrilog.getLogger(win_demo, use_colorsFalse)這樣確實(shí)失去了一點(diǎn)視覺上的級(jí)別區(qū)分但至少信息不會(huì)亂掉。在Windows上還經(jīng)常遇到中文亂碼特別是日志寫入文件的時(shí)候。寫入文件如果沒指定encoding默認(rèn)可能是系統(tǒng)本地編碼有些環(huán)境不支持中文導(dǎo)致亂碼。我用RotatingFileHandler時(shí)都會(huì)帶上encodingutf-8參數(shù)基本能避免這個(gè)問題。如果終端里直接print中文亂碼大概率不是acrilog的問題而是終端本身的編碼設(shè)置。檢查一下終端的編碼改成UTF-8或者把環(huán)境變量PYTHONIOENCODING設(shè)為utf-8再試。5.3 API版本更新帶來的兼容性問題在使用第三方庫時(shí)最讓人頭大的就是版本升級(jí)后參數(shù)發(fā)生變化。我最早接觸acrilog時(shí)很多配置都寫在getLogger函數(shù)的關(guān)鍵字參數(shù)里后來版本調(diào)整后可能是統(tǒng)一的配置類接管了部分參數(shù)。如果你在升級(jí)包之后發(fā)現(xiàn)原來能跑的代碼忽然報(bào)錯(cuò)多半就是參數(shù)名變了。遇到這種情況我一般的排查套路是三步運(yùn)行help(acrilog.getLogger)看一下當(dāng)前版本支持哪些參數(shù)。運(yùn)行print(acrilog.__version__)記錄版本號(hào)。把舊代碼里的LEVEL_INFO替換成新參數(shù)等操作逐步調(diào)整。這里提醒一句如果項(xiàng)目的核心邏輯依賴某個(gè)特定版本的acrilog別急著追新版本?？梢韵仍趓equirements.txt里鎖住版本等兼容性確認(rèn)后再升級(jí)。我吃過太多莫名奇妙的lib升級(jí)虧日志這種橫切面組件尤其要穩(wěn)。6. 我的幾個(gè)實(shí)際使用心得寫到這里最后分享幾個(gè)我在真實(shí)項(xiàng)目里摸索出來、容易踩坑但又不常寫進(jìn)文檔里的經(jīng)驗(yàn)。第一不要在模塊底層到處創(chuàng)建acrilog.getLogger。每個(gè)Python模塊都新建一個(gè)Logger代碼是能跑但后期做日志級(jí)別調(diào)整時(shí)你得改很多地方。我現(xiàn)在的習(xí)慣是項(xiàng)目里有一個(gè)logger.py把項(xiàng)目中需要用到的Logger統(tǒng)一創(chuàng)建好其他模塊直接從這里import。這樣所有Logger配置都集中在同一處要開DEBUG的時(shí)候改一個(gè)文件就夠了。第二ctx字段盡量用小寫加下劃線。雖然包本身沒有強(qiáng)制但日志平臺(tái)對(duì)JSON字段命名通常有規(guī)范比如user_id、trace_id這種解析時(shí)才能保持統(tǒng)一。如果一會(huì)兒駝峰一會(huì)兒下劃線后續(xù)做告警和指標(biāo)會(huì)非常痛苦。第三日志格式里一定要有請(qǐng)求或業(yè)務(wù)標(biāo)識(shí)。無論是trace_id還是order_id只要出現(xiàn)異常你能靠它把散落的日志連起來。沒有這個(gè)字段日志越多越亂最后變成一堆難以定位的噪音。第四建議在測(cè)試環(huán)境先把日志跑上一兩個(gè)小時(shí)。日志系統(tǒng)看起來簡(jiǎn)單但真正到了高并發(fā)、告警接入、磁盤配額這些場(chǎng)景很多小問題才會(huì)暴露出來。提前讓日志在真實(shí)環(huán)境里轉(zhuǎn)起來比上線后臨時(shí)修要好太多。我這里說的pre-production驗(yàn)證也就是看看文件增長速率、錯(cuò)誤日志是否完整、JSON是否能被正確解析這幾件事。我自己用了acrilog之后最直接的改變是日志代碼變短了排錯(cuò)效率提高了。以前寫一套logging配置要幾十行還要小心翼翼安排Handler現(xiàn)在大部分項(xiàng)目只需要初始化一個(gè)Logger然后在需要的地方調(diào)用就能持續(xù)得到整齊一致的日志。如果你也在找一個(gè)輕量又實(shí)用的Python日志方案不妨拿個(gè)十幾分鐘把a(bǔ)crilog的語法和參數(shù)試一遍尤其是ctx和json_output這兩個(gè)功能在真實(shí)項(xiàng)目里會(huì)逐漸顯出價(jià)值。