fix: add configurable DB_TIMEOUT environment variable for traces API

[TahirMurtaza]

Summary

Fixes #13305

Users were experiencing database timeouts when paginating through traces. This PR exposes a DB_TIMEOUT environment variable so operators can tune the query timeout without a code change.

Changes

• src/lfx/src/lfx/services/settings/groups/observability.py — Added DB_TIMEOUT setting with a sensible default

• src/backend/base/langflow/api/v1/traces.py — Wired DB_TIMEOUT into the traces DB queries

• docs/docs/Develop/environment-variables.mdx — Documented the new variable

• docs/docs/Develop/traces.mdx — Added usage note for timeout configuration

• src/backend/tests/unit/api/v1/test_traces_api.py — Unit tests for timeout behaviour

• src/lfx/tests/unit/services/settings/test_settings_composition.py — Tests for n## Testing

• Existing test suite passes

• New unit tests cover the default value and env var override

Notes

No breaking changes — the default value preserves existing behaviour.

Summary by CodeRabbit

• New Features

  • Made trace database query timeout configurable via LANGFLOW_TRACES_DB_TIMEOUT environment variable (default: 5.0 seconds) for improved flexibility on large datasets.

• Documentation

  • Added documentation for the new LANGFLOW_TRACES_DB_TIMEOUT environment variable and guidance on adjusting timeouts for large flows.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8c85a342-4fe5-431b-83f6-33d80747fa31

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This PR makes the hardcoded database timeout for trace queries (DB_TIMEOUT = 5.0) configurable through a new environment variable LANGFLOW_TRACES_DB_TIMEOUT. The trace API endpoints now retrieve the timeout from settings and apply it at request time, with supporting test and documentation updates.

Changes

Configurable Trace Database Timeout

Layer / File(s)	Summary
Settings configuration src/lfx/src/lfx/services/settings/groups/observability.py, src/lfx/tests/unit/services/settings/test_settings_composition.py	ObservabilitySettings adds traces_db_timeout (default 5.0 seconds) and the settings composition test registers this field in structural validation.
Trace endpoint timeout integration src/backend/base/langflow/api/v1/traces.py	get_traces and get_trace endpoints retrieve the configured timeout via _get_traces_db_timeout() and apply it to asyncio.wait_for; timeout logging now reports the configured value instead of a hardcoded constant.
Timeout configuration test src/backend/tests/unit/api/v1/test_traces_api.py	New test test_should_use_configured_db_timeout mocks settings and verifies the endpoint uses the configured timeout value.
User documentation docs/docs/Develop/environment-variables.mdx, docs/docs/Develop/traces.mdx	Environment variable reference and traces guide document the new LANGFLOW_TRACES_DB_TIMEOUT parameter and guidance for users experiencing timeouts on large flows.

🎯 2 (Simple) | ⏱️ ~12 minutes

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 2 warnings)

Check name	Status	Explanation	Resolution
Test Coverage For New Implementations	❌ Error	get_trace() endpoint also uses configured timeout but lacks a dedicated test for it. Also missing test coverage for field validation (positive values) despite review comment requesting Field(gt=0).	Add test for get_trace() configured timeout and add validation test ensuring traces_db_timeout rejects non-positive values.
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Test Quality And Coverage	⚠️ Warning	get_trace endpoint lacks timeout config test despite using configured timeout. Settings lack validation for invalid timeout values (zero/negative).	Add test_should_use_configured_db_timeout to TestGetTrace class. Add validation tests ensuring negative/zero timeout values are rejected per review.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly describes the main change: making DB_TIMEOUT configurable via an environment variable for the traces API, which aligns with the core modifications across settings, API endpoints, and documentation.
Linked Issues check	✅ Passed	The PR successfully addresses issue #13305 by adding a configurable environment parameter for DB_TIMEOUT in the traces API, allowing operators to adjust timeout values without code changes.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the linked issue objective: adding configurable DB_TIMEOUT. Settings definition, API integration, documentation, and unit tests are all within scope.
Test File Naming And Structure	✅ Passed	Test files follow test_*.py naming, use proper pytest fixtures, and comprehensively test positive/negative scenarios with descriptive names and logical class organization.
Excessive Mock Usage Warning	✅ Passed	Test mocking is proportional and follows intentional unit-test pattern documented in file; 3 patches for 1 clear behavior testing config flow, all appropriately scoped to external dependencies.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/lfx/tests/unit/services/settings/test_settings_composition.py (1)

102-102: ⚡ Quick win

