Enable debug logging

You can enable debug-level logging in the Elastic Agent by either modifying the configuration file or passing a runtime override. This is useful when troubleshooting startup issues or configuration problems.

This guide shows how to enable debug logging in different environments.

If you're running the Elastic Agent directly, you can choose between two approaches:

• Configuration file - to persist debug logging across restarts
• Temporary override: runtime flag - for temporary debugging or quick tests

Both approaches increase log verbosity and help surface misconfigurations.

Add the following section to your Elastic Agent configuration file (typically otel.yml):

service:
  telemetry:
    logs:
      level: debug

This method works across all deployment environments.

Pass the log level as a runtime argument using the --set flag:

otelcol --set=service.telemetry.logs.level=debug

This applies debug-level logging without modifying your configuration file.

If you're deploying the Elastic Agent using the OpenTelemetry Helm charts, enable debug logging by adding the configuration directly in your values.yaml file:

config:
  service:
    telemetry:
      logs:
        level: debug

Alternatively, use a CLI override when installing or upgrading the OpenTelemetry Collector Helm Chart release:

helm upgrade my-opentelemetry-collector open-telemetry/opentelemetry-collector --set mode=daemonset --set image.repository="docker.elastic.co/elastic-agent/elastic-otel-collector" --set image.tag="9.5.6" --set config.service.telemetry.logs.level=debug

This ensures the Collector logs at debug level when deployed into your cluster.

Standalone and Kubernetes are currently the only officially supported deployment environments for the Elastic Agent.

However, if you're running the Collector in a different context, such as a manually containerized setup, you can still enable debug logging using the same methods:

• Add it to your configuration file using the service.telemetry.logs.level setting

• Pass it at runtime with --set=service.telemetry.logs.level=debug

To learn how to enable debug logging for the EDOT SDKs, refer to Enable debug logging for EDOT SDKs.