docs(llama-index): update instrumentation integration (#848)

cookbook/integration_llama-index_instrumentation.ipynb

@@ -70,7 +70,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Add `LlamaIndexSpanHandler` via the instrumentation module of LlamaIndex:"
+        "Register the Langfuse `LlamaIndexInstrumentor`:"
       ]
     },
     {
@@ -81,11 +81,10 @@
       },
       "outputs": [],
       "source": [
-        "import llama_index.core.instrumentation as instrument\n",
-        "from langfuse.llama_index import LlamaIndexSpanHandler\n",
+        "from langfuse.llama_index import LlamaIndexInstrumentor\n",
         "\n",
-        "langfuse_span_handler = LlamaIndexSpanHandler()\n",
-        "instrument.get_dispatcher().add_span_handler(langfuse_span_handler)"
+        "instrumentor = LlamaIndexInstrumentor()\n",
+        "instrumentor.start()"
       ]
     },
     {
@@ -170,7 +169,7 @@
         "id": "1KxscR7-2NFn"
       },
       "source": [
-        "Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/5c6f2b7f-4ae5-41da-b320-24b493532657"
+        "Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/d933c7cc-20bf-4db3-810d-bab1c8d9a2a1"
       ]
     },
     {
@@ -204,10 +203,44 @@
         "id": "z5Imz4gX2S5y"
       },
       "source": [
-        "Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/f63aa1f7-8110-4a18-815c-c02d7131b984\n",
+        "Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/4e285b8f-9789-4cf0-a8b4-45473ac420f1\n",
         "\n",
         "![LlamaIndex Chat Engine Trace in Langfuse (via instrumentation module)](https://langfuse.com/images/cookbook/integration_llama-index_instrumentation_chatengine_trace.png)"
       ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Custom trace properties"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "You can use the `instrumentor.observe` context manager to manage trace IDs, set custom trace properties, and access the trace client for later scoring."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "with instrumentor.observe(user_id='my-user', session_id='my-session') as trace:\n",
+        "    response = index.as_query_engine().query(\"What did he do growing up?\")\n",
+        "\n",
+        "# Use the trace client yielded by the context manager for e.g. scoring:\n",
+        "trace.score(name=\"my-score\", value=0.5)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/6f554d6b-a2bc-4fba-904f-aa54de2897ca"
+      ]
     }
   ],
   "metadata": {

pages/docs/integrations/llama-index/example-python-instrumentation-module.md

@@ -35,15 +35,14 @@ os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region
 os.environ["OPENAI_API_KEY"] = ""
 ```
 
-Add `LlamaIndexSpanHandler` via the instrumentation module of LlamaIndex:
+Register the Langfuse `LlamaIndexInstrumentor`:
 
 
 ```python
-import llama_index.core.instrumentation as instrument
-from langfuse.llama_index import LlamaIndexSpanHandler
+from langfuse.llama_index import LlamaIndexInstrumentor
 
-langfuse_span_handler = LlamaIndexSpanHandler()
-instrument.get_dispatcher().add_span_handler(langfuse_span_handler)
+instrumentor = LlamaIndexInstrumentor()
+instrumentor.start()
 ```
 
 ## Index
@@ -81,7 +80,7 @@ print(response)
     He made home movies using a Super 8 camera.
 
 
-Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/5c6f2b7f-4ae5-41da-b320-24b493532657
+Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/d933c7cc-20bf-4db3-810d-bab1c8d9a2a1
 
 
 ```python
@@ -93,6 +92,21 @@ print(response)
     He made home movies using a Super 8 camera growing up.
 
 
-Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/f63aa1f7-8110-4a18-815c-c02d7131b984
+Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/4e285b8f-9789-4cf0-a8b4-45473ac420f1
 
 ![LlamaIndex Chat Engine Trace in Langfuse (via instrumentation module)](https://langfuse.com/images/cookbook/integration_llama-index_instrumentation_chatengine_trace.png)
+
+## Custom trace properties
+
+You can use the `instrumentor.observe` context manager to manage trace IDs, set custom trace properties, and access the trace client for later scoring.
+
+
+```python
+with instrumentor.observe(user_id='my-user', session_id='my-session') as trace:
+    response = index.as_query_engine().query("What did he do growing up?")
+
+# Use the trace client yielded by the context manager for e.g. scoring:
+trace.score(name="my-score", value=0.5)
+```
+
+Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/6f554d6b-a2bc-4fba-904f-aa54de2897ca

pages/docs/integrations/llama-index/get-started.mdx

@@ -208,13 +208,42 @@ Langfuse offers an **experimental** integration with the LlamaIndex instrumentat
 
 **NOTE**: This integration is in beta and under active development. Behavior and APIs may change in future releases.
 
+<Tabs items={["Trace all executions", "Trace specific executions / with params"]} >
+<Tab>
+```python
+from langfuse.llama_index import LlamaIndexInstrumentor
+
+instrumentor = LlamaIndexInstrumentor()
+
+# Automatically trace all LlamaIndex operations
+instrumentor.start()
+
+# ... your LlamaIndex index creation ...
+index.as_query_engine().query("What is the capital of France?")
+
+# Flush events to langfuse
+instrumentor.flush()
+```
+</Tab>
+<Tab>
 ```python
-import llama_index.core.instrumentation as instrument
-from langfuse.llama_index import LlamaIndexSpanHandler
+from langfuse.llama_index import LlamaIndexInstrumentor
+
+instrumentor = LlamaIndexInstrumentor()
+
+# Trace only a specific execution and/or pass trace params
+with instrumentor.observe(trace_id='custom-trace-id', session_id="my-session", user_id='my-user'):
+    # ... your LlamaIndex index creation ...
+
+    index.as_query_engine().query("What is the capital of France?")
 
-langfuse_span_handler = LlamaIndexSpanHandler()
-instrument.get_dispatcher().add_span_handler(langfuse_span_handler)
+# Flush events to langfuse
+instrumentor.flush()
 ```
+</Tab>
+
+
+</Tabs>
 
 Please report issues and feedback to us on [GitHub](https://github.com/langfuse/langfuse/issues/1931).
 

pages/guides/cookbook/integration_llama-index_instrumentation.md

@@ -35,15 +35,14 @@ os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region
 os.environ["OPENAI_API_KEY"] = ""
 ```
 
-Add `LlamaIndexSpanHandler` via the instrumentation module of LlamaIndex:
+Register the Langfuse `LlamaIndexInstrumentor`:
 
 
 ```python
-import llama_index.core.instrumentation as instrument
-from langfuse.llama_index import LlamaIndexSpanHandler
+from langfuse.llama_index import LlamaIndexInstrumentor
 
-langfuse_span_handler = LlamaIndexSpanHandler()
-instrument.get_dispatcher().add_span_handler(langfuse_span_handler)
+instrumentor = LlamaIndexInstrumentor()
+instrumentor.start()
 ```
 
 ## Index
@@ -81,7 +80,7 @@ print(response)
     He made home movies using a Super 8 camera.
 
 
-Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/5c6f2b7f-4ae5-41da-b320-24b493532657
+Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/d933c7cc-20bf-4db3-810d-bab1c8d9a2a1
 
 
 ```python
@@ -93,6 +92,21 @@ print(response)
     He made home movies using a Super 8 camera growing up.
 
 
-Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/f63aa1f7-8110-4a18-815c-c02d7131b984
+Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/4e285b8f-9789-4cf0-a8b4-45473ac420f1
 
 ![LlamaIndex Chat Engine Trace in Langfuse (via instrumentation module)](https://langfuse.com/images/cookbook/integration_llama-index_instrumentation_chatengine_trace.png)
+
+## Custom trace properties
+
+You can use the `instrumentor.observe` context manager to manage trace IDs, set custom trace properties, and access the trace client for later scoring.
+
+
+```python
+with instrumentor.observe(user_id='my-user', session_id='my-session') as trace:
+    response = index.as_query_engine().query("What did he do growing up?")
+
+# Use the trace client yielded by the context manager for e.g. scoring:
+trace.score(name="my-score", value=0.5)
+```
+
+Example trace: https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/6f554d6b-a2bc-4fba-904f-aa54de2897ca