Pin the new default value in test_critical_defaults_unchanged.

This set check protects field presence, but not the default contract. Add assert settings.traces_db_timeout == 5.0 in the defaults test so regressions are caught explicitly.

As per coding guidelines: “Tests should cover the main functionality being implemented, not just be smoke tests.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lfx/tests/unit/services/settings/test_settings_composition.py` at line
102, Update the defaults unit test to assert the new default value for
traces_db_timeout: inside the test_critical_defaults_unchanged function add an
explicit assertion that settings.traces_db_timeout == 5.0 so the test not only
verifies the field exists but also pins the default contract; locate the
test_critical_defaults_unchanged test and add the assert referencing
settings.traces_db_timeout.

Source: Coding guidelines

src/backend/tests/unit/api/v1/test_traces_api.py (1)

227-251: ⚡ Quick win

Add the same timeout-propagation assertion for get_trace.

This test covers /monitor/traces, but the PR also changed /monitor/traces/{trace_id} to use configured timeout. A mirrored test would close the regression gap for the second endpoint.

As per coding guidelines: “Verify tests cover both positive and negative scenarios where appropriate” and “Tests should cover the main functionality being implemented.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/backend/tests/unit/api/v1/test_traces_api.py` around lines 227 - 251, Add
a mirrored unit test for the single-trace endpoint that asserts the configured
DB timeout is used: copy the structure of test_should_use_configured_db_timeout
but call the GET for the /monitor/traces/{trace_id} endpoint (e.g.,
client.get(f"{self._PATH}/some-id") or the equivalent path constant), patch the
same symbols (langflow.api.v1.traces.get_settings_service returning the
MagicMock settings_service, langflow.api.v1.traces.asyncio.wait_for with the
_wait_for side effect, and the single-trace fetch function used by that
endpoint—likely langflow.api.v1.traces.fetch_trace—with a small _fetch stub),
set settings.traces_db_timeout = 30.0, then assert resp.status_code == 200 and
captured_timeouts == [30.0]; name it something like
test_should_use_configured_db_timeout_get_trace to mirror the existing test.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lfx/src/lfx/services/settings/groups/observability.py`:
- Around line 24-25: The traces_db_timeout setting is not validated and may be
zero or negative, causing immediate timeouts when used with asyncio.wait_for;
update the settings model where traces_db_timeout is declared to enforce
strictly positive values (e.g., add a Field constraint gt=0 or a pydantic
validator on traces_db_timeout) so invalid env values are rejected at load time;
ensure the validation is applied on the same settings class/field named
traces_db_timeout and that error messages clearly state the value must be > 0.

---

Nitpick comments:
In `@src/backend/tests/unit/api/v1/test_traces_api.py`:
- Around line 227-251: Add a mirrored unit test for the single-trace endpoint
that asserts the configured DB timeout is used: copy the structure of
test_should_use_configured_db_timeout but call the GET for the
/monitor/traces/{trace_id} endpoint (e.g., client.get(f"{self._PATH}/some-id")
or the equivalent path constant), patch the same symbols
(langflow.api.v1.traces.get_settings_service returning the MagicMock
settings_service, langflow.api.v1.traces.asyncio.wait_for with the _wait_for
side effect, and the single-trace fetch function used by that endpoint—likely
langflow.api.v1.traces.fetch_trace—with a small _fetch stub), set
settings.traces_db_timeout = 30.0, then assert resp.status_code == 200 and
captured_timeouts == [30.0]; name it something like
test_should_use_configured_db_timeout_get_trace to mirror the existing test.

In `@src/lfx/tests/unit/services/settings/test_settings_composition.py`:
- Line 102: Update the defaults unit test to assert the new default value for
traces_db_timeout: inside the test_critical_defaults_unchanged function add an
explicit assertion that settings.traces_db_timeout == 5.0 so the test not only
verifies the field exists but also pins the default contract; locate the
test_critical_defaults_unchanged test and add the assert referencing
settings.traces_db_timeout.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 75d0fb24-55d2-440a-8db7-c3c02532cdcd

📥 Commits

Reviewing files that changed from the base of the PR and between e26dff2 and 0595a0e.

📒 Files selected for processing (6)

• docs/docs/Develop/environment-variables.mdx
• docs/docs/Develop/traces.mdx
• src/backend/base/langflow/api/v1/traces.py
• src/backend/tests/unit/api/v1/test_traces_api.py
• src/lfx/src/lfx/services/settings/groups/observability.py
• src/lfx/tests/unit/services/settings/test_settings_composition.py