logging.config --- 日志記錄配置?

字典架構(gòu)細(xì)節(jié)?

傳給 dictConfig() 的字典必須包含以下的鍵:

• version - 應(yīng)設(shè)為代表架構(gòu)版本的整數(shù)值。 目前唯一有效的值是 1，使用此鍵可允許架構(gòu)在繼續(xù)演化的同時(shí)保持向下兼容性。

所有其他鍵都是可選項(xiàng)，但如存在它們將根據(jù)下面的描述來(lái)解讀。 在下面提到 'configuring dict' 的所有情況下，都將檢查它的特殊鍵 '()' 以確定是否需要自定義實(shí)例化。 如果需要，則會(huì)使用下面 用戶定義對(duì)象 所描述的機(jī)制來(lái)創(chuàng)建一個(gè)實(shí)例；否則，會(huì)使用上下文來(lái)確定要實(shí)例化的對(duì)象。

• formatters - 對(duì)應(yīng)的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)格式器 ID 而每個(gè)值則是一個(gè)描述如何配置相應(yīng) Formatter 實(shí)例的字典。

  在配置字典中搜索以下可選鍵，這些鍵對(duì)應(yīng)于創(chuàng)建 Formatter 對(duì)象時(shí)傳入的參數(shù)。:

  • format

  • datefmt

  • style

  • validate (從版本 >=3.8 起)

  可選的 class 鍵指定格式化器類的名稱（形式為帶點(diǎn)號(hào)的模塊名和類名）。 實(shí)例化的參數(shù)與 Formatter 的相同，因此這個(gè)鍵對(duì)于實(shí)例化自定義的 Formatter 子類最為有用。 如果，替代類可能 會(huì)以擴(kuò)展和精簡(jiǎn)格式呈現(xiàn)異常回溯信息。 如果你的格式化器需要不同的或額外的配置鍵，你應(yīng)當(dāng)使用 用戶定義對(duì)象。

• filters - 對(duì)應(yīng)的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)過(guò)濾器 ID 而每個(gè)值則是一個(gè)描述如何配置相應(yīng) Filter 實(shí)例的字典。

  將在配置字典中搜索鍵 name (默認(rèn)值為空字符串) 并且該鍵會(huì)被用于構(gòu)造 logging.Filter 實(shí)例。

• handlers - 對(duì)應(yīng)的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)處理器 ID 而每個(gè)值則是一個(gè)描述如何配置相應(yīng) Handler 實(shí)例的字典。

  將在配置字典中搜索下列鍵:

  • class (強(qiáng)制)。 這是處理器類的完整限定名稱。

  • level (可選)。 處理器的級(jí)別。

  • formatter (可選)。 處理器所對(duì)應(yīng)格式化器的 ID。

  • filters (可選)。 由處理器所對(duì)應(yīng)過(guò)濾器的 ID 組成的列表。

    在 3.11 版更改: filters can take filter instances in addition to ids.

  所有 其他 鍵會(huì)被作為關(guān)鍵字參數(shù)傳遞給處理器類的構(gòu)造器。 例如，給定如下配置:

  handlers:
    console:
      class : logging.StreamHandler
      formatter: brief
      level   : INFO
      filters: [allow_foo]
      stream  : ext://sys.stdout
    file:
      class : logging.handlers.RotatingFileHandler
      formatter: precise
      filename: logconfig.log
      maxBytes: 1024
      backupCount: 3
  

  ID 為 console 的處理器會(huì)被實(shí)例化為 logging.StreamHandler，并使用 sys.stdout 作為下層流。 ID 為 file 的處理器會(huì)被實(shí)例化為 logging.handlers.RotatingFileHandler，并附帶關(guān)鍵字參數(shù) filename='logconfig.log', maxBytes=1024, backupCount=3。

