Logfire docs (#106)

Author: samuelcolvin

docs/.hooks/main.py

@@ -18,25 +18,33 @@ def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) ->
 
 
 def replace_uv_python_run(markdown: str) -> str:
-    return re.sub(r'```bash\n(.*?)(python/uv[\- ]run|pip/uv[\- ]add)(.+?)\n```', sub_run, markdown)
+    return re.sub(r'```bash\n(.*?)(python/uv[\- ]run|pip/uv[\- ]add|py-cli)(.+?)\n```', sub_run, markdown)
 
 
 def sub_run(m: re.Match[str]) -> str:
     prefix = m.group(1)
     command = m.group(2)
-    install = 'pip' in command
+    if 'pip' in command:
+        pip_base = 'pip install'
+        uv_base = 'uv add'
+    elif command == 'py-cli':
+        pip_base = ''
+        uv_base = 'uv run'
+    else:
+        pip_base = 'python'
+        uv_base = 'uv run'
     suffix = m.group(3)
     return f"""\
 === "pip"
 
     ```bash
-    {prefix}{'pip install' if install else 'python'}{suffix}
+    {prefix}{pip_base}{suffix}
     ```
 
 === "uv"
 
     ```bash
-    {prefix}uv {'add' if install else 'run'}{suffix}
+    {prefix}{uv_base}{suffix}
     ```"""
 
 

docs/examples/stream-markdown.md

@@ -4,7 +4,7 @@ It'll run the example with both OpenAI and Google Gemini models if the required
 
 Demonstrates:
 
-* streaming text responses
+* [streaming text responses](../results.md#streaming-text)
 
 ## Running the Example
 

docs/examples/stream-whales.md

@@ -2,7 +2,7 @@ Information about whales — an example of streamed structured response validati
 
 Demonstrates:
 
-* streaming structured responses
+* [streaming structured responses](../results.md#streaming-structured-responses)
 
 This script streams structured responses from GPT-4 about whales, validates the data
 and displays it as a dynamic table using [`rich`](https://github.com/Textualize/rich) as the data is received.

docs/examples/weather-agent.md

@@ -4,6 +4,7 @@ Demonstrates:
 
 * [tools](../agents.md#function-tools)
 * [agent dependencies](../dependencies.md)
+* [streaming text responses](../results.md#streaming-text)
 
 In this case the idea is a "weather" agent — the user can ask for the weather in multiple locations,
 the agent will use the `get_lat_lng` tool to get the latitude and longitude of the locations, then use

docs/img/logfire-monitoring-pydanticai.png

@@ -145,11 +145,14 @@ To understand the flow of the above runs, we can watch the agent in action using
 
 To do this, we need to set up logfire, and add the following to our code:
 
-```py title="bank_support_with_logfire.py"
-import logfire
+```py title="bank_support_with_logfire.py"  hl_lines="4-6"
+...
+from bank_database import DatabaseConn
 
+import logfire
 logfire.configure()  # (1)!
 logfire.instrument_asyncpg()  # (2)!
+...
 ```
 
 1. Configure logfire, this will fail if not project is set up.

docs/index.md

@@ -24,7 +24,7 @@ To use Logfire with PydanticAI, install `pydantic-ai` or `pydantic-ai-slim` with
 pip/uv-add 'pydantic-ai[logfire]'
 ```
 
-From there, follow the [Logfire setup docs](logfire.md#integrating-logfire) to configure Logfire.
+From there, follow the [Logfire setup docs](logfire.md#using-logfire) to configure Logfire.
 
 ## Running Examples
 

docs/install.md

@@ -1,4 +1,4 @@
-# Monitoring and Performance
+# Debugging and Monitoring
 
 Applications that use LLMs have some challenges that are well known and understood: LLMs are **slow**, **unreliable** and **expensive**.
 
@@ -15,10 +15,10 @@ LLM Observability tools that just let you understand how your model is performin
 
 ## Pydantic Logfire
 
-[Pydantic Logfire](https://pydantic.dev/logfire) is an observability platform from the developers of Pydantic and PydanticAI, that aims to let you understand your entire application: Gen AI, classic predictive AI, HTTP traffic, database queries and everything else a modern application needs.
+[Pydantic Logfire](https://pydantic.dev/logfire) is an observability platform developed by the team who created and maintain Pydantic and PydanticAI. Logfire aims to let you understand your entire application: Gen AI, classic predictive AI, HTTP traffic, database queries and everything else a modern application needs.
 
 !!! tip "Pydantic Logfire is a commercial product"
-    Logfire is a commercially supported, hosted platform with an extremely generous and perpetual free tier.
+    Logfire is a commercially supported, hosted platform with an extremely generous and perpetual [free tier](https://pydantic.dev/pricing/).
     You can sign up and start using Logfire in a couple of minutes.
 
 PydanticAI has built-in (but optional) support for Logfire via the [`logfire-api`](https://github.com/pydantic/logfire/tree/main/logfire-api) no-op package.
@@ -29,14 +29,53 @@ Here's an example showing details of running the [Weather Agent](examples/weathe
 
 ![Weather Agent Logfire](img/logfire-weather-agent.png)
 
-## Integrating Logfire
+## Using Logfire
 
-TODO
+To use logfire, you'll need a logfire [account](https://logfire.pydantic.dev), and logfire installed:
 
-## Debugging
+```bash
+pip/uv-add 'pydantic-ai[logfire]'
+```
 
-TODO
+Then authenticate your local environment with logfire:
 
-## Monitoring Performance
+```bash
+py-cli logfire auth
+```
 
-TODO
+And configure a project to send data to:
+
+```bash
+py-cli logfire projects new
+```
+
+(Or use an existing project with `logfire projects use`)
+
+The last step is to add logfire to your code:
+
+```python title="adding_logfire.py"
+import logfire
+
+logfire.configure()
+```
+
+The [logfire documentation](https://logfire.pydantic.dev/docs/) has more details on how to use logfire, including how to instrument other libraries like Pydantic, HTTPX and FastAPI.
+
+Since Logfire is build on [OpenTelemetry](https://opentelemetry.io/), you can use the Logfire Python SDK to send data to any OpenTelemetry collector.
+
+Once you have logfire set up, there are two primary ways it can help you understand your application:
+
+* **Debugging** — Using the live view to see what's happening in your application in real-time.
+* **Monitoring** — Using SQL and dashboards to observe the behavior of your application, Logfire is effectively a SQL database that stores information about how your application is running.
+
+### Debugging
+
+To demonstrate how Logfire can let you visualise the flow of a PydanticAI run, here's the view you get from Logfire while running the [chat app examples](examples/chat-app.md):
+
+{{ video('a764aff5840534dc77eba7d028707bfa', 25) }}
+
+### Monitoring Performance
+
+We can also query data with SQL in Logfire to monitor the performance of an application. Here's a real world example of using Logfire to monitor PydanticAI runs inside Logfire itself:
+
+![Logfire monitoring PydanticAI](img/logfire-monitoring-pydanticai.png)

docs/logfire.md

@@ -398,7 +398,7 @@ To get a quantitative measure of performance, we assign points to each run as fo
 
 We use 5-fold cross-validation to judge the performance of the agent using our existing set of examples.
 
-```py title="test_sql_app.py"
+```py title="sql_app_evals.py"
 import json
 import statistics
 from pathlib import Path

docs/testing-evals.md

@@ -284,6 +284,7 @@ async def run_stream(
                                     self._result_schema,
                                     deps,
                                     self._result_validators,
+                                    lambda m: run_span.set_attribute('all_messages', messages),
                                 )
                                 return
                             else: