메타데이터

메타데이터 (Metadata)

Observations(Langfuse Data Model 참고)에 메타데이터를 추가하면 애플리케이션을 더 잘 이해하고 Langfuse에서 observation을 상호 연관지을 수 있어요. Langfuse UI와 API에서 메타데이터 키로 필터링할 수 있어요.

출처: 문서

본문

Observations에 메타데이터를 추가하면 애플리케이션을 더 잘 이해하고 Langfuse에서 observation을 상호 연관지을 수 있어요.

Langfuse UI와 API에서 메타데이터 키로 필터링할 수 있어요.

전파된 메타데이터 (Propagated Metadata)

propagate_attributes()를 사용하면 컨텍스트 내의 모든 observation에 메타데이터가 자동으로 적용되도록 보장해요. 전파된 메타데이터는 값이 최대 200자 문자열로 제한되는 키-값 쌍이에요. 키는 영숫자 문자만 허용돼요. 메타데이터 값이 200자를 넘으면 버려져요.

Python SDK

@observe() 데코레이터 사용 시:

from langfuse import observe, propagate_attributes

@observe()
def process_data():
    # Propagate metadata to all child observations
    with propagate_attributes(
        metadata={"source": "api", "region": "us-east-1", "user_tier": "premium"}
    ):
        # All nested observations automatically inherit this metadata
        result = perform_processing()
        return result

observation을 직접 생성할 때:

from langfuse import get_client, propagate_attributes

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="process-request") as root_span:
    # Propagate metadata to all child observations
    with propagate_attributes(metadata={"request_id": "req_12345", "region": "us-east-1"}):
        # All observations created here automatically have this metadata
        with root_span.start_as_current_observation(
            as_type="generation",
            name="generate-response",
            model="gpt-4o"
        ) as gen:
            # This generation automatically has the metadata
            pass

JS/TS SDK

컨텍스트 매니저 사용 시:

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

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

  // Propagate metadata to all child observations
  await propagateAttributes(
    {
      metadata: { source: "api", region: "us-east-1", userTier: "premium" },
    },
    async () => {
      // All observations created here automatically have this metadata
      // ... your logic ...
    }
  );
});

observe 래퍼 사용 시:

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

const processData = observe(
  async (data: string) => {
    // Propagate metadata to all child observations
    return await propagateAttributes(
      { metadata: { source: "api", region: "us-east-1" } },
      async () => {
        // All nested observations automatically inherit this metadata
        const result = await performProcessing(data);
        return result;
      }
    );
  },
  { name: "process-data" }
);

const result = await processData("input");

자세한 내용은 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 metadata to all observations including OpenAI generation
    with propagate_attributes(
        metadata={"source": "api", "region": "us-east-1"}
    ):
        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,
        )

OpenAI (JS/TS)

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

await startActiveObservation("openai-call", async () => {
  // Propagate metadata to all observations
  await propagateAttributes(
    {
      metadata: { source: "api", region: "us-east-1" },
    },
    async () => {
      const res = await observeOpenAI(new OpenAI()).chat.completions.create({
        messages: [{ role: "system", content: "Tell me a story about a dog." }],
        model: "gpt-3.5-turbo",
        max_tokens: 300,
      });
    }
  );
});

Langchain (Python)

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

langfuse = get_client()
langfuse_handler = CallbackHandler()

with langfuse.start_as_current_observation(as_type="span", name="langchain-call"):
    # Propagate metadata to all child observations
    with propagate_attributes(
        metadata={"foo": "bar", "baz": "qux"}
    ):
        response = chain.invoke(
            {"topic": "cats"},
            config={"callbacks": [langfuse_handler]}
        )

Langchain (JS/TS)

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

const langfuseHandler = new CallbackHandler();

// Propagate metadata to all child observations
await propagateAttributes(
  {
    metadata: { key: "value" },
  },
  async () => {
    await chain.invoke(
      { input: "<user_input>" },
      { callbacks: [langfuseHandler] }
    );
  }
);

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

Flowise

override configs에서 메타데이터를 설정할 수 있어요. 자세한 내용은 Flowise Integration docs를 참고하세요.

속성 전파(Attribute Propagation)에 대한 참고 — 우리는 Attribute Propagation을 사용해 trace의 모든 observation에 metadata를 전파해요. metadata가 있는 모든 observation을 사용해 metadata-레벨 메트릭을 만듭니다. Attribute Propagation 사용 시 다음을 고려하세요:

  • 값은 200자 이하의 문자열이어야 해요.
  • 메타데이터 키: 영숫자만 (공백·특수 문자 없음).
  • 모든 observation이 적용되도록 trace 초기에 호출하세요. 그래야 Langfuse의 모든 메트릭이 정확해요.
  • 잘못된 값은 경고와 함께 버려져요. 자세히: Python SDK | TypeScript SDK

전파되지 않는 메타데이터 (Non-Propagated Metadata)

특정 observation에만 메타데이터를 추가할 수도 있어요.

Python SDK

# Python SDK
from langfuse import get_client

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="span", name="process-request") as root_span:
    # Add metadata to this specific observation only
    root_span.update(metadata={"stage": "parsing"})

    # ... or access span via the current context
    langfuse.update_current_span(metadata={"stage": "parsing"})

JS/TS SDK

// TypeScript SDK
import {
  startActiveObservation,
  updateActiveObservation,
} from "@langfuse/tracing";

await startActiveObservation("process-request", async (span) => {
  // Add metadata to this specific observation only
  span.update({
    metadata: { stage: "parsing" },
  })

  // ... or access span via the current context
  updateActiveObservation({
    metadata: { stage: "parsing" },
  });
});

GitHub Discussions

더 알아보기 (Learn more)