Apache HTTP Server 第 2.4 版
Apache HTTP Server 第 2.4 版
| 說明 | 記錄對伺服器的要求 |
|---|---|
| 狀態 | 基本 |
| 模組識別碼 | log_config_module |
| 原始檔案 | mod_log_config.c |
此模組提供彈性記錄客戶端要求的功能。記錄採用可自訂的格式寫入，而且可以寫入檔案或外部程式。有提供條件化記錄，以便根據要求的特性納入或排除個別要求於記錄中。
此模組提供三條指令：TransferLog 用於建立記錄檔、LogFormat 用於設定自訂格式，以及 CustomLog 用於一步驟定義記錄檔和格式。可以在個別伺服器中多次使用 TransferLog 和 CustomLog 指令，導致個別要求記錄在多個檔案中。
LogFormat 及 CustomLog 指令的格式引數是字串。這個字串用於將個別要求記錄至記錄檔。這個字串可以包含複製到記錄檔的字元，以及 C 風格控制字元「\n」和「\t」來表示新行和標籤。字面上的引號和反斜線應以反斜線作跳脫。
請求本身的特性以將「%」指令置於格式字串中來記錄，這些指令在記錄檔中由值以下列方式取代
| 格式字串 | 說明 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
%% |
百分比符號。 | ||||||||||
%a |
請求的用戶端 IP 位址（請參閱 mod_remoteip 模組）。 | ||||||||||
%{c}a |
連線的基礎對等 IP 位址（請參閱 mod_remoteip 模組）。 | ||||||||||
%A |
本機 IP 位址。 | ||||||||||
%B |
回應大小（以位元為單位），不含 HTTP 標頭。 | ||||||||||
%b |
回應大小（以位元為單位），不含 HTTP 標頭。在 CLF 格式中，如果未傳送位元組則為「-」，而不會是 0。 | ||||||||||
%{VARNAME}C |
傳送至伺服器的請求中，Cookie VARNAME 的內容。只有 0 版的 Cookie 獲得完全支援。 | ||||||||||
%D |
處理請求所花費的時間（微秒）。 | ||||||||||
%{VARNAME}e |
環境變數 VARNAME 的內容。 | ||||||||||
%f |
檔案名稱。 | ||||||||||
%h |
遠端主機名稱。如果 HostnameLookups 設為預設的 Off，則會記錄 IP 位址。如果它僅為少數幾個主機記錄主機名稱，則您可能擁有提及主機名稱的存取控制指令。請參閱 Require 主機文件。 | ||||||||||
%{c}h |
與 %h 類似，但始終對基礎 TCP 連線的主機名稱進行報告，而不對 mod_remoteip 等模組對遠端主機名稱所做的任何修改進行報告。 | ||||||||||
%H |
請求協定。 | ||||||||||
%{VARNAME}i |
傳送至伺服器的請求中，標頭列 VARNAME: 的內容。由其他模組（例如 mod_headers）所做的變更會影響此內容。如果您有興趣瞭解大多數模組修改之前請求標頭的情況，請使用 mod_setenvif 將標頭複製到內部環境變數並使用上述 %{VARNAME}e 記錄該值。 | ||||||||||
%k |
以此連線處理的 keepalive 請求數。如果正在使用 KeepAlive，則會很有趣。例如，「1」表示初始請求後的第一個 keepalive 請求、「2」表示第二個，依此類推；否則，這始終為 0（表示初始請求）。 | ||||||||||
%l |
遠端登入名稱（來自 identd，如果已提供）。除非存在 mod_ident 且已將 IdentityCheck 設為 On，否則會傳回破折號。 | ||||||||||
%L |
來自錯誤記錄的請求記錄 ID（或者如果沒有任何內容記錄在此請求的錯誤記錄中，則顯示「-」）。尋找相符的錯誤記錄列，以查看哪些請求導致哪個錯誤。 | ||||||||||
%m |
請求方法。 | ||||||||||
%{VARNAME}n |
來自另一個模組的註記 VARNAME 的內容。 | ||||||||||
%{VARNAME}o |
回覆中標題行 VARNAME: 的內容。 | ||||||||||
%p |
提供請求服務的伺服器的正規埠口。 | ||||||||||
%{格式}p |
處理請求的伺服器的正規埠、伺服器的實際埠，或客戶端的實際埠。有效的格式為 cononical、local 或 remote。 | ||||||||||
%P |
處理請求的子程序的程序編號。 | ||||||||||
%{格式}P |
處理請求的子程序的程序編號或執行緒編號。有效的格式為 pid、tid 和 hextid。 | ||||||||||
%q |
查詢字串（若有查詢字串則以 ? 開頭，否則為空字串）。 | ||||||||||
%r |
請求的第一行。 | ||||||||||
%R |
產生回應的處理常式（若有）。 | ||||||||||
%s |
狀態。對於已內部重新導向的請求，這是原始請求的狀態。針對最終狀態，請使用 %>s。 | ||||||||||
%t |
收到請求的時間，格式為 [18/Sep/2011:19:18:28 -0400]。最後一個數字表示從 GMT 的時區偏移。 | ||||||||||
%{格式}t |
時間，格式由格式決定，應為擴充的 strftime(3) 格式（有可能是本地的）。若格式以 begin: 開始（預設），則時間採自請求處理的開始。若以 end: 開始，則為日誌項目寫入的時間，接近請求處理的結束。除了 strftime(3) 支援的格式外，還支援以下格式化標記
strftime(3) 格式組合使用，只要使用多個 %{格式}t 標記即可。 | ||||||||||
%T |
處理請求花費的時間（以秒為單位）。 | ||||||||||
%{單位}T |
處理請求所花費的時間，單位由 單位 決定。有效的單位有 ms（毫秒）、us（微秒）和 s（秒）。使用 s 會產生與不含任何格式的 %T 相同的結果；而 us 則會產生與 %D 相同的結果。將 %T 與單位結合使用的方式在 2.4.13 版之後才開始提供。 | ||||||||||
%u |
如果請求已驗證，則為遠端使用者。如果傳回狀態（%s）為 401（未授權），則可能是偽造的。 | ||||||||||
%U |
所請求的 URL 路徑，不含任何查詢字串。 | ||||||||||
%v |
處理請求的伺服器的正規 ServerName。 | ||||||||||
%V |
根據 使用正規名稱 設定的伺服器名稱。 | ||||||||||
%X |
回應完成時的連線狀態
| ||||||||||
%I |
收到的位元組，包含要求和標頭，不能為零。您需要啟用 mod_logio 模組才能使用此功能。 | ||||||||||
%O |
已傳送的位元組，包括標頭。在某些罕見情況下，例如在傳送回應之前取消要求時，它可能會為零。您需要啟用 mod_logio 模組才能使用此功能。 | ||||||||||
%S |
傳輸的位元組（收到的和已傳送的），包括要求和標頭，不能為零。這是 %I 和 %O 的組合。您需要啟用 mod_logio 模組才能使用此功能。 | ||||||||||
%{VARNAME}^ti |
傳送到伺服器的要求中，VARNAME 行（會加上結尾字串）的內容。 | ||||||||||
%{VARNAME}^to |
從伺服器傳送的回應中，VARNAME 行（會加上結尾字串）的內容。 |
個別項目可以限制僅列印特定 HTTP 狀態碼的回應，方法是在百分比符號後面加上狀態碼的逗號分隔清單。狀態碼清單前可以加上一個「!」來表示否定。
| 格式字串 | 含意 |
|---|---|
%400,501{User-agent}i |
僅在 400 錯誤和 501 錯誤時記錄 User-agent。對於其他狀態碼，會記錄字串常數 "-"。 |
%!200,304,302{Referer}i |
在 未 傳回三個指定代碼之一的所有要求上記錄 Referer，否則記錄 "-"。 |
對於已在內部重新導向以選擇應參照原始要求或最終要求的請求，可以使用修改器「<」和「>」。預設情況下，% 指令 %s、%U、%T、%D 和 %r 會檢視原始要求，而所有其他指令則會檢視最終要求。因此，例如，%>s 可用於記錄要求的最終狀態，而 %<u 可用於記錄在內部重新導向到未驗證資源的請求（要求記錄）上的原始驗證使用者。
由於安全性的考量，從 2.0.46 版開始，%r、%i 和 %o 中的非列印字元和其他特殊字元會使用 \xhh 順序來跳脫，其中 hh 代表原始位元的十六進制表示。此規則的例外情況是 " 和 \，它們會透過在其前面加上反斜線來跳脫，以及所有空白字元，這些字元會以其 C 風格表示法撰寫 (\n、\t 等)。在 2.0.46 版之前，這些字串未執行任何跳脫，因此您在處理原始記錄檔時必須非常小心。
自 httpd 2.0 後，不同於 1.3，格式字串 %b 和 %B 並不代表傳送給客戶端的位元組數量，而是 HTTP 回應的位元組大小（例如，連線中斷或使用 SSL 時，其值會有所不同）。由 mod_logio%O將記錄在網路上傳送的實際位元組數量。
注意：mod_cache%R 就不會傳回任何處理常式資訊。
以下是幾個常用的記錄格式字串
"%h %l %u %t \"%r\" %>s %b""%v %h %l %u %t \"%r\" %>s %b""%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"""%{Referer}i -> %U""%{User-agent}i"可以使用 %{format}t 指令多次來建立時間格式，使用延伸格式代碼，例如 msec_frac
"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"| 說明 | 在寫入磁碟前，將記錄項目緩存在記憶體中 |
|---|---|
| 語法 | BufferedLogs On|Off |
| 預設值 | BufferedLogs Off |
| 內容 | 伺服器設定 |
| 狀態 | 基本 |
| 模組 | mod_log_config |
BufferedLogsmod_log_config 將多個記錄項目儲存在記憶體中，並將它們一起寫入磁碟，而非在每個請求後寫入。在某些系統上，這樣可能使磁碟存取更有效率，因此效能更高。只能針對整個伺服器設定一次，無法針對每個虛擬主機設定。
| 說明 | 設定記錄檔的檔名和格式 |
|---|---|
| 語法 | CustomLog file|pipe format|nickname [env=[!]environment-variable| expr=expression] |
| 內容 | 伺服器設定、虛擬主機 |
| 狀態 | 基本 |
| 模組 | mod_log_config |
CustomLog
第一個引數指定記錄的寫入位置，可以是下列兩種類型的值之一
ServerRoot 的檔案名稱。|」，後接接收標準輸入中日誌資訊程式的路徑。有關詳細資訊，請參閱 傳輸日誌 的注意事項。如使用程式，則程式會以啟動 httpd 的使用者身分執行。如果伺服器是由 root 使用者啟動，則會是 root 使用者；請務必確保程式安全。
在非 Unix 平台上輸入檔案路徑時，請小心確保僅使用正斜線，即使平台允許使用反斜線亦同。一般而言，最好在設定檔中始終使用正斜線。
第二個參數會指定會寫入至日誌檔的內容。它可以指定由先前 LogFormat 指令定義的 暱稱，也可以是如 日誌格式 區段中所述的明確 格式字串。
例如，以下兩組指令具有完全相同的效果
# CustomLog with format nickname LogFormat "%h %l %u %t \"%r\" %>s %b" common CustomLog "logs/access_log" common # CustomLog with explicit format string CustomLog "logs/access_log" "%h %l %u %t \"%r\" %>s %b"
第三個參數是選用的，用於控制是否記錄特定要求。條件可能是伺服器 環境 中是否存在特定變數（如果是「env=!名稱」子句，則為不存在）。或者，條件可以表示為任意布林 運算式。如果未滿足條件，則不會記錄要求。運算式中對於 HTTP 標頭的參照不會使標頭名稱會加入 Vary 標頭。
可以使用 mod_setenvif 和/或 mod_rewrite 模組，針對每個要求設定環境變數。例如，如果你要單獨將你伺服器上所有 GIF 影像的要求記錄在不同的日誌檔中，但不要記錄在你的主日誌檔中，你可以使用
SetEnvIf Request_URI \.gif$ gif-image CustomLog "gif-requests.log" common env=gif-image CustomLog "nongif-requests.log" common env=!gif-image
或者，若要複製舊 RefererIgnore 指令的行為，你可以使用下列指令
SetEnvIf Referer example\.com localreferer CustomLog "referer.log" referer env=!localreferer
| 說明 | 設定記錄檔的檔名和格式 |
|---|---|
| 語法 | GlobalLog檔案|管線 格式|暱稱 [env=[!]環境變數| expr=運算式] |
| 內容 | 伺服器設定 |
| 狀態 | 基本 |
| 模組 | mod_log_config |
| 相容性 | 於 Apache HTTP Server 2.4.19 及更新版本提供 |
GlobalLog 指令定義主伺服器設定和所有已定義虛擬主機共用的日誌。
GlobalLog 指令與 CustomLog 指令相同，只有下列不同之處
GlobalLog 在虛擬主機環境中無效。GlobalLog 由定義自身 CustomLog 的虛擬主機使用，這與全局指定的 CustomLog 不同。| 說明 | 說明記錄檔檔案中使用的格式 |
|---|---|
| 語法 | LogFormat 格式|暱稱 [暱稱] |
| 預設值 | LogFormat "%h %l %u %t \"%r\" %>s %b" |
| 內容 | 伺服器設定、虛擬主機 |
| 狀態 | 基本 |
| 模組 | mod_log_config |
此指令定義存取記錄檔的格式。
有兩種形式的 LogFormat 指令。第一種形式只有一個指定的參數，此指令會設定記錄格式，而後續中指定的各個 TransferLog 指令就會使用該格式記錄。這一個參數可以是 自訂記錄格式 區段前面已討論過的明確 格式。此外，也可以使用 暱稱 指涉 LogFormat 指令先前定義的記錄格式（如下描述）。
第二種形式的 LogFormat 指令是將明確的 格式 與 暱稱 關聯起來。此 暱稱 可用於後續的 LogFormat 或 CustomLog 指令，而非重複整個格式字串。LogFormat 指令定義暱稱只會有這一個作用，也就是 只 定義暱稱，它並未實際套用格式，或將其設為預設值。因此，它不會影響後續的 TransferLog 指令。此外，LogFormat 無法使用一個暱稱去定義另一個暱稱。請注意，暱稱不得包含百分比符號（%）。
LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
| 說明 | 指定記錄檔位置 |
|---|---|
| 語法 | TransferLog 檔案|管線 |
| 內容 | 伺服器設定、虛擬主機 |
| 狀態 | 基本 |
| 模組 | mod_log_config |
此指令的參數和作用與 CustomLog 指令完全相同，唯一的例外是它不允許明确指定記錄格式，或有條件地記錄要求。記錄格式是由最近指定的 LogFormat 指令決定，此指令未定義暱稱。如果未指定其他格式，將會使用 common 日誌格式。
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log