本記事はLangfuse Advent Calendar 2025の1日目の記事です。初日は、Langfuse を使って 簡単なアプリケーションのトレースを取得するところまでをやってみます！
TL;DR;
- SaaS版 Langfuseをセットアップ
- Pythonで簡単なアプリを作り、
@observeデコレータでトレースを送信 - LagnfuseのTracing画面で実行結果を確認
Langfuseの設定
アカウントの作成
まずは Langfuseにアクセスしアカウントを作ります。メールアドレスだけでなく、GoogleやGitHub等とのアカウントとも連携できます。お好みでどうぞ。
（アンケートが数問あるので、そのまま回答して進みます。）
アカウントが作成され、ログインできました🎉
OrganaizationとProjectの作成
Langfuseでは、ユーザーはOrganization単位でRole（Admin/Viewerなど）が付与されます。その中に複数の Projectを作成し、ProjectごとにAPI Keyを発行します。アプリケーションがトレースを送信する際は、この ProjectのAPI Keyを使用します。
関係性を図で表すと、以下のようなイメージです1。
ちなみに、プロジェクトごとにRoleを付与する機能もありますが、これはProプラン以上の契約が必要になります。
ここでは下記の名前で作成します。
- Organization name:
advent-calendar - Project name:
my-llm-project
ログインしているアカウントがOwnerとして設定されます。私の場合は、アカウト作成時にGoogleのアカウントと連携するように設定したので、アイコンや名前、メールアドレスがそのままLangfuseのアカウントして流用されています。
createでOrganaizationとProjectの作成が完了です。
API Keyの発行
Langfuseにトレースを保存するために利用するAPIキーを発行します。
Create new API keysでAPI Keysが発行されます。発行されたKeyは環境変数として設定するので、忘れないようにメモしておきましょう。
アプリケーションと連携
次に、以下のような簡単なPythonアプリにトレースを仕込みます。Langfuseの@observe()デコレータを付けるだけで、関数単位のトレースを送信できるのが特徴です。
import time
from langfuse import observe
@observe()
def process_task(task_id: int) -> str:
print(f"Task {task_id} started")
time.sleep(1)
result = f"Task {task_id} completed"
print(result)
return result
@observe()
def main():
for i in range(3):
process_task(i)
if __name__ == "__main__":
main()
@observeデコレータを利用する以外にもトレースをLangfuseに送付する方法はたくさんあります。例えば、LangChainなどのフレームワークを利用している場合は、フレームワーク用の計装方法が提供されています。自分のアプリケーションに適用する際には、まずはIntegrationsを参照して、自分が利用しているフレームワークの計装ライブラリが提供されているか確認してみると良いかもです！
アプリケーションの実行前に、環境変数に先ほど取得したAPI KeyとURLを設定しましょう。
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"
アプリケーションを実行します。
$ python main.py
Task 0 started
Task 0 completed
Task 1 started
Task 1 completed
Task 2 started
Task 2 completed
アプリケーションを実行した際に下記のようなエラーが発生する場合、環境変数 LANGFUSE_SECRET_KEY / LANGFUSE_PUBLIC_KEY / LANGFUSE_BASE_URL が設定されているか見直してみると直るかもです。
Authentication error: Langfuse client initialized without public_key. Client will be disabled. Provide a public_key parameter or set LANGFUSE_PUBLIC_KEY environment variable.
LangfuseのTracing画面から先ほど実行したアプリケーションのトレースが可視化され、下記のような情報が確認できます。
-
main関数のなかでprocess_task関数が3回呼ばれている - 全体で3秒ほど実行に時間がかかっている
- 各関数の呼び出しの階層・所要時間
さいごに
SaaS版のLangfuseを利用して、アカウント作成からアプリケーションのトレース取得までの基本的な流れを紹介しました。Langfuse自体はOSS版2もあるのですが、環境構築がやや重めです。軽く試したいだけであれば、SaaS版のFreeプランが便利なのでおすすめです。