• loggers - 對(duì)應(yīng)的值將是一個(gè)字典，其中每個(gè)鍵是一個(gè)日志記錄器名稱而每個(gè)值則是一個(gè)描述如何配置相應(yīng) Logger 實(shí)例的字典。

  將在配置字典中搜索下列鍵:

  • level (可選)。 日志記錄器的級(jí)別。

  • propagate (可選)。 日志記錄器的傳播設(shè)置。

  • filters (可選)。 由日志記錄器對(duì)應(yīng)過(guò)濾器的 ID 組成的列表。

    在 3.11 版更改: filters can take filter instances in addition to ids.

  • handlers (可選)。 由日志記錄器對(duì)應(yīng)處理器的 ID 組成的列表。

  指定的記錄器將根據(jù)指定的級(jí)別、傳播、過(guò)濾器和處理器來(lái)配置。

• root - 這將成為根日志記錄器對(duì)應(yīng)的配置。 配置的處理方式將與所有日志記錄器一致，除了 propagate 設(shè)置將不可用之外。

• incremental - 配置是否要被解讀為在現(xiàn)有配置上新增。 該值默認(rèn)為 False，這意味著指定的配置將以與當(dāng)前 fileConfig() API 所使用的相同語(yǔ)義來(lái)替代現(xiàn)有的配置。

  如果指定的值為 True，配置會(huì)按照 增量配置 部分所描述的方式來(lái)處理。

• disable_existing_loggers - 是否要禁用任何現(xiàn)有的非根日志記錄器。 該設(shè)置對(duì)應(yīng)于 fileConfig() 中的同名形參。 如果省略，則此形參默認(rèn)為 True。 如果 incremental 為 True 則該省會(huì)被忽略。

增量配置?

為增量配置提供完全的靈活性是很困難的。 例如，由于過(guò)濾器和格式化器這樣的對(duì)象是匿名的，一旦完成配置，在增加配置時(shí)就不可能引用這些匿名對(duì)象。

此外，一旦完成了配置，在運(yùn)行時(shí)任意改變?nèi)罩居涗浧?、處理器、過(guò)濾器、格式化器的對(duì)象圖就不是很有必要；日志記錄器和處理器的詳細(xì)程度只需通過(guò)設(shè)置級(jí)別即可實(shí)現(xiàn)控制（對(duì)于日志記錄器則可設(shè)置傳播旗標(biāo)）。 在多線程環(huán)境中以安全的方式任意改變對(duì)象圖也許會(huì)導(dǎo)致問(wèn)題；雖然并非不可能，但這樣做的好處不足以抵銷其所增加的實(shí)現(xiàn)復(fù)雜度。

這樣，當(dāng)配置字典的 incremental 鍵存在且為 True 時(shí)，系統(tǒng)將完全忽略任何 formatters 和 filters 條目，并僅會(huì)處理 handlers 條目中的 level 設(shè)置，以及 loggers 和 root 條目中的 level 和 propagate 設(shè)置。

使用配置字典中的值可讓配置以封存字典對(duì)象的形式通過(guò)線路傳送給套接字監(jiān)聽(tīng)器。 這樣，長(zhǎng)時(shí)間運(yùn)行的應(yīng)用程序的日志記錄的詳細(xì)程度可隨時(shí)間改變而無(wú)須停止并重新啟動(dòng)應(yīng)用程序。

對(duì)象連接?

該架構(gòu)描述了一組日志記錄對(duì)象 —— 日志記錄器、處理器、格式化器、過(guò)濾器 —— 它們?cè)趯?duì)象圖中彼此連接。 因此，該架構(gòu)需要能表示對(duì)象之間的連接。 例如，在配置完成后，一個(gè)特定的日志記錄器關(guān)聯(lián)到了一個(gè)特定的處理器。 出于討論的目的，我們可以說(shuō)該日志記錄器代表兩者間連接的源頭，而處理器則代表對(duì)應(yīng)的目標(biāo)。 當(dāng)然在已配置對(duì)象中這是由包含對(duì)處理器的引用的日志記錄器來(lái)代表的。 在配置字典中，這是通過(guò)給每個(gè)目標(biāo)對(duì)象一個(gè) ID 來(lái)無(wú)歧義地標(biāo)識(shí)它，然后在源頭對(duì)象中使用該 ID 來(lái)實(shí)現(xiàn)的。

