From 3b0a901275e63ca7a0d46a5f58bdc6d1f706ce06 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 12 Oct 2023 10:17:47 +0000 Subject: New logging system; not used yet in tipideed Signed-off-by: Laurent Bercot --- doc/tipidee.conf.html | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/tipideed.html | 41 +++++++++++++++++++---- 2 files changed, 126 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/tipidee.conf.html b/doc/tipidee.conf.html index 73620bc..57c5c29 100644 --- a/doc/tipidee.conf.html +++ b/doc/tipidee.conf.html @@ -322,6 +322,97 @@ only the index.html file will be looked up when a resource resolves to a directory. +
+

The log directive

+
+ +

+ log is also a global directive, but is introduced by the +keyword log, without prepending global. It allows +the user to control what will appear in +tipideed's log output. +

+ +

+ log nothing
+ log keyword1 keyword2 ... +

+ + + +

+ Here are the informational log lines printed by tipideed, +depending on the keywords in the log directive: +

+ +
+
nothing
Don't log anything else than warning and error messages. This +keyword cannot be given with other keywords.
+
start
Log a start line when tipideed starts + and an exit exitcode line when it exits.
+
ip
Add an ip client_ip field to the start line. +This is potentially PII, so make sure to stay compliant with your local laws if you activate it. +client_ip is read from the TCPREMOTEIP environment variable. +This keyword has no effect when given without the start keyword.
+
hostname
Add a host client_hostname field to the start line. +This is potentially PII, so make sure to stay compliant with your local laws if you activate it. +client_hostname is read from the TCPREMOTEHOST environment variable if it exists, or made up from +TCPREMOTEIP otherwise. Make sure to invoke +s6-tcpserver-access before +tipideed in order to get meaningful values for this field. +This keyword has no effect when given without the start keyword.
+
host_as_prefix
Prepend all request, resource and answer +lines with a host host field. This field will not be repeated in the request +line, so it changes the order of the fields. host is the virtual host the request is addressed +to. host_as_prefix is useful when you want to log entries for different virtual hosts to +different locations. For instance, if you're using +s6-log, and want entries for example.com and +example.org to be logged to different backends, you would use the host_as_prefix directive, +and use - +"^tipidee: pid [[:digit:]]*: info: host example\\.com " to select example.com-related +lines, and - +"^tipidee: pid [[:digit:]]*: info: host example\\.org " +to select example.org-related lines. Note that warning and error messages would still need an additional +backend, as well as start and exit lines if you add the start directive +to your log configuration.
+
request
Log a request line when tipideed +receives a request from its client. The line looks like request method host host path "path" +http version. The path is decoded, but if there are non-printable characters in it, they are +encoded as hexadecimal values \0xab. If the request line includes a query, a query query field +is added before the http field.
+
referrer
Add a referrer "referrer" field to the request line, for +requests that include a Referrer: header. referrer is quoted like path, to avoid +malicious clients messing with log lines. +This keyword has no effect when given without the request keyword.
+
user-agent
Add a user-agent "user-agent" field to the request line, for +requests that include a User-Agent: header. user-agent is quoted like path, to avoid +malicious clients messing with log lines. +This keyword has no effect when given without the request keyword.
+
resource
Log a resource line when tipideed +has found a resource corresponding to the URI and is willing to serve it. The line looks like +resource docroot docroot file file type type. docroot is +the document root of the virtual host; file is the path to the served file; type +is nph for an NPH script, cgi for a CGI script, or the Content-Type for a regular file.
+
answer
Log an answer line when tipideed +answers the currently processed request. The line looks like answer status, where status is +the 3-digit status code returned to the client.
+
size
Add a size size field to the answer line, +containing the Content-Length of the answer. +This keyword has no effect when given without the answer keyword.
+
debug
Log debug information. You should not need this in regular use.
+ +

The content-type directive

diff --git a/doc/tipideed.html b/doc/tipideed.html index 8f080bc..977317c 100644 --- a/doc/tipideed.html +++ b/doc/tipideed.html @@ -28,7 +28,7 @@ a web server package: it serves files over HTTP. 
-     tipideed [ -v verbosity ] [ -f cdbfile ] [ -d basedir ] [ -R ] [ -U ]
+     tipideed [ -f cdbfile ] [ -d basedir ] [ -R ] [ -U ]
    @@ -201,11 +201,6 @@ cannot be used by CGI scripts in a portable way.
    -
    -v verbosity
    -
    The level of log verbosity. This is the same as the global verbosity -setting in the configuration file; an explicit -command line option overrides any setting present in the configuration file.
    -
    -f file
    Use file as the compiled configuration database, typically obtained by running tipidee-config -o file. @@ -335,6 +330,40 @@ at all, your documents will most likely be accessible for HTTP/1.0 clients under @:80 or @:443.

    +
    +

    Logging

    +
    + +
      +
    • tipideed uses stderr for all its logging. All its log lines are prefixed +with "tipideed: pid pid: ".
      • +
    • The log lines continue with "fatal: " for fatal error messages (meaning +that tipideed exits right after writing the message), or "warning: " for +warnings (meaning that tipideed continues operating after writing the message). +In normal operation, you should not see any fatal or warning line.
      • +
    • In normal operation, tipidee can log informational lines, and the continuing +prefix is "info: ". It can potentially log: +
        +
      • One line when it starts (i.e. a client has connected)
        • +
      • Up to three lines for every request: +
          +
        • One when the request is received
          • +
        • One when a suitable resource is found
          • +
        • One when an answer is sent
          • +
        • +
      • One line when it exits normally
        • +
      • +
    • What informational lines to log is configured via the +log directive in the +configuration file. By default, only +a minimal request line and an answer line are printed.
      • +
    • The log format is designed to be readable by a human, but still +easily processable by automation. For instance, the regular prefix structure +makes it easy for s6-log +to select different lines to send them to various backends for archiving or +processing.
      • +
    +

    Detailed operation

    -- cgit v1.3.1