[pull] main from apache:main

docs/reference/integrations/index.rst

@@ -30,6 +30,7 @@ Integrations -- we will be adding more
    streamlit
    opentelemetry
    traceloop
+   langfuse
    langchain
    pydantic
    haystack

docs/reference/integrations/langfuse.rst

@@ -0,0 +1,73 @@
+..
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+.. _langfuseintegrationref:
+
+--------
+Langfuse
+--------
+
+`Langfuse <https://langfuse.com>`_ is an open-source LLM engineering platform with
+tracing/observability capabilities. Burr integrates with it through the
+OpenTelemetry-native Langfuse Python SDK, building on the
+:ref:`opentelemetry integration <opentelintegrationref>`.
+
+Install the integration:
+
+.. code-block:: bash
+
+    pip install "apache-burr[langfuse]"
+
+Then add the bridge as a hook -- credentials are read from the standard
+``LANGFUSE_PUBLIC_KEY``, ``LANGFUSE_SECRET_KEY``, and ``LANGFUSE_HOST``
+environment variables:
+
+.. code-block:: python
+
+    from burr.core import ApplicationBuilder
+    from burr.integrations.langfuse import LangfuseBridge
+
+    app = (
+        ApplicationBuilder()
+        .with_graph(graph)
+        .with_entrypoint("prompt")
+        .with_hooks(LangfuseBridge())
+        .build()
+    )
+    app.run(halt_after=["response"])  # logs one trace to Langfuse
+
+Each application execution call becomes a Langfuse trace, each step becomes a span
+(with state/inputs/results captured as observation input/output), and spans opened
+through Burr's :ref:`tracing API <opentelref>` become nested spans. Any additional
+OpenTelemetry LLM instrumentation (e.g. ``opentelemetry-instrumentation-openai``)
+appears nested within the corresponding Burr step.
+
+See the following resources for more information:
+
+- `Example in the repository <https://github.com/apache/burr/tree/main/examples/integrations/langfuse>`_
+- `Langfuse OpenTelemetry docs <https://langfuse.com/integrations/native/opentelemetry>`_
+
+Reference for the various useful methods:
+
+.. autoclass:: burr.integrations.langfuse.LangfuseBridge
+    :members:
+
+    .. automethod:: __init__
+
+.. autofunction:: burr.integrations.langfuse.burr_span_export_filter

examples/integrations/langfuse/README.md

@@ -0,0 +1,72 @@
+<!--
+     Licensed to the Apache Software Foundation (ASF) under one
+     or more contributor license agreements.  See the NOTICE file
+     distributed with this work for additional information
+     regarding copyright ownership.  The ASF licenses this file
+     to you under the Apache License, Version 2.0 (the
+     "License"); you may not use this file except in compliance
+     with the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+     Unless required by applicable law or agreed to in writing,
+     software distributed under the License is distributed on an
+     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+     KIND, either express or implied.  See the License for the
+     specific language governing permissions and limitations
+     under the License.
+-->
+
+# Langfuse + Burr
+
+This shows how to trace a Burr application to [Langfuse](https://langfuse.com)
+using the `LangfuseBridge` hook.
+
+What gets logged:
+
+1. One Langfuse **trace** per application execution call (`run`/`step`/`iterate`/`stream_result`/...)
+2. One **span** per step, with the action's inputs/read state as observation input and
+   its result/written state as observation output
+3. One **span** per span opened through Burr's tracing API (`__tracer`)
+4. Attributes logged via `__tracer.log_attribute(s)` as observation **metadata**
+5. Burr's `app_id` maps to the Langfuse **session** and `partition_key` to the
+   Langfuse **user** (both overridable)
+
+If you also install an OpenTelemetry LLM instrumentor (e.g.
+`opentelemetry-instrumentation-openai`), LLM calls show up as generations nested
+inside the corresponding Burr steps, with prompts/completions/token usage.
+
+## Running
+
+```bash
+pip install "apache-burr[langfuse]" openai opentelemetry-instrumentation-openai
+
+export LANGFUSE_PUBLIC_KEY="pk-lf-..."
+export LANGFUSE_SECRET_KEY="sk-lf-..."
+export LANGFUSE_HOST="https://cloud.langfuse.com"  # or your self-hosted URL
+export OPENAI_API_KEY="sk-..."
+
+python application.py
+```
+
+Then open your Langfuse project -- you will see one trace per `.run()` call, with
+the step spans, tracer spans, and (if instrumented) OpenAI generations nested inside.
+
+See [application.py](./application.py) for the full code, and the
+[integration docs](https://burr.apache.org/reference/integrations/langfuse/) for
+configuration options (custom session/user IDs, disabling state capture, passing
+your own `Langfuse` client).
+
+## Note on langfuse v4+
+
+Langfuse SDK v4+ only exports LLM-relevant spans by default. `LangfuseBridge`
+handles this automatically when it constructs the client. If you construct the
+`Langfuse` client yourself, pass the provided filter:
+
+```python
+from langfuse import Langfuse
+from burr.integrations.langfuse import LangfuseBridge, burr_span_export_filter
+
+client = Langfuse(should_export_span=burr_span_export_filter)
+bridge = LangfuseBridge(langfuse_client=client)
+```

examples/integrations/langfuse/__init__.py

@@ -0,0 +1,16 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.

examples/integrations/langfuse/application.py

@@ -0,0 +1,110 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# This is a simple chatbot to trace Langfuse
+
+"""
+Requires the following environment variables (see https://langfuse.com):
+
+- LANGFUSE_PUBLIC_KEY
+- LANGFUSE_SECRET_KEY
+- LANGFUSE_HOST (e.g. https://cloud.langfuse.com)
+- OPENAI_API_KEY
+"""
+
+from typing import Optional, Tuple
+
+import openai
+
+from burr.core import Application, ApplicationBuilder, State
+from burr.core.action import action
+from burr.integrations.langfuse import LangfuseBridge
+from burr.visibility import TracerFactory, trace
+
+try:
+    # Optional: with the openai instrumentor installed, LLM calls (prompts, completions, token usage) show up as generations nested inside Burr steps.
+    # pip install opentelemetry-instrumentation-openai
+    from opentelemetry.instrumentation.openai import OpenAIInstrumentor
+
+    OpenAIInstrumentor().instrument()
+except ImportError:
+    pass
+
+
+@action(reads=[], writes=["chat_history", "prompt"])
+def process_prompt(state: State, prompt: str) -> Tuple[dict, State]:
+    result = {"chat_item": {"role": "user", "content": prompt}}
+    return result, state.append(chat_history=result["chat_item"]).update(prompt=prompt)
+
+
+@trace()
+def _query_openai(prompt: str, chat_history: Optional[list] = None) -> str:
+    client = openai.Client()
+    result = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "system", "content": "You are a helpful assistant"},
+            *(chat_history or []),
+            {"role": "user", "content": prompt},
+        ],
+    )
+    return result.choices[0].message.content
+
+
+@action(reads=["prompt", "chat_history"], writes=["chat_history"])
+def chat_response(state: State, __tracer: TracerFactory) -> Tuple[dict, State]:
+    with __tracer("prepare_history"):
+        chat_history = state["chat_history"].copy()
+        __tracer.log_attributes(history_length=len(chat_history))
+    content = _query_openai(prompt=state["prompt"], chat_history=chat_history[:-1])
+    result = {"chat_item": {"role": "assistant", "content": content}}
+    return result, state.append(chat_history=result["chat_item"])
+
+
+def application(
+    app_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    bridge: Optional[LangfuseBridge] = None,
+) -> Application:
+    return (
+        ApplicationBuilder()
+        .with_actions(process_prompt, chat_response)
+        .with_transitions(
+            ("process_prompt", "chat_response"),
+            ("chat_response", "process_prompt"),
+        )
+        .with_state(chat_history=[])
+        .with_entrypoint("process_prompt")
+        .with_identifiers(app_id=app_id, partition_key=user_id)
+        # reads LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY/LANGFUSE_HOST from the environment.
+        # app_id maps to the Langfuse session, partition_key to the Langfuse user.
+        .with_hooks(bridge if bridge is not None else LangfuseBridge())
+        .build()
+    )
+
+
+if __name__ == "__main__":
+    bridge = LangfuseBridge()
+    app = application(user_id="example-user", bridge=bridge)
+    for user_prompt in ["What is Burr?", "And what is Langfuse?"]:
+        # each .run() call logs one trace to Langfuse
+        action_, result, state = app.run(
+            halt_after=["chat_response"], inputs={"prompt": user_prompt}
+        )
+        print(state["chat_history"][-1]["content"])
+    # flush before exiting a short-lived script -- the client batches exports
+    bridge.langfuse_client.flush()

pyproject.toml

@@ -100,6 +100,7 @@ tests = [
   "apache-burr[pymongo]",
   "apache-burr[redis]",
   "apache-burr[opentelemetry]",
+  "apache-burr[langfuse]",
   "apache-burr[haystack]",
   "apache-burr[ray]"
 ]
@@ -222,6 +223,11 @@ opentelemetry = [
   "opentelemetry-sdk",
 ]
 
+langfuse = [
+  "langfuse>=3.0.0",
+  "apache-burr[opentelemetry]",
+]
+
 ray = [
   "ray[default]"
 ]