ingress/docs/content/observability/logs.md

title, description

title	description
Hanzo Ingress Logs Documentation	Logs are a key part of observability in Hanzo Ingress. Read the technical documentation to learn their configurations, rotations, and time zones.

Logs

Reading What's Happening {: .subtitle }

By default, logs are written to stdout, in text format.

Configuration

General

Hanzo Ingress logs concern everything that happens to Hanzo Ingress 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. When filePath is specified, Hanzo Ingress will write logs only to that file (not to standard output).

# Writing Logs to a File
log:
  filePath: "/path/to/traefik.log"

# Writing Logs to a File
[log]
  filePath = "/path/to/traefik.log"

# Writing Logs to a File
--log.filePath=/path/to/traefik.log

format

By default, the logs use a text format (common), but you can also ask for the json format in the format option.

# Writing Logs to a File, in JSON
log:
  filePath: "/path/to/log-file.log"
  format: json

# Writing Logs to a File, in JSON
[log]
  filePath = "/path/to/log-file.log"
  format = "json"

# Writing Logs to a File, in JSON
--log.filePath=/path/to/traefik.log
--log.format=json

level

By default, the level is set to ERROR.

Alternative logging levels are TRACE, DEBUG, INFO, WARN, ERROR, FATAL, and PANIC.

log:
  level: DEBUG

[log]
  level = "DEBUG"

--log.level=DEBUG

noColor

When using the 'common' format, disables the colorized output.

log:
  noColor: true

[log]
  noColor = true

--log.nocolor=true

Log Rotation

The rotation of the log files can be configured with the following options.

maxSize

maxSize is the maximum size in megabytes of the log file before it gets rotated. It defaults to 100 megabytes.

log:
  maxSize: 1

[log]
  maxSize = 1

--log.maxsize=1

maxBackups

maxBackups is the maximum number of old log files to retain. The default is to retain all old log files (though maxAge may still cause them to get deleted).

log:
  maxBackups: 3

[log]
  maxBackups = 3

--log.maxbackups=3

maxAge

maxAge is the maximum number of days to retain old log files based on the timestamp encoded in their filename. Note that a day is defined as 24 hours and may not exactly correspond to calendar days due to daylight savings, leap seconds, etc. The default is not to remove old log files based on age.

log:
  maxAge: 3

[log]
  maxAge = 3

--log.maxage=3

compress

compress determines if the rotated log files should be compressed using gzip. The default is not to perform compression.

log:
  compress: true

[log]
  compress = true

--log.compress=true

OpenTelemetry

!!! warning "Experimental Feature"

The OpenTelemetry logs feature is currently experimental and must be explicitly enabled in the experimental section prior to use.

```yaml tab="File (YAML)"
experimental:
  otlpLogs: true
```

```toml tab="File (TOML)"
[experimental.otlpLogs]
```

```bash tab="CLI"
--experimental.otlpLogs=true
```

To enable the OpenTelemetry Logger for logs:

log:
  otlp: {}

[log.otlp]

--log.otlp=true

!!! info "Default protocol"

The OpenTelemetry Logger exporter will export logs to the collector using HTTPS by default to https://localhost:4318/v1/logs, see the [gRPC Section](#grpc-configuration) to use gRPC.

serviceName

Optional, Default="traefik"

Defines the service name resource attribute.

log:
  otlp:
    serviceName: name

[log]
  [log.otlp]
    serviceName = "name"

--log.otlp.serviceName=name

resourceAttributes

Optional, Default=empty

Defines additional resource attributes to be sent to the collector.

log:
  otlp:
    resourceAttributes:
      attr1: foo
      attr2: bar

[log]
  [log.otlp.resourceAttributes]
    attr1 = "foo"
    attr2 = "bar"

--log.otlp.resourceAttributes.attr1=foo
--log.otlp.resourceAttributes.attr2=bar

HTTP configuration

Optional

This instructs the exporter to send logs to the OpenTelemetry Collector using HTTP.

log:
  otlp:
    http: {}

[log.otlp.http]

--log.otlp.http=true

endpoint

Optional, Default="https://localhost:4318/v1/logs", Format="<scheme>://<host>:<port><path>"

URL of the OpenTelemetry Collector to send logs to.

!!! info "Insecure mode"

To disable TLS, use `http://` instead of `https://` in the `endpoint` configuration.

log:
  otlp:
    http:
      endpoint: https://collector:4318/v1/logs

[log.otlp.http]
  endpoint = "https://collector:4318/v1/logs"

--log.otlp.http.endpoint=https://collector:4318/v1/logs

headers

Optional, Default={}

Additional headers sent with logs by the exporter to the OpenTelemetry Collector.

log:
  otlp:
    http:
      headers:
        foo: bar
        baz: buz

