Observability

Observability in FastAPI

Observability is a critical aspect of modern API platforms, providing insights into system performance, user interactions, and operational health. In FastAPI, the observability domain enables developers to monitor and manage configurations, metrics, and traces, ensuring that applications run smoothly and efficiently. This documentation outlines the key concepts, workflows, and practical examples for leveraging observability features in FastAPI.

Key Concepts

• Langfuse Config: This configuration is essential for setting up and managing observability settings for tenants and spaces. It allows customization of how data is collected and reported.
• Metrics: Metrics provide quantitative data about the system's performance over time, such as request counts, error rates, and latency. They are crucial for identifying trends and potential issues.
• Traces: Traces offer detailed records of requests through the system, capturing the path and timing of each operation. This is invaluable for debugging and performance optimization.
• Feedback: Feedback on traces allows users to annotate and provide insights on specific traces, which can be used for further analysis or improvement.

Common Workflows

1. Configuring Observability Settings:

   • Retrieve the current Langfuse configuration using the GET /v1/admin/observability/config endpoint.
   • Update the configuration with the PUT /v1/admin/observability/config endpoint to tailor observability settings to your needs.
   • Optionally, delete the configuration with DELETE /v1/admin/observability/config if no longer needed.

2. Monitoring Metrics:

   • Use the GET /v1/admin/observability/metrics endpoint to fetch metrics data. You can filter metrics by specifying from_timestamp and to_timestamp to narrow down the data range.

3. Managing Traces:

   • List all traces within a specific space using GET /v1/spaces/{space_id}/observability/traces. Use query parameters like limit, cursor, model_id, and status to refine your search.
   • Retrieve detailed information about a specific trace with GET /v1/spaces/{space_id}/observability/traces/{trace_id}.
   • Provide feedback on a trace using POST /v1/spaces/{space_id}/observability/traces/{trace_id}/feedback.

Practical Examples

Here are some practical examples using curl to demonstrate common use cases:

Retrieve Tenant Langfuse Config

curl -X GET "https://api.example.com/v1/admin/observability/config" \
     -H "X-API-Key: your_api_key"

Set Tenant Langfuse Config

curl -X PUT "https://api.example.com/v1/admin/observability/config" \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"setting1": "value1", "setting2": "value2"}'

List Traces in a Space

curl -X GET "https://api.example.com/v1/spaces/space123/observability/traces?limit=10" \
     -H "X-API-Key: your_api_key"

Provide Feedback on a Trace

curl -X POST "https://api.example.com/v1/spaces/space123/observability/traces/trace456/feedback" \
     -H "X-API-Key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"feedback": "This trace is missing data."}'

Important Considerations

• Authentication: Most endpoints require an X-API-Key header for authentication. Ensure your API key is kept secure.
• Pagination: When listing traces, use the limit and cursor parameters to handle large datasets efficiently.
• Error Handling: Always check response codes and handle errors gracefully. A 200 response indicates success, while other codes may require specific handling.

By understanding and utilizing these observability features, developers can maintain robust and efficient applications, quickly identifying and resolving issues as they arise.