feat: add x-trace-id to http responses and logs (#29015)

Introduce trace id to http responses and logs to facilitate debugging process.

api/extensions/ext_blueprints.py

@@ -6,6 +6,7 @@ BASE_CORS_HEADERS: tuple[str, ...] = ("Content-Type", HEADER_NAME_APP_CODE, HEAD
 SERVICE_API_HEADERS: tuple[str, ...] = (*BASE_CORS_HEADERS, "Authorization")
 AUTHENTICATED_HEADERS: tuple[str, ...] = (*SERVICE_API_HEADERS, HEADER_NAME_CSRF_TOKEN)
 FILES_HEADERS: tuple[str, ...] = (*BASE_CORS_HEADERS, HEADER_NAME_CSRF_TOKEN)
+EXPOSED_HEADERS: tuple[str, ...] = ("X-Version", "X-Env", "X-Trace-Id")
 
 
 def init_app(app: DifyApp):
@@ -25,6 +26,7 @@ def init_app(app: DifyApp):
         service_api_bp,
         allow_headers=list(SERVICE_API_HEADERS),
         methods=["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH"],
+        expose_headers=list(EXPOSED_HEADERS),
     )
     app.register_blueprint(service_api_bp)
 
@@ -34,7 +36,7 @@ def init_app(app: DifyApp):
         supports_credentials=True,
         allow_headers=list(AUTHENTICATED_HEADERS),
         methods=["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH"],
-        expose_headers=["X-Version", "X-Env"],
+        expose_headers=list(EXPOSED_HEADERS),
     )
     app.register_blueprint(web_bp)
 
@@ -44,7 +46,7 @@ def init_app(app: DifyApp):
         supports_credentials=True,
         allow_headers=list(AUTHENTICATED_HEADERS),
         methods=["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH"],
-        expose_headers=["X-Version", "X-Env"],
+        expose_headers=list(EXPOSED_HEADERS),
     )
     app.register_blueprint(console_app_bp)
 
@@ -52,6 +54,7 @@ def init_app(app: DifyApp):
         files_bp,
         allow_headers=list(FILES_HEADERS),
         methods=["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH"],
+        expose_headers=list(EXPOSED_HEADERS),
     )
     app.register_blueprint(files_bp)
 
@@ -63,5 +66,6 @@ def init_app(app: DifyApp):
         trigger_bp,
         allow_headers=["Content-Type", "Authorization", "X-App-Code"],
         methods=["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH", "HEAD"],
+        expose_headers=list(EXPOSED_HEADERS),
     )
     app.register_blueprint(trigger_bp)

api/extensions/ext_logging.py

@@ -7,6 +7,7 @@ from logging.handlers import RotatingFileHandler
 import flask
 
 from configs import dify_config
+from core.helper.trace_id_helper import get_trace_id_from_otel_context
 from dify_app import DifyApp
 
 
@@ -76,7 +77,9 @@ class RequestIdFilter(logging.Filter):
     # the logging format. Note that we're checking if we're in a request
     # context, as we may want to log things before Flask is fully loaded.
     def filter(self, record):
+        trace_id = get_trace_id_from_otel_context() or ""
         record.req_id = get_request_id() if flask.has_request_context() else ""
+        record.trace_id = trace_id
         return True
 
 
@@ -84,6 +87,8 @@ class RequestIdFormatter(logging.Formatter):
     def format(self, record):
         if not hasattr(record, "req_id"):
             record.req_id = ""
+        if not hasattr(record, "trace_id"):
+            record.trace_id = ""
         return super().format(record)
 
 

api/extensions/ext_request_logging.py

@@ -1,12 +1,14 @@
 import json
 import logging
+import time
 
 import flask
 import werkzeug.http
-from flask import Flask
+from flask import Flask, g
 from flask.signals import request_finished, request_started
 
 from configs import dify_config
+from core.helper.trace_id_helper import get_trace_id_from_otel_context
 
 logger = logging.getLogger(__name__)
 
@@ -20,6 +22,9 @@ def _is_content_type_json(content_type: str) -> bool:
 
 def _log_request_started(_sender, **_extra):
     """Log the start of a request."""
+    # Record start time for access logging
+    g.__request_started_ts = time.perf_counter()
+
     if not logger.isEnabledFor(logging.DEBUG):
         return
 
@@ -42,8 +47,39 @@ def _log_request_started(_sender, **_extra):
 
 
 def _log_request_finished(_sender, response, **_extra):
-    """Log the end of a request."""
-    if not logger.isEnabledFor(logging.DEBUG) or response is None:
+    """Log the end of a request.
+
+    Safe to call with or without an active Flask request context.
+    """
+    if response is None:
+        return
+
+    # Always emit a compact access line at INFO with trace_id so it can be grepped
+    has_ctx = flask.has_request_context()
+    start_ts = getattr(g, "__request_started_ts", None) if has_ctx else None
+    duration_ms = None
+    if start_ts is not None:
+        duration_ms = round((time.perf_counter() - start_ts) * 1000, 3)
+
+    # Request attributes are available only when a request context exists
+    if has_ctx:
+        req_method = flask.request.method
+        req_path = flask.request.path
+    else:
+        req_method = "-"
+        req_path = "-"
+
+    trace_id = get_trace_id_from_otel_context() or response.headers.get("X-Trace-Id") or ""
+    logger.info(
+        "%s %s %s %s %s",
+        req_method,
+        req_path,
+        getattr(response, "status_code", "-"),
+        duration_ms if duration_ms is not None else "-",
+        trace_id,
+    )
+
+    if not logger.isEnabledFor(logging.DEBUG):
         return
 
     if not _is_content_type_json(response.content_type):