Add New Observe Guides to the Documentation

2025-08-06 22:57:14 +02:00 · 2025-06-23 16:06:04 +01:00 · 2025-06-23 16:06:04 +01:00 · 107efb8a5a
commit 107efb8a5a
parent 0f862f4792
5 changed files with 462 additions and 1 deletions
--- a/docs/content/observe/logs-and-access-logs.md
+++ b/docs/content/observe/logs-and-access-logs.md
@ -0,0 +1,179 @@
+---
+title: "Logs and Access Logs"
+description: "Logs and Access Logs in Traefik Proxy provide real-time insight into the health of your system. They enable swift error detection and intervention through alerts. By centralizing logs, you can streamline the debugging process during incident resolution."
+---
+
+## Logs
+
+Logs concern everything that happens to Traefik itself (startup, configuration, events, shutdown, and so on).
+
+### Configuration Example
+
+To enable and configure logs in Traefik Proxy, you can use the static configuration file or Helm values if you are using the [Helm chart](https://github.com/traefik/traefik-helm-chart).
+
+```yaml tab="Structured (YAML)"
+log:
+  filePath: "/path/to/log-file.log"
+  format: json
+  level: INFO
+```
+
+```toml tab="Structured (TOML)"
+[log]
+  filePath = "/path/to/log-file.log"
+  format = "json"
+  level = "INFO"
+```
+
+```yaml tab="Helm Chart Values"
+logs:
+  general:
+    filePath: "/path/to/log-file.log"
+    format: json
+    level: INFO
+```
+
+## Access Logs
+
+Access logs concern everything that happens to the requests handled by Traefik.
+
+### Configuration Example
+
+To enable and configure access logs in Traefik Proxy, you can use the static configuration file or Helm values if you are using the [Helm chart](https://github.com/traefik/traefik-helm-chart).
+
+The following example enables access logs in JSON format, filters them to only include specific status codes, and customizes the fields that are kept or dropped.
+
+```yaml tab="Structured (YAML)"
+accessLog:
+  format: json
+  filters:
+    statusCodes:
+      - "200"
+      - "400-404"
+      - "500-503"
+  fields:
+    names:
+      ClientUsername: drop
+    headers:
+      defaultMode: keep
+      names:
+        User-Agent: redact
+        Content-Type: keep
+```
+
+```toml tab="Structured (TOML)"
+[accessLog]
+  format = "json"
+  [accessLog.filters]
+    statusCodes = ["200", "400-404", "500-503"]
+  [accessLog.fields]
+    [accessLog.fields.names]
+      ClientUsername = "drop"
+    [accessLog.fields.headers]
+      defaultMode = "keep"
+      [accessLog.fields.headers.names]
+        "User-Agent" = "redact"
+        "Content-Type" = "keep"
+```
+
+```yaml tab="Helm Chart Values"
+# values.yaml
+logs:
+  access:
+    enabled: true
+    format: json
+    filters:
+      statusCodes:
+        - "200"
+        - "400-404"
+        - "500-503"
+    fields:
+      names:
+        ClientUsername: drop
+      headers:
+        defaultMode: keep
+        names:
+          User-Agent: redact
+          Content-Type: keep
+```
+
+## Per-Router Access Logs
+
+You can enable or disable access logs for a specific router. This is useful for turning off logging for noisy routes while keeping it on globally.
+
+Here's an example of disabling access logs on a specific router:
+
+```yaml tab="Structured (YAML)"
+http:
+  routers:
+    my-router:
+      rule: "Host(`example.com`)"
+      service: my-service
+      observability:
+        accessLogs: false
+```
+
+```toml tab="Structured (TOML)"
+[http.routers.my-router.observability]
+  accessLogs = false
+```
+
+```yaml tab="Kubernetes"
+# ingressroute.yaml
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: my-router
+spec:
+  routes:
+    - kind: Rule
+      match: Host(`example.com`)
+      services:
+        - name: my-service
+          port: 80
+      observability:
+        accessLogs: false
+```
+
+```bash tab="Labels"
+labels:
+  - "traefik.http.routers.my-router.observability.accesslogs=false"
+```
+
+```json tab="Tags"
+{
+  // ...
+  "Tags": [
+    "traefik.http.routers.my-router.observability.accesslogs=false"
+  ]
+}
+```
+
+When the `observability` options are not defined on a router, it inherits the behavior from the [entrypoint's observability configuration](./overview.md), or the global one.
+
+## Log Formats
+
+Traefik Proxy supports the following log formats:
+
+- Common Log Format (CLF)
+- JSON
+
+## Access Log Filters
+
+You can configure Traefik Proxy to only record access logs for requests that match certain criteria. This is useful for reducing the volume of logs and focusing on specific events.
+
+The available filters are:
+
+- **Status Codes:** Keep logs only for requests with specific HTTP status codes or ranges (e.g., `200`, `400-404`).
+- **Retry Attempts:** Keep logs only when a request retry has occurred.
+- **Minimum Duration:** Keep logs only for requests that take longer than a specified duration.
+
+## Log Fields Customization
+
+When using the `json` format, you can customize which fields are included in your access logs.
+
+- **Request Fields:** You can choose to `keep`, `drop`, or `redact` any of the standard request fields. A complete list of available fields like `ClientHost`, `RequestMethod`, and `Duration` can be found in the [reference documentation](../reference/install-configuration/observability/logs-and-accesslogs.md#available-fields).
+- **Request Headers:** You can also specify which request headers should be included in the logs, and whether their values should be `kept`, `dropped`, or `redacted`.
+
+!!! info
+    For detailed configuration options, refer to the [reference documentation](../reference/install-configuration/observability/logs-and-accesslogs.md).
--- a/docs/content/observe/metrics.md
+++ b/docs/content/observe/metrics.md
@ -0,0 +1,104 @@
+---
+title: "Metrics"
+description: "Metrics in Traefik Proxy offer a comprehensive view of your infrastructure's health. They allow you to monitor critical indicators like incoming traffic volume. Metrics graphs and visualizations are helpful during incident triage in understanding the causes and implementing proactive measures."
+---
+
+# Metrics
+
+Metrics in Traefik Proxy offer a comprehensive view of your infrastructure's health. They allow you to monitor critical indicators like incoming traffic volume. Metrics graphs and visualizations are helpful during incident triage in understanding the causes and implementing proactive measures.
+
+## Available Metrics Providers
+
+Traefik Proxy supports the following metrics providers:
+
+- OpenTelemetry
+- Prometheus
+- Datadog
+- InfluxDB 2.X
+- StatsD
+
+## Configuration
+
+To enable metrics in Traefik Proxy, you need to configure the metrics provider in your static configuration file or helm values if you are using the [Helm chart](https://github.com/traefik/traefik-helm-chart). The following example shows how to configure the OpenTelemetry provider to send metrics to a collector.
+
+```yaml tab="Structured (YAML)"
+metrics:
+  otlp:
+    http:
+      endpoint: http://myotlpcollector:4318/v1/metrics
+```
+
+```toml tab="Structured (TOML)"
+[metrics.otlp.http]
+  endpoint = "http://myotlpcollector:4318/v1/metrics"
+```
+
+```yaml tab="Helm Chart Values"
+# values.yaml
+metrics:
+  # Disable Prometheus (enabled by default)
+  prometheus: null
+  # Enable providing OTel metrics
+  otlp:
+    enabled: true
+    http:
+      enabled: true
+      endpoint: http://myotlpcollector:4318/v1/metrics
+```
+
+## Per-Router Metrics
+
+You can enable or disable metrics collection for a specific router. This can be useful for excluding certain routes from your metrics data.
+
+Here's an example of disabling metrics on a specific router:
+
+```yaml tab="Structured (YAML)"
+http:
+  routers:
+    my-router:
+      rule: "Host(`example.com`)"
+      service: my-service
+      observability:
+        metrics: false
+```
+
+```toml tab="Structured (TOML)"
+[http.routers.my-router.observability]
+  metrics = false
+```
+
+```yaml tab="Kubernetes"
+# ingressroute.yaml
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: my-router
+spec:
+  routes:
+    - kind: Rule
+      match: Host(`example.com`)
+      services:
+        - name: my-service
+          port: 80
+      observability:
+        metrics: false
+```
+
+```bash tab="Labels"
+labels:
+  - "traefik.http.routers.my-router.observability.metrics=false"
+```
+
+```json tab="Tags"
+{
+  // ...
+  "Tags": [
+    "traefik.http.routers.my-router.observability.metrics=false"
+  ]
+}
+```
+
+When the `observability` options are not defined on a router, it inherits the behavior from the [entrypoint's observability configuration](./overview.md), or the global one.
+
+!!! info
+    For detailed configuration options, refer to the [reference documentation](../reference/install-configuration/observability/metrics.md).
--- a/docs/content/observe/overview.md
+++ b/docs/content/observe/overview.md
@ -0,0 +1,80 @@
+---
+title: "Observability Overview"
+description: "Traefik Proxy provides comprehensive monitoring and observability capabilities to maintain reliability and efficiency."
+---
+
+# Observability Overview
+
+Traefik Proxy provides comprehensive monitoring and observability capabilities to maintain reliability and efficiency:
+
+- [Logs and Access Logs](./logs-and-access-logs.md) provide real-time insight into the health of your system. They enable swift error detection and intervention through alerts. By centralizing logs, you can streamline the debugging process during incident resolution.
+
+- [Metrics](./metrics.md) offer a comprehensive view of your infrastructure's health. They allow you to monitor critical indicators like incoming traffic volume. Metrics graphs and visualizations are helpful during incident triage in understanding the causes and implementing proactive measures.
+
+- [Tracing](./tracing.md) enables tracking the flow of operations within your system. Using traces and spans, you can identify performance bottlenecks and pinpoint applications causing slowdowns to optimize response times effectively.
+
+## Configuration Example
+
+You can enable access logs, metrics, and tracing globally:
+
+```yaml tab="Structured (YAML)"
+accessLog: {}
+
+metrics:
+  otlp: {}
+
+tracing: {}
+```
+
+```toml tab="Structured (TOML)"
+[accessLog]
+
+[metrics.otlp]
+
+[tracing.otlp]
+```
+
+```yaml tab="Helm Chart Values"
+# values.yaml
+accessLog:
+  enabled: true
+
+metrics:
+  otlp:
+    enabled: true
+
+tracing:
+  otlp:
+    enabled: true
+```
+
+You can disable access logs, metrics, and tracing for a specific [entrypoint](../reference/install-configuration/entrypoints.md):
+
+```yaml tab="Structured (YAML)"
+entryPoints:
+  EntryPoint0:
+    address: ':8000/udp'
+    observability:
+      accessLogs: false
+      tracing: false
+      metrics: false
+```
+
+```toml tab="Structured (TOML)"
+[entryPoints.EntryPoint0.observability]
+  accessLogs = false
+  tracing = false
+  metrics = false
+```
+
+```yaml tab="Helm Chart Values"
+additionalArguments:
+  - "--entrypoints.entrypoint0.observability.accesslogs=false"
+  - "--entrypoints.entrypoint0.observability.tracing=false"
+  - "--entrypoints.entrypoint0.observability.metrics=false"
+```
+
+!!! note
+    A router with its own observability configuration will override the global default.
+
+{!traefik-for-business-applications.md!}
--- a/docs/content/observe/tracing.md
+++ b/docs/content/observe/tracing.md
@ -0,0 +1,93 @@
+---
+title: "Tracing"
+description: "Tracing in Traefik Proxy allows you to track the flow of operations within your system. Using traces and spans, you can identify performance bottlenecks and pinpoint applications causing slowdowns to optimize response times effectively."
+---
+
+# Tracing
+
+Tracing in Traefik Proxy allows you to track the flow of operations within your system. Using traces and spans, you can identify performance bottlenecks and pinpoint applications causing slowdowns to optimize response times effectively.
+
+Traefik Proxy uses [OpenTelemetry](https://opentelemetry.io/) to export traces. OpenTelemetry is an open-source observability framework. You can send traces to an OpenTelemetry collector, which can then export them to a variety of backends like Jaeger, Zipkin, or Datadog.
+
+## Configuration
+
+To enable tracing in Traefik Proxy, you need to configure it in your static configuration file or Helm values if you are using the [Helm chart](https://github.com/traefik/traefik-helm-chart). The following example shows how to configure the OpenTelemetry provider to send traces to a collector via HTTP.
+
+```yaml tab="Structured (YAML)"
+tracing:
+  otlp:
+    http:
+      endpoint: http://myotlpcollector:4318/v1/traces
+```
+
+```toml tab="Structured (TOML)"
+[tracing.otlp.http]
+  endpoint = "http://myotlpcollector:4318/v1/traces"
+```
+
+```yaml tab="Helm Chart Values"
+# values.yaml
+tracing:
+  otlp:
+    enabled: true
+    http:
+      enabled: true
+      endpoint: http://myotlpcollector:4318/v1/traces
+```
+
+!!! info
+    For detailed configuration options, refer to the [tracing reference documentation](../reference/install-configuration/observability/tracing.md).
+
+## Per-Router Tracing
+
+You can enable or disable tracing for a specific router. This is useful for turning off tracing for specific routes while keeping it on globally.
+
+Here's an example of disabling tracing on a specific router:
+
+```yaml tab="Structured (YAML)"
+http:
+  routers:
+    my-router:
+      rule: "Host(`example.com`)"
+      service: my-service
+      observability:
+        tracing: false
+```
+
+```toml tab="Structured (TOML)"
+[http.routers.my-router.observability]
+  tracing = false
+```
+
+```yaml tab="Kubernetes"
+# ingressoute.yaml
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: my-router
+spec:
+  routes:
+    - kind: Rule
+      match: Host(`example.com`)
+      services:
+        - name: my-service
+          port: 80
+      observability:
+        tracing: false
+```
+
+```yaml tab="Labels"
+labels:
+  - "traefik.http.routers.my-router.observability.tracing=false"
+```
+
+```json tab="Tags"
+{
+  // ...
+  "Tags": [
+    "traefik.http.routers.my-router.observability.tracing=false"
+  ]
+}
+```
+
+When the `observability` options are not defined on a router, it inherits the behavior from the [entrypoint's observability configuration](./overview.md), or the global one.
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@ -71,7 +71,12 @@ nav:
        - 'Kubernetes': 'getting-started/kubernetes.md'
        - 'Docker': 'getting-started/docker.md'
      - 'Configuration Introduction': 'getting-started/configuration-overview.md'
-      - 'Frequently Asked Questions': 'getting-started/faq.md'  
+      - 'Frequently Asked Questions': 'getting-started/faq.md'
+  - 'Observe':
+      - 'Overview': 'observe/overview.md'
+      - 'Logs & Access Logs': 'observe/logs-and-access-logs.md'
+      - 'Metrics': 'observe/metrics.md'
+      - 'Tracing': 'observe/tracing.md'
  - 'Configuration Discovery':
      - 'Overview': 'providers/overview.md'
      - 'Docker': 'providers/docker.md'