mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-23 21:46:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs for upcoming v2.5.0 release (#216)

Browse source 
* docs: new `log` filters in Caddyfile

* docs: `renew_interval` global option

* docs: Update access log example

* docs: `log_credentials` global option

* docs: `vars`, `vars_regexp` matchers

* docs: `roll_uncompressed`, `roll_local_time`

* docs: `http_redirect` listener wrapper

* docs: `pki` app

* docs: `strict_sni_host` options

* docs: `default_bind` option

* docs: `method` directive

* docs: `tls internal` subdirectives

* Apply suggestions from code review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

* Matchers, options, file_server, reverse_proxy

* More clarifications / corrections

* Corrections from review

* Typo fix

* One more note about dynamic upstreams

* Tab -> space

* Update module namespaces

* Update some docs about logging

* `copy_response`, `copy_response_headers`, `replace_status`

* `dns_challenge_domain_override`

* `caddy trust`, API endpoints

* `trusted_proxies`

* Note about `pass_thru` being only useful inside `route`

* Improve logging docs to clarify the difference

* A bit of polish on patterns

* request_body: Clarify error behavior

* review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>
This commit is contained in:
Francis Lavoie 2022-03-11 16:26:00 -05:00 • committed by GitHub
parent c734cc3e64
commit a1ddadf798
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 575 additions and 157 deletions
Download patch file Download diff file Expand all files Collapse all files

43
src/docs/markdown/logging.md
View file

@ -50,54 +50,47 @@ Now compare an equivalent structured log message from Caddy, encoded as JSON and
```json
{
"level": "info",
"ts": 1585597114.7687502,
"ts": 1646861401.5241024,
"logger": "http.log.access",
"msg": "handled request",
"request": {
"method": "GET",
"uri": "/",
"remote_ip": "127.0.0.1",
"remote_port": "41342",
"proto": "HTTP/2.0",
"remote_addr": "127.0.0.1:50876",
"host": "example.com",
"method": "GET",
"host": "localhost",
"uri": "/",
"headers": {
"User-Agent": [
"curl/7.64.1"
],
"Accept": [
"*/*"
]
"User-Agent": ["curl/7.82.0"],
"Accept": ["*/*"],
"Accept-Encoding": ["gzip, deflate, br"],
},
"tls": {
"resumed": false,
"version": 771,
"ciphersuite": 49196,
"version": 772,
"cipher_suite": 4865,
"proto": "h2",
"proto_mutual": true,
"server_name": "example.com"
}
},
"user_id": "",
"duration": 0.000014711,
"size": 2326,
"duration": 0.000929675,
"size": 10900,
"status": 200,
"resp_headers": {
"Server": [
"Caddy"
],
"Content-Type": ["text/html"]
"Server": ["Caddy"],
"Content-Encoding": ["gzip"],
"Content-Type": ["text/html; charset=utf-8"],
"Vary": ["Accept-Encoding"]
}
}
```
<aside class="tip">
In actual access logs emitted from Caddy, another field called "common_log" is also present. The purpose of this field is just to help people transition from legacy systems to more modern ones.
</aside>
You can see how the structured log is much more useful and contains much more information. The abundance of information in this log message is not only useful, but it comes at virtually no performance overhead: Caddy's logs are zero-allocation. Structured logs have no restrictions on data types or context: they can be used in any code path and include any kind of information.
Because the logs are structured and strongly-typed, they can be encoded into any format. So if you don't want to work with JSON, logs can be encoded into any other representation. Caddy supports others through [log encoder modules](/docs/json/logging/logs/encoder/), and even more can be added.
**Most importantly** in the distinction between structured logs and legacy formats, a structured log can be encoded as Common Log Format (or anything else!), but not the other way around. It is non-trivial (or at least inefficient) to go from CLF to structured formats, and impossible considering the lack of information.
**Most importantly** in the distinction between structured logs and legacy formats, with a performance penalty a structured log [can be transformed into the legacy Common Log Format](https://github.com/caddyserver/transform-encoder), but not the other way around. It is non-trivial (or at least inefficient) to go from CLF to structured formats, and impossible considering the lack of information.
In essence, efficient, structured logging generally promotes these philosophies: