Merge pull request #3990 from ndrsfel/litellm_langfuse_metadata_from_header

feat: add langfuse metadata via proxy request headers

docs/my-website/docs/observability/langfuse_integration.md

@@ -144,6 +144,26 @@ print(response)
 
 ```
 
+You can also pass `metadata` as part of the request header with a `langfuse_*` prefix:
+
+```shell
+curl --location 'http://0.0.0.0:4000/chat/completions' \
+    --header 'Content-Type: application/json' \    
+    --header 'langfuse_trace_id: trace-id22' \
+    --header 'langfuse_trace_user_id: user-id2' \
+    --header 'langfuse_trace_metadata: {"key":"value"}' \
+    --data '{
+    "model": "gpt-3.5-turbo",
+    "messages": [
+        {
+        "role": "user",
+        "content": "what llm are you"
+        }
+    ]
+}'
+```
+
+
 ### Trace & Generation Parameters
 
 #### Trace Specific Parameters

litellm/integrations/langfuse.py

@@ -69,6 +69,28 @@ class LangFuseLogger:
         else:
             self.upstream_langfuse = None
 
+    @staticmethod
+    def add_metadata_from_header(litellm_params: dict, metadata: dict) -> dict:
+        """
+        Adds metadata from proxy request headers to Langfuse logging if keys start with "langfuse_" 
+        and overwrites litellm_params.metadata if already included.
+
+        For example if you want to append your trace to an existing `trace_id` via header, send
+        `headers: { ..., langfuse_existing_trace_id: your-existing-trace-id }` via proxy request.
+        """
+        proxy_headers = litellm_params.get("proxy_server_request", {}).get("headers", {})
+
+        for metadata_param_key in proxy_headers:
+            if metadata_param_key.startswith("langfuse_"):
+                trace_param_key = metadata_param_key.replace("langfuse_", "", 1)
+                if trace_param_key in metadata:
+                    verbose_logger.warning(f"Overwriting Langfuse `{trace_param_key}` from request header")
+                else:
+                    verbose_logger.debug(f"Found Langfuse `{trace_param_key}` in request header")
+                metadata[trace_param_key] = proxy_headers.get(metadata_param_key)
+
+        return metadata
+
     # def log_error(kwargs, response_obj, start_time, end_time):
     #     generation = trace.generation(
     #         level ="ERROR" # can be any of DEBUG, DEFAULT, WARNING or ERROR
@@ -97,6 +119,7 @@ class LangFuseLogger:
             metadata = (
                 litellm_params.get("metadata", {}) or {}
             )  # if litellm_params['metadata'] == None
+            metadata = self.add_metadata_from_header(litellm_params, metadata)
             optional_params = copy.deepcopy(kwargs.get("optional_params", {}))
 
             prompt = {"messages": kwargs.get("messages")}