[FEATURE]: Enhance consistency between debug mode and root logger hierarchy

[shlomiuziel]

Package Name

No response

Package Version(s)

No response

Describe the goal of the feature

Since ddtrace uses the Python logging module, the logger inherits its log level from the root logger. As stated in the documentation, when the application's root logger is set to DEBUG, it requires manual adjustment of the ddtrace logger to disable debug mode.

This can cause confusion, particularly because DD_DEBUG_MODE is explicitly expected to control debug behavior. For example, the current implementation handles DD_DEBUG_MODE setting, but it does not account for cases where getEffectiveLevel() independently resolves to logging.DEBUG due to the root logger hierarchy.

To achieve a more consistent and predictable behavior, the following options are suggested:

• Logging debug mode has been enabled for the ddtrace logger not only if DD_DEBUG_MODE is set, but also when ddtrace's getEffectiveLevel() evaluates to logging.DEBUG.

• Issuing a warning log if getEffectiveLevel() evaluates to logging.DEBUG in contradiction to DD_DEBUG_MODE.

• Explicitly setting the logger to a higher level if DD_DEBUG_MODE is not enabled, but getEffectiveLevel() evaluates to logging.DEBUG

Is your feature request related to a problem?

The current behavior can lead to unexpected results that negatively impact performance:

When DEBUG mode is inadvertently enabled in third-party libraries, it can significantly degrade performance, particularly in production environments. Debug logs, by design, are verbose and can create I/O congestion, especially on web servers.

For ddtrace, this issue can be more problematic due to the frequent invocation of on_span_finish and on_span_start. These methods hold the SpanAggregator’s lock, and since on_span_finish triggers debug logging which holds the logging I/O lock, enabling debug mode introduces a risk of severe contention. High debug log pressure in this scenario (which isn't rate limited) introduces latency to the system, potentially grinding it to a halt. This behavior may resemble a deadlock when looking at the stack trace: threads (or Greenlets) yield on logging I/O operations while holding both the SpanAggregator lock and the logging I/O lock during log writes, and it prevents any creation or finalization of other spans in the meantime.

Describe alternatives you've considered

No response

Additional context

No response