Documentation Revamp

Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com>

docs/content/observability/access-logs.md

@@ -0,0 +1,152 @@
+# Access Logs
+
+Who Calls Whom?
+{.subtitle}
+
+By default, logs are written to stdout, in text format.
+
+## Configuration Examples
+
+??? example "Enabling Access Logs"
+
+    ```toml
+    [accessLog]
+    ```
+
+## Configuration Options 
+
+### filePath
+
+By default access logs are written to the standard output.
+To write the logs into a log file, use the `filePath` option.
+
+in the Common Log Format (CLF), extended with additional fields.
+
+### format
+ 
+By default, logs are written using the Common Log Format (CLF).
+To write logs in JSON, use `json` in the `format` option.
+
+!!! note "Common Log Format"
+
+#### CLF - Common Log Format
+
+    ```html
+    <remote_IP_address> - <client_user_name_if_available> [<timestamp>] "<request_method> <request_path> <request_protocol>" <origin_server_HTTP_status> <origin_server_content_size> "<request_referrer>" "<request_user_agent>" <number_of_requests_received_since_Traefik_started> "<Traefik_frontend_name>" "<Traefik_backend_URL>" <request_duration_in_ms>ms 
+    ```
+
+#### bufferingSize
+
+To write the logs in an asynchronous fashion, specify a  `bufferingSize` option.
+This option represents the number of log lines Traefik will keep in memory before writing them to the selected output.
+In some cases, this option can greatly help performances.
+
+??? example "Configuring a buffer of 100 lines"
+
+    ```toml
+    [accessLog]
+    filePath = "/path/to/access.log"
+    bufferingSize = 100
+    ```
+
+#### Filtering
+
+To filter logs, you can specify a set of filters which are logically "OR-connected". 
+Thus, specifying multiple filters will keep more access logs than specifying only one.
+
+The available filters are: 
+
+- `statusCodes`, to limit the access logs to requests with a status codes in the specified range
+- `retryAttempts`, to keep the access logs when at least one retry has happened
+- `minDuration`, to keep access logs when requests take longer than the specified duration
+
+??? example "Configuring Multiple Filters"
+
+    ```toml
+    [accessLog]
+    filePath = "/path/to/access.log"
+    format = "json"
+    
+      [accessLog.filters]    
+        statusCodes = ["200", "300-302"]
+        retryAttempts = true
+        minDuration = "10ms"
+    ```
+
+#### Limiting the Fields
+
+You can decide to limit the logged fields/headers to a given list with the `fields.names` and `fields.header` options
+
+Each field can be set to:
+
+- `keep` to keep the value
+- `drop` to drop the value
+- `redact` to replace the value with "redacted"
+
+??? example "Limiting the Logs to Specific Fields"
+
+    ```toml
+    [accessLog]
+        filePath = "/path/to/access.log"
+        format = "json"
+        
+        [accessLog.filters]
+            statusCodes = ["200", "300-302"]
+    
+        [accessLog.fields]
+            defaultMode = "keep"
+    
+            [accessLog.fields.names]
+                "ClientUsername" = "drop"
+
+            [accessLog.fields.headers]
+                defaultMode = "keep"
+        
+                [accessLog.fields.headers.names]
+                    "User-Agent" = "redact"
+                    "Authorization" = "drop"
+                    "Content-Type" = "keep"
+    ```
+    
+??? list "Available Fields"
+
+    ```ini
+    StartUTC
+    StartLocal
+    Duration
+    FrontendName
+    BackendName
+    BackendURL
+    BackendAddr
+    ClientAddr
+    ClientHost
+    ClientPort
+    ClientUsername
+    RequestAddr
+    RequestHost
+    RequestPort
+    RequestMethod
+    RequestPath
+    RequestProtocol
+    RequestLine
+    RequestContentSize
+    OriginDuration
+    OriginContentSize
+    OriginStatus
+    OriginStatusLine
+    DownstreamStatus
+    DownstreamStatusLine
+    DownstreamContentSize
+    RequestCount
+    GzipRatio
+    Overhead
+    RetryAttempts
+    ```
+
+## Log Rotation
+
+Traefik will close and reopen its log files, assuming they're configured, on receipt of a USR1 signal.
+This allows the logs to be rotated and processed by an external program, such as `logrotate`.
+
+!!! note
+    This does not work on Windows due to the lack of USR signals.

