사용자 추적

사용자 추적 (User Tracking)

Users 뷰는 모든 사용자에 대한 개요를 제공하고, 개별 사용자를 깊이 있게 들여다볼 수도 있어요. Langfuse의 데이터를 개별 사용자에 매핑하는 건 쉬워요. observation 전체에 userId 속성을 전파(propagate)하기만 하면 되죠. 이 값은 사용자 이름, 이메일, 또는 다른 고유 식별자일 수 있어요. userId는 선택 사항이지만, 사용하면 Langfuse가 사용자별로 LLM 사용 비용 같은 지표를 집계할 때 더 많은 것을 얻을 수 있어요. 자세한 내용은 통합 문서를 참고하세요.

출처: 문서

본문

제품 사용법

모든 사용자 보기

사용자 목록은 Langfuse가 추적한 모든 사용자에 대한 개요를 제공해요. 전체 토큰 사용량, 트레이스 수, 사용자 피드백 등으로 쉽게 세그먼트할 수 있어요.

개별 사용자 보기

개별 사용자 뷰는 한 사용자를 깊이 있게 보여줘요. 집계된 지표를 탐색하거나, 그 사용자의 모든 트레이스와 피드백을 볼 수 있어요.

사용자 추적 설정

Python SDKJS/TS SDKOpenAI (Python)Langchain (Python)Langchain (JS/TS)

@observe() 데코레이터를 사용할 때:

from langfuse import observe, propagate_attributes

@observe()
def process_user_request(user_query):
    # Propagate user_id to all child observations
    with propagate_attributes(user_id="user_12345"):
        # All nested observations automatically inherit user_id
        result = process_query(user_query)
        return result

observation을 직접 만들 때:

from langfuse import get_client, propagate_attributes

langfuse = get_client()

with langfuse.start_as_current_observation(
    as_type="span",
    name="process-user-request"
) as root_span:
    # Propagate user_id to all child observations
    with propagate_attributes(user_id="user_12345"):
        # All observations created here automatically have user_id
        with root_span.start_as_current_observation(
            as_type="generation",
            name="generate-response",
            model="gpt-4o"
        ) as gen:
            # This observation automatically has user_id
            pass

컨텍스트 매니저를 사용할 때:

import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";

await startActiveObservation("context-manager", async (span) => {
  span.update({
    input: { query: "What is the capital of France?" },
  });

  // Propagate userId to all child observations
  await propagateAttributes(
    {
      userId: "user-123",
    },
    async () => {
      // All observations created here automatically have userId
      // ... your logic ...
    }
  );
});

observe 래퍼를 사용할 때:

import { observe, propagateAttributes } from "@langfuse/tracing";

// An existing function
const processUserRequest = observe(
  async (userQuery: string) => {
    // Propagate userId to all child observations
    return await propagateAttributes({ userId: "user-123" }, async () => {
      // All nested observations automatically inherit userId
      const result = await processQuery(userQuery);
      return result;
    });
  },
  { name: "process-user-request" }
);

const result = await processUserRequest("some query");

자세한 내용은 JS/TS SDK docs를 참고하세요.

OpenAI (Python)

from langfuse import get_client, propagate_attributes
from langfuse.openai import openai

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="openai-call"):
    # Propagate user_id to all observations including OpenAI generation
    with propagate_attributes(user_id="user_12345"):
        completion = openai.chat.completions.create(
            name="test-chat",
            model="gpt-3.5-turbo",
            messages=[
                {"role": "system", "content": "You are a calculator."},
                {"role": "user", "content": "1 + 1 = "}
            ],
            temperature=0,
        )

Langchain (Python)

propagate_attributes()를 CallbackHandler와 함께 사용해요:

from langfuse import get_client, propagate_attributes
from langfuse.langchain import CallbackHandler

langfuse = get_client()
handler = CallbackHandler()

with langfuse.start_as_current_observation(as_type="span", name="langchain-call"):
    # Propagate user_id to all observations
    with propagate_attributes(user_id="user_12345"):
        # Pass handler to the chain invocation
        chain.invoke(
            {"animal": "dog"},
            config={"callbacks": [handler]},
        )

Langchain (JS/TS)

propagateAttributes()를 CallbackHandler와 함께 사용해요:

import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";
import { CallbackHandler } from "@langfuse/langchain";

const langfuseHandler = new CallbackHandler();

await startActiveObservation("langchain-call", async () => {
  // Propagate userId to all observations
  await propagateAttributes(
    {
      userId: "user-123",
    },
    async () => {
      // Pass handler to the chain invocation
      await chain.invoke(
        { input: "<user_input>" },
        { callbacks: [langfuseHandler] }
      );
    }
  );
});

속성 전파에 대한 참고 사항

트레이스의 모든 observation에 userId를 전파하기 위해 Attribute Propagation을 사용해요. userId가 있는 모든 observation을 사용해 userId 수준 지표를 만들 거예요. Attribute Propagation을 사용할 때 다음을 고려하세요:

값은 200자 이하의 문자열이어야 해요
모든 observation을 커버하려면 트레이스 초반에 호출하세요. 그래야 Langfuse의 모든 지표가 정확해져요.
유효하지 않은 값은 경고와 함께 버려져요

더 알아보기: Python SDK | TypeScript SDK

딥 링크

이 뷰는 다음 URL 형식으로 딥 링크할 수 있어요: https://<hostname>/project/{projectId}/users/{userId}

GitHub Discussions

이 주제에 대한 토론에 참여해 보세요.

더 알아보기 (Learn more)

출처 문서: 사용자 추적 (User Tracking)