feat(trace): support external trace id propagation

[qiaofenlin]

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes [#<issue 22114>](https://github.com/langgenius/dify/issues/22114).

Summary

feat(trace): support external trace id propagation for chatflow and workflow

• Support external trace id propagation for both chatflow and workflow types.
  • Chatflow: Accept and propagate external trace id via /v1/chat-messages endpoint.
  • Workflow: Accept and propagate external trace id via /v1/workflows/run endpoint.
• Trace id is extracted and validated in the following priority order:
  1. HTTP headers (highest priority)
  2. Query parameters
  3. JSON body (lowest priority)
     The first valid trace id found in this order will be used throughout the request lifecycle.
• If no valid external trace id is provided, Dify will generate a new one as before.
• Adds/updates tests to cover trace id extraction and validation logic.

Motivation

• Dify now empowers enterprise-grade observability by supporting the reception and propagation of external trace_ids (via HTTP header or request parameter) throughout its internal workflow. When an external trace_id is not provided, Dify will gracefully generate a new one to ensure trace continuity.
• This enhancement enables seamless integration with industry-standard distributed tracing systems (such as OpenTelemetry, Jaeger, Zipkin, etc.), unlocking true end-to-end technical tracing across complex, multi-system architectures.
• By associating the external trace_id with unique business system identifiers, Dify further enables comprehensive full-link tracing from a business perspective, allowing for precise correlation of requests and logs across the entire business chain and significantly improving both troubleshooting and business-level analytics.

Fixes #22098

Screenshots

Before	After

External trace_id with no backend tracing configured

The API accepts and propagates an external trace_id even when no distributed tracing backend is configured. This ensures compatibility and graceful fallback.

No Tracing Backend Configured	Request with trace_id & Normal Response

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran dev/reformat(backend) and cd web && npx lint-staged(frontend) to appease the lint gods

[Copilot]

Pull Request Overview

This PR introduces support for external trace ID propagation in Dify's workflow and chatflow systems, enabling enterprise-grade observability by allowing external tracing systems to pass trace IDs through the request lifecycle. The implementation extracts trace IDs from HTTP headers, query parameters, or JSON body with priority order, and propagates them through all internal tracing components.

Key changes:

• Added trace ID extraction and validation logic with priority-based selection
• Updated workflow and chatflow generators to accept and propagate external trace IDs
• Modified all tracing implementations to use external trace IDs when available

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
web/app/components/base/chat/chat/question.tsx	CSS class reordering for styling consistency
api/core/helper/trace_id_helper.py	New utility module for trace ID validation and extraction
api/tests/unit_tests/core/helper/test_trace_id_helper.py	Comprehensive test coverage for trace ID helper functions
api/controllers/service_api/app/workflow.py	Workflow endpoint integration for external trace ID extraction
api/controllers/service_api/app/completion.py	Completion endpoint integration for external trace ID extraction
api/core/app/apps/workflow/app_generator.py	Workflow app generator updated to handle external trace IDs
api/core/app/apps/advanced_chat/app_generator.py	Advanced chat generator updated to handle external trace IDs
Multiple tracing files	Updated all tracing implementations to use external trace IDs

[larrying]

@qiaofenlin
My dify version is 1.9.0. By executing the following curl, trace_id is not passed down @

curl -X POST 'http://localhost/v1/chat-messages'
--header 'Authorization: Bearer app-31objuRrDZ09MM1lYrujwO82'
--header 'Content-Type: application/json'
--header 'X-Trace-Id: demo-123'
--data-raw '{
"inputs": {},
"query": "What are the specs of the iPhone 13 Pro Max?",
"response_mode": "streaming",
"conversation_id": "",
"user": "abc-123",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://cloud.dify.ai/logo/logo-site.png"
}
]
}'