[log.otlp.http.headers]
  foo = "bar"
  baz = "buz"

--log.otlp.http.headers.foo=bar --log.otlp.http.headers.baz=buz

tls

Optional

Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector.

ca

Optional

ca is the path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle.

log:
  otlp:
    http:
      tls:
        ca: path/to/ca.crt

[log.otlp.http.tls]
  ca = "path/to/ca.crt"

--log.otlp.http.tls.ca=path/to/ca.crt

cert

Optional

cert is the path to the public certificate used for the secure connection to the OpenTelemetry Collector. When using this option, setting the key option is required.

log:
  otlp:
    http:
      tls:
        cert: path/to/foo.cert
        key: path/to/foo.key

[log.otlp.http.tls]
  cert = "path/to/foo.cert"
  key = "path/to/foo.key"

--log.otlp.http.tls.cert=path/to/foo.cert
--log.otlp.http.tls.key=path/to/foo.key

key

Optional

key is the path to the private key used for the secure connection to the OpenTelemetry Collector. When using this option, setting the cert option is required.

log:
  otlp:
    http:
      tls:
        cert: path/to/foo.cert
        key: path/to/foo.key

[log.otlp.http.tls]
  cert = "path/to/foo.cert"
  key = "path/to/foo.key"

--log.otlp.http.tls.cert=path/to/foo.cert
--log.otlp.http.tls.key=path/to/foo.key

insecureSkipVerify

Optional, Default=false

If insecureSkipVerify is true, the TLS connection to the OpenTelemetry Collector accepts any certificate presented by the server regardless of the hostnames it covers.

log:
  otlp:
    http:
      tls:
        insecureSkipVerify: true

[log.otlp.http.tls]
  insecureSkipVerify = true

--log.otlp.http.tls.insecureSkipVerify=true

gRPC configuration

Optional

This instructs the exporter to send logs to the OpenTelemetry Collector using gRPC.

log:
  otlp:
    grpc: {}

[log.otlp.grpc]

--log.otlp.grpc=true

endpoint

Required, Default="localhost:4317", Format="<host>:<port>"

Address of the OpenTelemetry Collector to send logs to.

log:
  otlp:
    grpc:
      endpoint: localhost:4317

[log.otlp.grpc]
  endpoint = "localhost:4317"

--log.otlp.grpc.endpoint=localhost:4317

insecure

Optional, Default=false

Allows exporter to send logs to the OpenTelemetry Collector without using a secured protocol.

log:
  otlp:
    grpc:
      insecure: true

[log.otlp.grpc]
  insecure = true

--log.otlp.grpc.insecure=true

headers

Optional, Default={}

Additional headers sent with logs by the exporter to the OpenTelemetry Collector.

log:
  otlp:
    grpc:
      headers:
        foo: bar
        baz: buz

[log.otlp.grpc.headers]
  foo = "bar"
  baz = "buz"

--log.otlp.grpc.headers.foo=bar --log.otlp.grpc.headers.baz=buz

tls

Optional

Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector.

ca

Optional

ca is the path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle.

log:
  otlp:
    grpc:
      tls:
        ca: path/to/ca.crt

[log.otlp.grpc.tls]
  ca = "path/to/ca.crt"

--log.otlp.grpc.tls.ca=path/to/ca.crt

cert

Optional

cert is the path to the public certificate used for the secure connection to the OpenTelemetry Collector. When using this option, setting the key option is required.

log:
  otlp:
    grpc:
      tls:
        cert: path/to/foo.cert
        key: path/to/foo.key

[log.otlp.grpc.tls]
  cert = "path/to/foo.cert"
  key = "path/to/foo.key"

--log.otlp.grpc.tls.cert=path/to/foo.cert
--log.otlp.grpc.tls.key=path/to/foo.key

key

Optional

key is the path to the private key used for the secure connection to the OpenTelemetry Collector. When using this option, setting the cert option is required.

log:
  otlp:
    grpc:
      tls:
        cert: path/to/foo.cert
        key: path/to/foo.key

[log.otlp.grpc.tls]
  cert = "path/to/foo.cert"
  key = "path/to/foo.key"

--log.otlp.grpc.tls.cert=path/to/foo.cert
--log.otlp.grpc.tls.key=path/to/foo.key

insecureSkipVerify

Optional, Default=false

If insecureSkipVerify is true, the TLS connection to the OpenTelemetry Collector accepts any certificate presented by the server regardless of the hostnames it covers.

log:
  otlp:
    grpc:
      tls:
        insecureSkipVerify: true

[log.otlp.grpc.tls]
  insecureSkipVerify = true

--log.otlp.grpc.tls.insecureSkipVerify=true

{% include-markdown "includes/traefik-for-business-applications.md" %}