docs/content/observability/logs.md

@@ -0,0 +1,50 @@
+# Logs
+
+Reading What's Happening
+{: .subtitle }
+
+By default, logs are written to stdout, in text format.
+
+## Configuration Example
+
+??? example "Writing Logs in a File"
+
+    ```toml
+    [log]
+    filePath = "/path/to/traefik.log"
+    ```
+
+??? example "Writing Logs in a File, in JSON"
+
+    ```toml
+    [log]
+    filePath = "/path/to/log-file.log"
+    format   = "json"
+    ```
+
+## Configuration Options
+
+### General
+
+Traefik logs concern everything that happens to Traefik itself (startup, configuration, events, shutdown, and so on).
+
+#### filePath
+
+By default, the logs are written to the standard output.
+You can configure a file path instead using the `filePath` option.
+
+#### format
+
+By default, the logs use a text format (`common`), but you can also ask for the `json` format in the `format` option.   
+
+#### logLevel
+
+By default, the `logLevel` is set to `error`, but you can choose amongst `debug`, `panic`, `fatal`, `error`, `warn`, and `info`. 
+
+## Log Rotation
+
+Traefik will close and reopen its log files, assuming they're configured, on receipt of a USR1 signal.
+This allows the logs to be rotated and processed by an external program, such as `logrotate`.
+
+!!! note
+    This does not work on Windows due to the lack of USR signals.

docs/content/observability/tracing.md

