langfuse-tracing-adapter 0.1.0

Env-only Langfuse tracing adapter for LangChain/LangGraph; callback handler as primary integration.

langfuse-tracing-adapter

Env-only Langfuse tracing adapter for LangChain/LangGraph. Callback handler is the primary integration; no @observe decorator required.

Install

pip install langfuse-tracing-adapter langfuse

Env

Set before running your app:

• LANGFUSE_BASE_URL — Langfuse server URL (e.g. http://localhost:3011)
• LANGFUSE_PUBLIC_KEY — Project public key (from Langfuse UI)
• LANGFUSE_SECRET_KEY — Project secret key
• LANGFUSE_PROJECT — Project name (optional, default "default")

Usage

1. Startup: init_client() once (e.g. FastAPI lifespan).
2. LLM runs: Pass get_callback_handler() in config: config["callbacks"] = [get_callback_handler()].
3. Optional: run_metadata_for_org(org_id, extra_tags=..., custom_metadata=...) in config for org isolation and custom metadata.
4. After run: get_context().update_current_trace(input=..., output=..., metadata=...) then flush().
5. Shutdown: flush() then shutdown().

Using the adapter in another project

1. Install: pip install langfuse-tracing-adapter langfuse
2. Env: Set LANGFUSE_BASE_URL, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_PROJECT (optional).
3. Startup: Call init_client() once (e.g. FastAPI lifespan, Django AppConfig.ready, or main).
4. LLM entry points: Pass get_callback_handler() into LangChain/LangGraph config (e.g. config["callbacks"] = [get_callback_handler()] when not None). One trace per run; no observe decorator required.
5. Optional: Use run_metadata_for_org(org_id, extra_tags=..., custom_metadata=...) in config for org isolation and custom metadata. After the run, call get_context().update_current_trace(input=..., output=..., metadata=...).
6. After request / shutdown: Call flush() so traces are sent; on shutdown call shutdown().

Publishing to PyPI

The package is universal (env-only; use in any project). To publish so others can pip install langfuse-tracing-adapter:

1. Prerequisites: PyPI account, API token (PyPI → Account settings → API tokens), and pip install build twine.
2. Bump version in pyproject.toml (e.g. 0.1.0 → 0.1.1).
3. Build: From repo root: python -m build langfuse_tracing_adapter/ — or from this dir: python -m build.
4. Upload: cd langfuse_tracing_adapter && twine upload dist/* (use TWINE_USERNAME=__token__, TWINE_PASSWORD=<pypi-token>). Test first with twine upload --repository testpypi dist/*.

Full step-by-step: see PUBLISH_TO_PYPI.md in this directory.