因此，舉例來(lái)說(shuō)，考慮以下 YAML 代碼段:

formatters:
  brief:
    # configuration for formatter with id 'brief' goes here
  precise:
    # configuration for formatter with id 'precise' goes here
handlers:
  h1: #This is an id
   # configuration of handler with id 'h1' goes here
   formatter: brief
  h2: #This is another id
   # configuration of handler with id 'h2' goes here
   formatter: precise
loggers:
  foo.bar.baz:
    # other configuration for logger 'foo.bar.baz'
    handlers: [h1, h2]

（注：這里使用 YAML 是因?yàn)樗目勺x性比表示字典的等價(jià) Python 源碼形式更好。）

日志記錄器 ID 就是日志記錄器的名稱，它會(huì)在程序中被用來(lái)獲取對(duì)日志記錄器的引用，例如 foo.bar.baz。 格式化器和過(guò)濾器的 ID 可以是任意字符串值 (例如上面的 brief, precise) 并且它們是瞬態(tài)的，因?yàn)樗鼈儍H對(duì)處理配置字典有意義并會(huì)被用來(lái)確定對(duì)象之間的連接，而當(dāng)配置調(diào)用完成時(shí)不會(huì)在任何地方保留。

上面的代碼片段指明名為 foo.bar.baz 的日志記錄器應(yīng)當(dāng)關(guān)聯(lián)到兩個(gè)處理器，它們的 ID 是 h1 和 h2。 h1 的格式化器的 ID 是 brief，而 h2 的格式化器的 ID 是 precise。

用戶定義對(duì)象?

此架構(gòu)支持用戶定義對(duì)象作為處理器、過(guò)濾器和格式化器。 （日志記錄器的不同實(shí)例不需要具有不同類型，因此這個(gè)配置架構(gòu)并不支持用戶定義日志記錄器類。）

要配置的對(duì)象是由字典描述的，其中包含它們的配置詳情。 在某些地方，日志記錄系統(tǒng)將能夠從上下文中推斷出如何實(shí)例化一個(gè)對(duì)象，但是當(dāng)要實(shí)例化一個(gè)用戶自定義對(duì)象時(shí)，系統(tǒng)將不知道要如何做。 為了提供用戶自定義對(duì)象實(shí)例化的完全靈活性，用戶需要提供一個(gè)‘工廠’函數(shù) —— 即在調(diào)用時(shí)傳入配置字典并返回實(shí)例化對(duì)象的可調(diào)用對(duì)象。 這是用一個(gè)通過(guò)特殊鍵 '()' 來(lái)訪問(wèn)的工廠函數(shù)的絕對(duì)導(dǎo)入路徑來(lái)標(biāo)示的。 下面是一個(gè)實(shí)際的例子:

formatters:
  brief:
    format: '%(message)s'
  default:
    format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
    datefmt: '%Y-%m-%d %H:%M:%S'
  custom:
      (): my.package.customFormatterFactory
      bar: baz
      spam: 99.9
      answer: 42

上面的 YAML 代碼片段定義了三個(gè)格式化器。 第一個(gè)的 ID 為 brief，是帶有特殊格式字符串的標(biāo)準(zhǔn) logging.Formatter 實(shí)例。 第二個(gè)的 ID 為 default，具有更長(zhǎng)的格式同時(shí)還顯式地定義了時(shí)間格式，并將最終實(shí)例化一個(gè)帶有這兩個(gè)格式字符串的 logging.Formatter。 以 Python 源代碼形式顯示的 brief 和 default 格式化器分別具有下列配置子字典:

{
  'format' : '%(message)s'
}

和:

{
  'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
  'datefmt' : '%Y-%m-%d %H:%M:%S'
}

并且由于這些字典不包含特殊鍵 '()'，實(shí)例化方式是從上下文中推斷出來(lái)的：結(jié)果會(huì)創(chuàng)建標(biāo)準(zhǔn)的 logging.Formatter 實(shí)例。 第三個(gè)格式器的 ID 為 custom，對(duì)應(yīng)配置子字典為:

{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42
}

并且它包含特殊鍵 '()'，這意味著需要用戶自定義實(shí)例化方式。 在此情況下，將使用指定的工廠可調(diào)用對(duì)象。 如果它本身就是一個(gè)可調(diào)用對(duì)象則將被直接使用 —— 否則如果你指定了一個(gè)字符串（如這個(gè)例子所示）則將使用正常的導(dǎo)入機(jī)制來(lái)定位實(shí)例的可調(diào)用對(duì)象。 調(diào)用該可調(diào)用對(duì)象將傳入配置子字典中 剩余的 條目作為關(guān)鍵字參數(shù)。 在上面的例子中，調(diào)用將預(yù)期返回 ID 為 custom 的格式化器:

my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)

將 '()' 用作特殊鍵是因?yàn)樗皇且粋€(gè)有效的關(guān)鍵字形參名稱，這樣就不會(huì)與調(diào)用中使用的關(guān)鍵字參數(shù)發(fā)生沖突。 '()' 還被用作表明對(duì)應(yīng)值為可調(diào)用對(duì)象的助記符。

在 3.11 版更改: The filters member of handlers and loggers can take filter instances in addition to ids.

訪問(wèn)外部對(duì)象?

有時(shí)一個(gè)配置需要引用配置以外的對(duì)象，例如 sys.stderr。 如果配置字典是使用 Python 代碼構(gòu)造的，這會(huì)很直觀，但是當(dāng)配置是通過(guò)文本文件（例如 JSON, YAML）提供的時(shí)候就會(huì)引發(fā)問(wèn)題。 在一個(gè)文本文件中，沒(méi)有將 sys.stderr 與字符串字面值 'sys.stderr' 區(qū)分開(kāi)來(lái)的標(biāo)準(zhǔn)方式。 為了實(shí)現(xiàn)這種區(qū)分，配置系統(tǒng)會(huì)在字符串值中查找規(guī)定的特殊前綴并對(duì)其做特殊處理。 例如，如果在配置中將字符串字面值 'ext://sys.stderr' 作為一個(gè)值來(lái)提供，則 ext:// 將被去除而該值的剩余部分將使用正常導(dǎo)入機(jī)制來(lái)處理。

此類前綴的處理方式類似于協(xié)議處理：存在一種通用機(jī)制來(lái)查找與正則表達(dá)式 ^(?P<prefix>[a-z]+)://(?P<suffix>.*)$ 相匹配的前綴，如果識(shí)別出了 prefix，則 suffix 會(huì)以與前綴相對(duì)應(yīng)的方式來(lái)處理并且處理的結(jié)果將替代原字符串值。 如果未識(shí)別出前綴，則原字符串將保持不變。

訪問(wèn)內(nèi)部對(duì)象?

除了外部對(duì)象，有時(shí)還需要引用配置中的對(duì)象。 這將由配置系統(tǒng)針對(duì)它所了解的內(nèi)容隱式地完成。 例如，在日志記錄器或處理器中表示 level 的字符串值 'DEBUG' 將被自動(dòng)轉(zhuǎn)換為值 logging.DEBUG，而 handlers, filters 和 formatter 條目將接受一個(gè)對(duì)象 ID 并解析為適當(dāng)?shù)哪繕?biāo)對(duì)象。