@@ -0,0 +1,219 @@
+# Tracing
+
+Visualize the Requests Flow
+{: .subtitle }
+
+The tracing system allows developers to visualize call flows in their infrastructure.
+
+Traefik uses OpenTracing, an open standard designed for distributed tracing.
+
+Traefik supports three tracing backends: Jaeger, Zipkin, and DataDog.
+
+## Configuration Reference
+
+??? example "With Jaeger" 
+
+    ```toml
+    # Tracing definition
+    [tracing]
+      # Backend name used to send tracing data
+      #
+      # Default: "jaeger"
+      #
+      backend = "jaeger"
+    
+      # Service name used in Jaeger backend
+      #
+      # Default: "traefik"
+      #
+      serviceName = "traefik"
+        
+      # Span name limit allows for name truncation in case of very long Frontend/Backend names
+      # This can prevent certain tracing providers to drop traces that exceed their length limits
+      #
+      # Default: 0 - no truncation will occur
+      # 
+      spanNameLimit = 0
+    
+      [tracing.jaeger]
+        # Sampling Server URL is the address of jaeger-agent's HTTP sampling server
+        #
+        # Default: "http://localhost:5778/sampling"
+        #
+        samplingServerURL = "http://localhost:5778/sampling"
+    
+        # Sampling Type specifies the type of the sampler: const, probabilistic, rateLimiting
+        #
+        # Default: "const"
+        #
+        samplingType = "const"
+    
+        # Sampling Param is a value passed to the sampler.
+        # Valid values for Param field are:
+        #   - for "const" sampler, 0 or 1 for always false/true respectively
+        #   - for "probabilistic" sampler, a probability between 0 and 1
+        #   - for "rateLimiting" sampler, the number of spans per second
+        #
+        # Default: 1.0
+        #
+        samplingParam = 1.0
+    
+        # Local Agent Host Port instructs reporter to send spans to jaeger-agent at this address
+        #
+        # Default: "127.0.0.1:6831"
+        #
+        localAgentHostPort = "127.0.0.1:6831"
+       
+        # Generate 128-bit trace IDs, compatible with OpenCensus
+        #
+        # Default: false
+        gen128Bit = true
+       
+        # Set the propagation header type. This can be either:
+        #   - "jaeger", jaeger's default trace header.
+        #   - "b3", compatible with OpenZipkin
+        #
+        # Default: "jaeger"
+        propagation = "jaeger"
+    ```
+
+    !!! warning
+        Traefik is only able to send data over the compact thrift protocol to the [Jaeger agent](https://www.jaegertracing.io/docs/deployment/#agent).
+
+??? example "With Zipkin"
+
+    ```toml
+    # Tracing definition
+    [tracing]
+      # Backend name used to send tracing data
+      #
+      # Default: "jaeger"
+      #
+      backend = "zipkin"
+    
+      # Service name used in Zipkin backend
+      #
+      # Default: "traefik"
+      #
+      serviceName = "traefik"
+        
+      # Span name limit allows for name truncation in case of very long Frontend/Backend names
+      # This can prevent certain tracing providers to drop traces that exceed their length limits
+      #
+      # Default: 0 - no truncation will occur
+      # 
+      spanNameLimit = 150
+    
+      [tracing.zipkin]
+        # Zipkin HTTP endpoint used to send data
+        #
+        # Default: "http://localhost:9411/api/v1/spans"
+        #
+        httpEndpoint = "http://localhost:9411/api/v1/spans"
+    
+        # Enable Zipkin debug
+        #
+        # Default: false
+        #
+        debug = false
+    
+        # Use Zipkin SameSpan RPC style traces
+        #
+        # Default: false
+        #
+        sameSpan = false
+    
+        # Use Zipkin 128 bit root span IDs
+        #
+        # Default: true
+        #
+        id128Bit = true
+    
+        # The rate between 0.0 and 1.0 of requests to trace.
+        #
+        # Default: 1.0
+        #
+        sampleRate = 0.2
+    ```
+
+??? example "With DataDog"
+
+    ```toml
+    # Tracing definition
+    [tracing]
+      # Backend name used to send tracing data
+      #
+      # Default: "jaeger"
+      #
+      backend = "datadog"
+    
+      # Service name used in DataDog backend
+      #
+      # Default: "traefik"
+      #
+      serviceName = "traefik"
+      
+      # Span name limit allows for name truncation in case of very long Frontend/Backend names
+      # This can prevent certain tracing providers to drop traces that exceed their length limits
+      #
+      # Default: 0 - no truncation will occur
+      # 
+      spanNameLimit = 100
+    
+      [tracing.datadog]
+        # Local Agent Host Port instructs reporter to send spans to datadog-tracing-agent at this address
+        #
+        # Default: "127.0.0.1:8126"
+        #
+        localAgentHostPort = "127.0.0.1:8126"
+    
+        # Enable DataDog debug
+        #
+        # Default: false
+        #
+        debug = false
+    
+        # Apply shared tag in a form of Key:Value to all the traces
+        #
+        # Default: ""
+        #
+        globalTag = ""
+    ```
+    
+??? example "With Instana"
+
+    ```toml
+    # Tracing definition
+    [tracing]
+      # Backend name used to send tracing data
+      #
+      # Default: "jaeger"
+      #
+      backend = "instana"
+      # Service name used in Instana backend
+      #
+      # Default: "traefik"
+      #
+      serviceName = "traefik"
+      [tracing.instana]
+        # Local Agent Host instructs reporter to send spans to instana-agent at this address
+        #
+        # Default: "127.0.0.1"
+        #
+        localAgentHost = "127.0.0.1"
+        # Local Agent port instructs reporter to send spans to the instana-agent at this port
+        # 
+        # Default: 42699
+        #
+        localAgentPort = 42699
+        # Set Instana tracer log level
+        #
+        # Default: info
+        # Valid values for logLevel field are:
+        #   - error
+        #   - warn
+        #   - debug
+        #   - info
+        #
+        logLevel = "info"
+    ```