😺

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を利用するのがおすすめです。
src/mastra/index.ts
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日単位でのアクティブユーザ(ユニークユーザ)数の水位を確認できるダッシュボードを作成します。
手順:

  1. 左のメニューから「DashBoards」を選択
  2. 「Widgets」を選択
  3. 「+ New Widget」ボタンをクリック
  4. 以下の項目に設定する
    • View: Traces
    • Metric: Unique User Ids, Sum
    • Chart Type: 好みのチャートタイプを選択
  5. 「Save Widget」で保存

このWidgetをダッシュボードに追加することで、左のメニューの「DashBoards」からアクティブユーザ数を確認することができます。

まとめ

本記事では、MastraのAI TracingとLangfuseの User Trackingを組み合わせて、LLMアプリにおける「ユーザ単位の挙動」を可視化する方法を紹介しました。

  • Mastra側でobservabilityにLangfuse Exporterを設定する
  • トレース送信時に userId を付与する
  • Langfuse のダッシュボードで「Unique User Ids」メトリクスを使って集計する

といった設定だけで、ユーザごとのトークン使用量やアクティブユーザ数の推移を、ダッシュボード上で簡単に把握できるようになります。

セリオ株式会社 テックブログ

Discussion