但是，對(duì)于 logging 模塊所不了解的用戶自定義對(duì)象則需要一種更通用的機(jī)制。 例如，考慮 logging.handlers.MemoryHandler，它接受一個(gè) target 參數(shù)即其所委托的另一個(gè)處理器。 由于系統(tǒng)已經(jīng)知道存在該類，因而在配置中，給定的 target 只需為相應(yīng)目標(biāo)處理器的的對(duì)象 ID 即可，而系統(tǒng)將根據(jù)該 ID 解析出處理器。 但是，如果用戶定義了一個(gè)具有 alternate 處理器的 my.package.MyHandler，則配置程序?qū)⒉恢?alternate 指向的是一個(gè)處理器。 為了應(yīng)對(duì)這種情況，通用解析系統(tǒng)允許用戶指定:

handlers:
  file:
    # configuration of file handler goes here

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file

字符串字面值 'cfg://handlers.file' 將按照與 ext:// 前綴類似的方式被解析為結(jié)果字符串，但查找操作是在配置自身而不是在導(dǎo)入命名空間中進(jìn)行。 該機(jī)制允許按點(diǎn)號(hào)或按索引來(lái)訪問(wèn)，與 str.format 所提供的方式類似。 這樣，給定以下代碼段:

handlers:
  email:
    class: logging.handlers.SMTPHandler
    mailhost: localhost
    fromaddr: my_app@domain.tld
    toaddrs:
      - support_team@domain.tld
      - dev_team@domain.tld
    subject: Houston, we have a problem.

在該配置中，字符串 'cfg://handlers' 將解析為帶有 handlers 鍵的字典，字符串 'cfg://handlers.email 將解析為具有 email 鍵的 handlers 字典中的字典，依此類推。 字符串 'cfg://handlers.email.toaddrs[1] 將解析為 'dev_team@domain.tld' 而字符串 'cfg://handlers.email.toaddrs[0]' 將解析為值 'support_team@domain.tld'。 subject 值 可以使用 'cfg://handlers.email.subject' 或者等價(jià)的 'cfg://handlers.email[subject]' 來(lái)訪問(wèn)。 后一種形式僅在鍵包含空格或非字母類數(shù)字類字符的情況下才需要使用。 如果一個(gè)索引僅由十進(jìn)制數(shù)碼構(gòu)成，則將嘗試使用相應(yīng)的整數(shù)值來(lái)訪問(wèn)，如果有必要?jiǎng)t將回退為字符串值。

給定字符串 cfg://handlers.myhandler.mykey.123，這將解析為 config_dict['handlers']['myhandler']['mykey']['123']。 如果字符串被指定為 cfg://handlers.myhandler.mykey[123]，系統(tǒng)將嘗試從 config_dict['handlers']['myhandler']['mykey'][123] 中提取值，并在嘗試失敗時(shí)回退為 config_dict['handlers']['myhandler']['mykey']['123']。

導(dǎo)入解析與定制導(dǎo)入器?

導(dǎo)入解析默認(rèn)使用內(nèi)置的 __import__() 函數(shù)來(lái)執(zhí)行導(dǎo)入。 你可能想要將其替換為你自己的導(dǎo)入機(jī)制：如果是這樣的話，你可以替換 DictConfigurator 或其超類 BaseConfigurator 類的 importer 屬性。 但是你必須小心謹(jǐn)慎，因?yàn)楹瘮?shù)是從類中通過(guò)描述器方式來(lái)訪問(wèn)的。 如果你使用 Python 可調(diào)用對(duì)象來(lái)執(zhí)行導(dǎo)入，并且你希望在類層級(jí)而不是在實(shí)例層級(jí)上定義它，則你需要用 staticmethod() 來(lái)裝飾它。 例如:

from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)

如果你是在一個(gè)配置器的 實(shí)例 上設(shè)置導(dǎo)入可調(diào)用對(duì)象則你不需要用 staticmethod() 來(lái)裝飾。