LangfuseのUser Trackingを使う
背景
LLMアプリを運用する際、ユーザ単位での挙動を可視化したい場面があります。
例えば、次のような観点です。
- 「ユーザ単位でどのくらいのトークン量を消費しているのか」
- 「1日ごとのアクティブユーザ数がどのくらいで推移しているのか」
Langfuseには、ユーザ単位でトレースを集計できるUser Tracking機能が用意されており、userIdをトレースに付与しておくことで、ユーザごとのトークン使用量やトレース履歴を可視化できます。
本記事では、Mastraを用いてLangfuseでユーザ単位でトレースする方法を紹介します。
事前準備
今回、Langfuseはセルフホスト版のv3.134.0を使用しました。
起動手順は、公式ドキュメントを参照してください。また、APIキーの取得方法はこちらが参考になります。
Mastraは、npm create mastraでプロジェクトを作成し、その中で"@mastra/core": "0.24.6"利用しています。
手順
Mastraのトレース設定
Mastraクラスでは、telemetryとobservabilityの2つのトレース用のプロパティがあります。
-
telemetry: OTEL互換の従来型のトレース方法です。 -
observability: AI TracingというLLMアプリに特化したトレース手法です。
AI Tracingを使うと、LLMとToolの親子関係や、各スパンの詳細ログが分かりやすく可視化されます。
特別理由がなければAI Tracingを利用するのがおすすめです。
import { Mastra } from '@mastra/core/mastra';
import { weatherWorkflow } from './workflows/weather-workflow';
import { weatherAgent } from './agents/weather-agent';
import { LangfuseExporter } from "@mastra/langfuse";
import { SamplingStrategyType } from "@mastra/core/ai-tracing";
export const langfuse_exporter = new LangfuseExporter({
realtime: true,
publicKey: process.env.LANGFUSE_PUBLIC_KEY,
secretKey: process.env.LANGFUSE_SECRET_KEY,
baseUrl: process.env.LANGFUSE_BASE_URL,
})
export const mastra = new Mastra({
workflows: { weatherWorkflow },
agents: { weatherAgent },
observability: {
configs: {
langfuse: {
serviceName: "ai",
sampling: { type: SamplingStrategyType.ALWAYS },
exporters: [
langfuse_exporter
]
}
}
}
});
トレースにUser Idを付与する
Langfuse側でユーザごとの集計を行うためには、リクエストにuserIdを付与しておく必要があります。
Mastraでは、tracingOptions.metadata.userIdにユーザ識別子を設定するだけでOKです。
.generate/.streamで使う場合
agent.generate / agent.streamの第2引数にtracingOptionsを渡します。
// .stream、generateLegacy、streamLegacyも同じ
const agentMessage = await agent.generate("テスト",{
tracingOptions: {
metadata: {
userId: <ユーザ識別子> // アプリ内で一意なユーザID
}
}
});
MastraをREST API経由で使う場合
APIから呼び出す場合も同様に、リクエストボディにtracingOptions.metadata.userIdを含めます。
curl -X POST "http://localhost:4111/api/agents/${AGENT_ID}/generate" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"messages": "今日の天気を教えて",
"tracingOptions": {
"metadata": {
"userId": <ユーザ識別子>
}
}
}'
userIdを付与しておくことで、Langfuseの左メニューにある 「Users」 からユーザ一覧と各ユーザのトレース・トークン使用量を確認できるようになり、任意のユーザを選択して、そのユーザに紐づくトレース詳細をたどることができます。


ダッシュボードでアクティブユーザ(ユニークユーザ)数を確認する
1日単位でのアクティブユーザ(ユニークユーザ)数の水位を確認できるダッシュボードを作成します。
手順:
- 左のメニューから「DashBoards」を選択
- 「Widgets」を選択
- 「+ New Widget」ボタンをクリック
- 以下の項目に設定する
- View: Traces
- Metric: Unique User Ids, Sum
- Chart Type: 好みのチャートタイプを選択
- 「Save Widget」で保存
このWidgetをダッシュボードに追加することで、左のメニューの「DashBoards」からアクティブユーザ数を確認することができます。

まとめ
本記事では、MastraのAI TracingとLangfuseの User Trackingを組み合わせて、LLMアプリにおける「ユーザ単位の挙動」を可視化する方法を紹介しました。
- Mastra側でobservabilityにLangfuse Exporterを設定する
- トレース送信時に userId を付与する
- Langfuse のダッシュボードで「Unique User Ids」メトリクスを使って集計する
といった設定だけで、ユーザごとのトークン使用量やアクティブユーザ数の推移を、ダッシュボード上で簡単に把握できるようになります。
Discussion