> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry 트레이스를 Weave로 전송

> 전용 엔드포인트를 통해 OpenTelemetry 호환 트레이스 데이터를 임포트합니다

Weave는 전용 엔드포인트를 통해 OpenTelemetry 호환 트레이스 데이터를 임포트할 수 있도록 지원합니다. 이 엔드포인트를 사용하면 OTLP(OpenTelemetry Protocol) 형식의 트레이스 데이터를 Weave 프로젝트로 직접 전송할 수 있습니다. 기존 OTel 기반 관측성 파이프라인을 대체하지 않으면서, 애플리케이션을 OpenTelemetry 표준으로 계측하고 해당 트레이스를 다른 Weave 데이터와 함께 표시하려는 경우 이 인테그레이션을 사용하세요.

이 페이지에서는 엔드포인트 세부 정보, 인증, Python 및 TypeScript의 엔드투엔드 예시, OpenTelemetry Collector를 통해 트레이스를 전달하는 방법, 트레이스를 Weave 스레드로 구성하는 방법, 그리고 Weave가 들어오는 span에 적용하는 속성 매핑을 설명합니다.

<div id="endpoint-details">
  ## 엔드포인트 세부 정보
</div>

* **Path**: `/otel/v1/traces`
* **Method**: `POST`
* **Content-Type**: `application/x-protobuf`
* **Base URL**: OTel 트레이스 엔드포인트의 기본 URL은 W\&B 배포 유형에 따라 달라집니다.

- Multi-tenant Cloud: `https://trace.wandb.ai/otel/v1/traces`.
- Dedicated Cloud 및 Self-Managed 인스턴스: `https://<your-subdomain>.wandb.io/traces/otel/v1/traces`.

`<your-subdomain>`을 조직의 고유한 W\&B 도메인으로 바꾸세요. 예를 들어 `acme.wandb.io`가 있습니다.

<div id="authentication-and-routing">
  ## 인증 및 라우팅
</div>

Weave는 요청을 인증하기 위해 `wandb-api-key` 헤더를 사용하고, span을 올바른 entity와 프로젝트로 라우팅하기 위해 `TracerProvider`의 리소스 속성을 사용합니다.

`wandb-api-key` 헤더에 W\&B API 키를 전달한 후, `TracerProvider` 클래스에서 다음 키를 OpenTelemetry 리소스 속성으로 지정합니다:

* `wandb.entity`: W\&B 팀 이름 또는 사용자 이름입니다.
* `wandb.project`: 트레이스를 보낼 프로젝트 이름입니다.

다음 예제는 인증과 프로젝트 라우팅을 구성하는 방법을 보여줍니다:

<CodeGroup>
  ```python Python lines {7,8} theme={null}
  import os
  from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
  from opentelemetry.sdk import trace as trace_sdk
  from opentelemetry.sdk.resources import Resource

  WANDB_BASE_URL = "https://trace.wandb.ai"
  ENTITY = "<your-team-name>"
  PROJECT = "<your-project-name>"

  OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"

  # https://wandb.ai/settings 에서 API 키를 생성하세요
  WANDB_API_KEY = os.environ["WANDB_API_KEY"]

  exporter = OTLPSpanExporter(
      endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
      headers={"wandb-api-key": WANDB_API_KEY},
  )

  tracer_provider = trace_sdk.TracerProvider(resource=Resource({
      "wandb.entity": ENTITY,
      "wandb.project": PROJECT,
  }))
  ```

  ```typescript TypeScript lines theme={null}
  import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
  import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
  import { Resource } from "@opentelemetry/resources";

  const WANDB_BASE_URL = "https://trace.wandb.ai";
  const ENTITY = "<your-team-name>";
  const PROJECT = "<your-project-name>";

  const OTEL_EXPORTER_OTLP_ENDPOINT = `${WANDB_BASE_URL}/otel/v1/traces`;

  // https://wandb.ai/settings 에서 API 키를 생성하세요
  const WANDB_API_KEY = process.env.WANDB_API_KEY!;

  const exporter = new OTLPTraceExporter({
    url: OTEL_EXPORTER_OTLP_ENDPOINT,
    headers: { "wandb-api-key": WANDB_API_KEY },
  });

  const provider = new NodeTracerProvider({
    resource: new Resource({
      "wandb.entity": ENTITY,
      "wandb.project": PROJECT,
    }),
  });
  ```
</CodeGroup>

<div id="examples">
  ## 예시
</div>

다음 예시에서는 Python과 TypeScript를 사용하여 OpenTelemetry 트레이스를 Weave로 전송하는 방법을 보여줍니다. 각 예시는 서로 다른 접근 방식을 설명합니다. OpenInference 계측 라이브러리를 사용하는 방법, OpenLLMetry 계측을 사용하는 방법, 또는 계측 패키지 없이 OpenTelemetry SDK를 직접 사용하는 방법입니다.

다음 코드 샘플을 실행하기 전에 다음 필드를 설정하세요:

* `WANDB_API_KEY`: [User Settings](https://wandb.ai/settings)에서 확인할 수 있습니다.
* Entity: 액세스 권한이 있는 팀/entity 아래의 프로젝트에만 트레이스를 로그할 수 있습니다. entity 이름을 찾으려면 [W\&B 대시보드](https://wandb.ai/home)로 이동한 다음 왼쪽 사이드바의 **Teams** 필드를 확인하세요.
* 프로젝트 이름: 원하는 이름을 선택하세요.
* `OPENAI_API_KEY`: [OpenAI dashboard](https://platform.openai.com/api-keys)에서 획득할 수 있습니다.

<div id="openinference-instrumentation">
  ### OpenInference 계측
</div>

[OpenInference](https://github.com/Arize-ai/openinference)는 LLM 호출을 OpenTelemetry span으로 캡처하는 Arize AI의 오픈 소스 계측 라이브러리입니다. 이 예제에서는 OpenAI 계측을 사용하는 방법을 보여줍니다. 사용할 수 있는 계측은 이보다 훨씬 더 많으며, [공식 저장소](https://github.com/Arize-ai/openinference)에서 확인할 수 있습니다.

먼저, 필요한 의존성을 설치하세요:

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install openai openinference-instrumentation-openai opentelemetry-exporter-otlp-proto-http
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install openai @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/resources @opentelemetry/exporter-trace-otlp-proto @arizeai/openinference-instrumentation-openai @opentelemetry/api
    ```
  </Tab>
</Tabs>

<Warning>
  **성능 권장 사항**: Weave로 트레이스를 전송할 때는 항상 `SimpleSpanProcessor` 대신 `BatchSpanProcessor`를 사용하세요. `SimpleSpanProcessor`는 span을 동기식으로 내보내므로 다른 워크로드의 성능에 영향을 줄 수 있습니다. 이 예제들에서는 `BatchSpanProcessor`를 사용합니다. 이 프로세서는 span을 비동기적으로 효율적으로 일괄 처리하므로 프로덕션 환경에서 권장됩니다.
</Warning>

<Tabs>
  <Tab title="Python">
    다음 코드를 예를 들어 `openinference_example.py`와 같은 Python 파일에 붙여 넣으세요:

    ```python lines theme={null}
    import os
    import openai
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk import trace as trace_sdk
    from opentelemetry.sdk.resources import Resource
    from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
    from openinference.instrumentation.openai import OpenAIInstrumentor

    OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"
    WANDB_BASE_URL = "https://trace.wandb.ai"
    ENTITY = "<your-team-name>"
    PROJECT = "<your-project-name>"

    OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"

    # https://wandb.ai/settings 에서 API 키를 생성하세요.
    WANDB_API_KEY = os.environ["WANDB_API_KEY"]

    exporter = OTLPSpanExporter(
        endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
        headers={"wandb-api-key": WANDB_API_KEY},
    )

    tracer_provider = trace_sdk.TracerProvider(resource=Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
    }))
    tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

    # 선택 사항: 스팬을 콘솔에 출력합니다.
    tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

    OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

    def main():
        client = openai.OpenAI(api_key=OPENAI_API_KEY)
        response = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[{"role": "user", "content": "Describe OTel in a single sentence."}],
            max_tokens=20,
            stream=True,
            stream_options={"include_usage": True},
        )
        for chunk in response:
            if chunk.choices and (content := chunk.choices[0].delta.content):
                print(content, end="")

    if __name__ == "__main__":
        main()
    ```

    코드를 실행하세요:

    ```bash theme={null}
    python openinference_example.py
    ```
  </Tab>

  <Tab title="TypeScript">
    이 예제의 TypeScript 구현에는 Python 구현과 비교했을 때 다음과 같은 주요 차이점이 있습니다:

    * 계측을 등록하기 전에 OpenAI를 먼저 임포트해야 합니다(ESM 모듈에서는 이를 요구합니다).
    * W\&B 엔드포인트는 protobuf만 허용하므로, HTTP exporter 대신 `@opentelemetry/exporter-trace-otlp-proto`(protobuf 형식)를 사용합니다.
    * `BatchSpanProcessor`는 비동기적으로 플러시되므로, span이 모두 플러시되도록 종료 전에 지연 시간을 두고 `provider.shutdown()`을 명시적으로 호출해야 합니다.

    다음 코드를 `openinference_example.ts`와 같은 TypeScript 파일에 붙여 넣으세요:

    ```typescript lines {11,12} theme={null}
    // 중요: 계측이 패치할 수 있도록 OpenAI를 먼저 임포트하세요
    import OpenAI from "openai";
    import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
    import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
    import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
    import { resourceFromAttributes } from "@opentelemetry/resources";
    import { OpenAIInstrumentation, isPatched } from "@arizeai/openinference-instrumentation-openai";

    const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
    const WANDB_BASE_URL = "https://trace.wandb.ai";
    const ENTITY = "<your-team-name>";
    const PROJECT = "<your-project-name>";

    const OTEL_EXPORTER_OTLP_ENDPOINT = `${WANDB_BASE_URL}/otel/v1/traces`;

    // https://wandb.ai/settings 에서 API 키를 생성하세요
    const WANDB_API_KEY = process.env.WANDB_API_KEY!;

    const exporter = new OTLPTraceExporter({
      url: OTEL_EXPORTER_OTLP_ENDPOINT,
      headers: { "wandb-api-key": WANDB_API_KEY },
    });

    const provider = new NodeTracerProvider({
      resource: resourceFromAttributes({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
      }),
      spanProcessors: [
        new BatchSpanProcessor(exporter)
      ],
    });

    provider.register();

    // 트레이서 프로바이더에 OpenAI 계측을 등록합니다
    const openAIInstrumentation = new OpenAIInstrumentation();
    openAIInstrumentation.setTracerProvider(provider);

    // ESM을 사용하므로 OpenAI를 수동으로 계측합니다
    openAIInstrumentation.manuallyInstrument(OpenAI);

    async function main() {
      console.log("OpenAI is patched?", isPatched());

      const client = new OpenAI({ apiKey: OPENAI_API_KEY });

      console.log("Making OpenAI API call...");
      const response = await client.chat.completions.create({
        model: "gpt-3.5-turbo",
        messages: [{ role: "user", content: "Describe OTel in a single sentence." }],
        max_tokens: 50,
      });

      console.log("Response:", response.choices[0]?.message?.content);
      console.log("Waiting for spans to flush...");
    }

    (async () => {
      await main();

      // 스팬이 플러시될 시간을 확보합니다
      console.log("Waiting 2 seconds for spans to flush...");
      await new Promise(resolve => setTimeout(resolve, 2000));

      await provider.shutdown(); // 종료 전 대기 중인 모든 스팬을 플러시합니다
      console.log("Shutdown complete");
    })();
    ```

    코드를 실행하세요:

    ```bash theme={null}
    npx ts-node openinference_example.ts
    ```
  </Tab>
</Tabs>

<div id="openllmetry-instrumentation">
  ### OpenLLMetry 계측
</div>

[OpenLLMetry](https://github.com/traceloop/openllmetry)는 Traceloop에서 제공하는 오픈 소스 관측성 라이브러리로, 널리 사용되는 LLM 공급자와 프레임워크를 위한 OpenTelemetry 계측을 제공합니다. 다음 예제에서는 OpenAI 계측을 사용하는 방법을 보여줍니다. 추가 예제는 [OpenLLMetry 저장소](https://github.com/traceloop/openllmetry)에서 확인할 수 있습니다.

먼저 필요한 의존성을 설치합니다:

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install openai opentelemetry-instrumentation-openai opentelemetry-exporter-otlp-proto-http
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install openai @traceloop/instrumentation-openai @opentelemetry/sdk-trace-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Python">
    다음 코드를 `openllmetry_example.py`와 같은 Python 파일에 붙여넣으세요. 앞선 예시와 같은 코드이지만, `OpenAIInstrumentor`는 `openinference.instrumentation.openai` 대신 `opentelemetry.instrumentation.openai`에서 임포트한다는 점만 다릅니다:

    ```python lines theme={null}
    import os
    import openai
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk import trace as trace_sdk
    from opentelemetry.sdk.resources import Resource
    from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
    from opentelemetry.instrumentation.openai import OpenAIInstrumentor

    OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"
    WANDB_BASE_URL = "https://trace.wandb.ai"
    ENTITY = "<your-team-name>"
    PROJECT = "<your-project-name>"

    OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"

    # https://wandb.ai/settings 에서 API 키를 생성하세요.
    WANDB_API_KEY = os.environ["WANDB_API_KEY"]

    exporter = OTLPSpanExporter(
        endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
        headers={"wandb-api-key": WANDB_API_KEY},
    )

    tracer_provider = trace_sdk.TracerProvider(resource=Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
    }))
    tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

    # 선택 사항: 스팬을 콘솔에 출력합니다.
    tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

    OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

    def main():
        client = openai.OpenAI(api_key=OPENAI_API_KEY)
        response = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[{"role": "user", "content": "Describe OTel in a single sentence."}],
            max_tokens=20,
            stream=True,
            stream_options={"include_usage": True},
        )
        for chunk in response:
            if chunk.choices and (content := chunk.choices[0].delta.content):
                print(content, end="")

    if __name__ == "__main__":
        main()
    ```

    코드를 실행하세요:

    ```bash theme={null}
    python openllmetry_example.py
    ```
  </Tab>

  <Tab title="TypeScript">
    다음 코드를 `openllmetry_example.ts` 같은 TypeScript 파일에 붙여넣으세요. Traceloop OpenAI instrumentation 패키지를 사용합니다:

    ```typescript lines theme={null}
    import OpenAI from "openai";
    import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
    import { BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
    import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
    import { Resource } from "@opentelemetry/resources";
    import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";
    import { registerInstrumentations } from "@opentelemetry/instrumentation";

    const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
    const WANDB_BASE_URL = "https://trace.wandb.ai";
    const ENTITY = "<your-team-name>";
    const PROJECT = "<your-project-name>";

    const OTEL_EXPORTER_OTLP_ENDPOINT = `${WANDB_BASE_URL}/otel/v1/traces`;

    // https://wandb.ai/settings 에서 API 키를 생성하세요.
    const WANDB_API_KEY = process.env.WANDB_API_KEY!;

    const exporter = new OTLPTraceExporter({
      url: OTEL_EXPORTER_OTLP_ENDPOINT,
      headers: { "wandb-api-key": WANDB_API_KEY },
    });

    const provider = new NodeTracerProvider({
      resource: new Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
      }),
      spanProcessors: [
        new BatchSpanProcessor(exporter),
        // 선택 사항: 스팬을 콘솔에 출력합니다.
        new BatchSpanProcessor(new ConsoleSpanExporter()),
      ],
    });

    provider.register();

    // 트레이서 프로바이더에 OpenAI 계측을 등록합니다.
    const openAIInstrumentation = new OpenAIInstrumentation();
    registerInstrumentations({
      tracerProvider: provider,
      instrumentations: [openAIInstrumentation],
    });

    // ESM을 사용하므로 OpenAI를 수동으로 계측합니다.
    openAIInstrumentation.manuallyInstrument(OpenAI);

    async function main() {
      const client = new OpenAI({ apiKey: OPENAI_API_KEY });
      const stream = await client.chat.completions.create({
        model: "gpt-3.5-turbo",
        messages: [{ role: "user", content: "Describe OTel in a single sentence." }],
        max_tokens: 20,
        stream: true,
      });

      for await (const chunk of stream) {
        const content = chunk.choices[0]?.delta?.content;
        if (content) {
          process.stdout.write(content);
        }
      }
      console.log(); // 스트리밍 후 줄바꿈
    }

    (async () => {
      await main();

      // 스팬을 플러시할 시간을 확보합니다.
      await new Promise(resolve => setTimeout(resolve, 2000));

      await provider.shutdown(); // 종료 전 대기 중인 모든 스팬을 플러시합니다.
    })();
    ```

    코드를 실행하세요:

    ```bash theme={null}
    npx ts-node openllmetry_example.ts
    ```
  </Tab>
</Tabs>

<div id="without-instrumentation">
  ### 계측 없이
</div>

계측 패키지 대신 OTel을 직접 사용하려면 그렇게 해도 됩니다. 이 접근 방식을 사용하면 각 span에 설정할 속성을 완전히 제어할 수 있습니다. 스팬 속성은 [https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)에 설명된 OpenTelemetry 시맨틱 규약에 따라 해석됩니다.

먼저 필요한 의존성을 설치합니다:

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install openai opentelemetry-sdk opentelemetry-api opentelemetry-exporter-otlp-proto-http
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install openai @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Python">
    다음 코드를 `opentelemetry_example.py`와 같은 Python 파일에 붙여 넣으세요:

    ```python lines theme={null}
    import json
    import os
    import openai
    from opentelemetry import trace
    from opentelemetry.sdk import trace as trace_sdk
    from opentelemetry.sdk.resources import Resource
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor

    OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"
    WANDB_BASE_URL = "https://trace.wandb.ai"
    ENTITY = "<your-team-name>"
    PROJECT = "<your-project-name>"

    OTEL_EXPORTER_OTLP_ENDPOINT = f"{WANDB_BASE_URL}/otel/v1/traces"

    # https://wandb.ai/settings 에서 API 키를 생성하세요.
    WANDB_API_KEY = os.environ["WANDB_API_KEY"]

    # OTLP 내보내기 도구를 구성합니다.
    exporter = OTLPSpanExporter(
        endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
        headers={"wandb-api-key": WANDB_API_KEY},
    )

    tracer_provider = trace_sdk.TracerProvider(resource=Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
    }))
    tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

    # 필요에 따라 스팬을 콘솔에 출력합니다.
    tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

    # 트레이서 프로바이더를 설정합니다.
    trace.set_tracer_provider(tracer_provider)

    # 전역 트레이서 프로바이더에서 트레이서를 생성합니다.
    tracer = trace.get_tracer(__name__)

    def my_function():
        with tracer.start_as_current_span("outer_span") as outer_span:
            client = openai.OpenAI()
            input_messages = [{"role": "user", "content": "Describe OTel in a single sentence."}]
            outer_span.set_attribute("input.value", json.dumps(input_messages))
            outer_span.set_attribute("gen_ai.system", "openai")
            response = client.chat.completions.create(
                model="gpt-3.5-turbo",
                messages=input_messages,
                max_tokens=20,
                stream=True,
                stream_options={"include_usage": True},
            )
            out = ""
            for chunk in response:
                if chunk.choices and (content := chunk.choices[0].delta.content):
                    out += content
            outer_span.set_attribute("output.value", json.dumps({"content": out}))

    if __name__ == "__main__":
        my_function()
    ```

    코드를 실행하세요:

    ```bash theme={null}
    python opentelemetry_example.py
    ```
  </Tab>

  <Tab title="TypeScript">
    다음 코드를 `opentelemetry_example.ts` 같은 TypeScript 파일에 붙여 넣으세요:

    ```typescript lines theme={null}
    import OpenAI from "openai";
    import { trace } from "@opentelemetry/api";
    import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
    import { BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
    import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
    import { Resource } from "@opentelemetry/resources";

    const OPENAI_API_KEY = "YOUR_OPENAI_API_KEY";
    const WANDB_BASE_URL = "https://trace.wandb.ai";
    const ENTITY = "<your-team-name>";
    const PROJECT = "<your-project-name>";

    const OTEL_EXPORTER_OTLP_ENDPOINT = `${WANDB_BASE_URL}/otel/v1/traces`;

    // https://wandb.ai/settings 에서 API 키를 생성하세요.
    const WANDB_API_KEY = process.env.WANDB_API_KEY!;

    const exporter = new OTLPTraceExporter({
      url: OTEL_EXPORTER_OTLP_ENDPOINT,
      headers: { "wandb-api-key": WANDB_API_KEY },
    });

    const provider = new NodeTracerProvider({
      resource: new Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
      }),
      spanProcessors: [
        new BatchSpanProcessor(exporter),
        // 선택 사항: 스팬을 콘솔에 출력합니다.
        new BatchSpanProcessor(new ConsoleSpanExporter()),
      ],
    });

    provider.register();

    // 전역 트레이서 프로바이더에서 트레이서를 생성합니다.
    const tracer = trace.getTracer("my-app");

    async function myFunction() {
      const span = tracer.startSpan("outer_span");

      try {
        const client = new OpenAI({ apiKey: OPENAI_API_KEY });
        const inputMessages = [
          { role: "user" as const, content: "Describe OTel in a single sentence." },
        ];

        // 사이드 패널에만 표시됩니다.
        span.setAttribute("input.value", JSON.stringify(inputMessages));
        
        // 규칙을 따르며 대시보드에 표시됩니다.
        span.setAttribute("gen_ai.system", "openai");

        const stream = await client.chat.completions.create({
          model: "gpt-3.5-turbo",
          messages: inputMessages,
          max_tokens: 20,
          stream: true,
        });

        let output = "";
        for await (const chunk of stream) {
          const content = chunk.choices[0]?.delta?.content;
          if (content) {
            output += content;
          }
          }

        // 사이드 패널에만 표시됩니다.
        span.setAttribute("output.value", JSON.stringify({ content: output }));
      } finally {
        span.end();
      }
    }

    myFunction();
    ```

    코드를 실행하세요:

    ```bash theme={null}
    npx ts-node opentelemetry_example.ts
    ```
  </Tab>
</Tabs>

Weave는 트레이스를 해석할 때 어떤 규약을 사용할지 확인하기 위해 span 속성 접두사 `gen_ai`와 `openinference`를 사용합니다. 두 키가 모두 감지되지 않으면 모든 span 속성이 트레이스 뷰에 표시됩니다. 트레이스를 선택하면 사이드 패널에서 전체 span을 볼 수 있습니다.

<div id="use-an-opentelemetry-collector">
  ## OpenTelemetry Collector 사용하기
</div>

이전 예시에서는 애플리케이션에서 Weave로 트레이스를 직접 전송합니다. 프로덕션 환경에서는 애플리케이션과 Weave 사이의 중간 계층으로 [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)를 사용할 수 있습니다. Collector는 앱에서 트레이스를 수신한 다음 하나 이상의 백엔드로 전달합니다. 이 패턴을 사용하면 인증, 배치 처리, 라우팅 로직을 애플리케이션 코드 외부에서 중앙화할 수 있으며, 단일 파이프라인에서 여러 관측성 백엔드로 트레이스를 분산 전송할 수 있습니다.

<div id="set-up-a-collector">
  ### collector 설정하기
</div>

이 섹션에서는 Docker에서 로컬 OpenTelemetry Collector를 실행하고, 애플리케이션이 해당 collector로 트레이스를 보내도록 구성하는 과정을 설명합니다. 다음 예제에서는 다음을 수행하는 방법을 보여줍니다:

* OTLP 트레이스를 수신하고, 이를 일괄 처리한 뒤 Weave로 전달하는 로컬 서버(collector)를 배포하는 Docker 설정 파일을 설정합니다.
* Docker를 사용해 로컬에서 collector를 실행합니다.
* 도커 컨테이너에서 실행 중인 collector로 트레이스를 전달하는 기본 OpenAI Call을 전송합니다.

collector를 사용하려면 먼저 collector가 OTLP 트레이스를 수신하고 이를 Weave로 내보내도록 구성하는 `collector-config.yaml` 파일을 만드세요:

```yaml lines {23,26} collector-config.yaml title="collector-config.yaml"  theme={null}
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlphttp/weave:
    endpoint: ${env:WANDB_OTLP_ENDPOINT}
    headers:
      wandb-api-key: ${env:WANDB_API_KEY}
    sending_queue:
      batch:

processors:
  resource:
    attributes:
      - key: wandb.entity # 리소스 속성 필드
        value: ${env:DEFAULT_WANDB_ENTITY}  # 주입할 값
        action: insert # 아직 설정되어 있지 않은 경우에만 주입
      - key: wandb.project
        value: ${env:DEFAULT_WANDB_PROJECT}
        action: insert 

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resource]
      exporters: [otlphttp/weave]
```

이 설정 파일은 다음을 수행합니다.

* 포트 `4318`(HTTP)에서 OTLP 트레이스를 수신합니다.
* `wandb-api-key` 헤더를 사용해 Weave의 OTLP 엔드포인트로 트레이스를 내보내며, 엔드포인트 URL은 `WANDB_OTLP_ENDPOINT`에서, API 키는 `WANDB_API_KEY`에서 읽어옵니다.
* `resource` 프로세서를 사용해 `wandb.entity`와 `wandb.project`를 리소스 속성으로 설정하고, 값은 `DEFAULT_WANDB_ENTITY`와 `DEFAULT_WANDB_PROJECT`에서 읽어옵니다. `insert` action은 애플리케이션 코드에서 이러한 속성을 이미 설정하지 않은 경우에만 속성을 주입합니다.
* 네트워크 오버헤드를 줄이기 위해 exporter에 내장된 `sending_queue`를 배치 처리와 함께 활성화합니다.

collector 설정을 완료한 후, 다음 Docker command에서 API 및 entity 값을 업데이트한 뒤 실행합니다:

```bash lines {3,5} theme={null}
docker run \
  -v ./config.yaml:/etc/otelcol-contrib/config.yaml \
  -e WANDB_API_KEY="<your-wandb-api-key>" \
  -e WANDB_OTLP_ENDPOINT="https://trace.wandb.ai/otel" \
  -e DEFAULT_WANDB_ENTITY="<your-team-name>" \
  -e DEFAULT_WANDB_PROJECT="YOUR_PROJECT" \
  -p 4318:4318 \
  otel/opentelemetry-collector-contrib:latest
```

collector가 실행되면 `OTEL_EXPORTER_OTLP_ENDPOINT` 환경 변수를 설정해 애플리케이션이 해당 엔드포인트로 트레이스를 내보내도록 구성하세요. OTel SDK는 이 변수를 자동으로 읽으므로 exporter에 엔드포인트를 전달할 필요가 없습니다.

애플리케이션의 `TracerProvider`에서 `wandb.entity` 또는 `wandb.project`를 리소스 속성으로 설정하면 collector 설정에 정의된 기본값보다 우선합니다.

<CodeGroup>
  ```python Python lines theme={null}
  import os
  import openai
  from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
  from opentelemetry.sdk import trace as trace_sdk
  from opentelemetry.sdk.trace.export import BatchSpanProcessor
  from openinference.instrumentation.openai import OpenAIInstrumentor

  os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4318"

  OPENAI_API_KEY = "YOUR_OPENAI_API_KEY"

  tracer_provider = trace_sdk.TracerProvider()
  tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

  OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

  def main():
      client = openai.OpenAI(api_key=OPENAI_API_KEY)
      response = client.chat.completions.create(
          model="gpt-3.5-turbo",
          messages=[{"role": "user", "content": "Describe OTel in a single sentence."}],
          max_tokens=20,
      )
      print(response.choices[0].message.content)

  if __name__ == "__main__":
      main()
  ```

  ```typescript TypeScript lines theme={null}
  import OpenAI from "openai";
  import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
  import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
  import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
  import { OpenAIInstrumentation, isPatched } from "@arizeai/openinference-instrumentation-openai";

  process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318";

  const OPENAI_API_KEY = process.env.OPENAI_API_KEY;

  const provider = new NodeTracerProvider({
    spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter())],
  });

  provider.register();

  const openAIInstrumentation = new OpenAIInstrumentation();
  openAIInstrumentation.setTracerProvider(provider);
  openAIInstrumentation.manuallyInstrument(OpenAI);

  async function main() {
    console.log("OpenAI is patched?", isPatched());

    const client = new OpenAI({ apiKey: OPENAI_API_KEY });
    const response = await client.chat.completions.create({
      model: "gpt-3.5-turbo",
      messages: [{ role: "user", content: "Describe OTel in a single sentence." }],
      max_tokens: 20,
    });

    console.log("Response:", response.choices[0]?.message?.content);
  }

  (async () => {
    await main();
    await new Promise(resolve => setTimeout(resolve, 2000));
    await provider.shutdown();
  })();
  ```
</CodeGroup>

`OpenAIInstrumentor`는 OpenAI Call을 래핑하고 트레이스를 생성한 뒤 collector로 내보냅니다. collector는 인증과 Weave로의 라우팅을 처리합니다.

스크립트를 실행한 후에는 Weave UI에서 [트레이스를 확인할 수 있습니다](/ko/weave/guides/tracking/trace-tree).

트레이스를 추가 백엔드로 전송하려면 exporter를 더 추가하고 `service.pipelines.traces.exporters` 목록에 포함하세요. 예를 들어 동일한 Collector 인스턴스에서 Weave와 Jaeger 둘 다로 내보낼 수 있습니다.

<div id="organize-otel-traces-into-threads">
  ## OTel 트레이스를 스레드로 정리하기
</div>

[Weave 스레드](/ko/weave/guides/tracking/threads)를 사용하면 관련 트레이스를 그룹화하여 멀티턴 대화나 사용자 세션을 단일 단위로 분석할 수 있습니다. 특정 span 속성을 추가해 OpenTelemetry 트레이스를 스레드로 정리한 다음, Weave의 Thread UI를 사용해 멀티턴 대화나 사용자 세션과 같은 관련 오퍼레이션을 분석할 수 있습니다.

스레드 그룹화를 사용하려면 OTel span에 다음 속성을 추가하세요:

* `wandb.thread_id`: span을 특정 스레드로 그룹화합니다.
* `wandb.is_turn`: span을 대화 턴으로 표시합니다(스레드 view에서 행으로 표시됨).

다음 예제는 OTel 트레이스를 Weave 스레드로 정리하는 방법을 보여줍니다. `wandb.thread_id`를 사용해 관련 오퍼레이션을 그룹화하고, `wandb.is_turn`을 사용해 스레드 view에서 행으로 표시되는 상위 수준 오퍼레이션을 표시합니다.

<Accordion title="초기 설정">
  이 예제를 실행하려면 다음 설정을 사용하세요:

  <Tabs>
    <Tab title="Python">
      ```python lines theme={null}
      import json
      import os
      from opentelemetry import trace
      from opentelemetry.sdk import trace as trace_sdk
      from opentelemetry.sdk.resources import Resource
      from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
      from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor

      # 설정
      ENTITY = "<your-team-name>"
      PROJECT = "<your-project-name>"
      WANDB_API_KEY = os.environ["WANDB_API_KEY"]

      OTEL_EXPORTER_OTLP_ENDPOINT = "https://trace.wandb.ai/otel/v1/traces"

      exporter = OTLPSpanExporter(
          endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
          headers={"wandb-api-key": WANDB_API_KEY},
      )

      tracer_provider = trace_sdk.TracerProvider(resource=Resource({
          "wandb.entity": ENTITY,
          "wandb.project": PROJECT,
      }))
      tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

      # 선택적으로 span을 콘솔에 출력합니다
      tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

      trace.set_tracer_provider(tracer_provider)

      # 전역 tracer provider에서 tracer를 생성합니다
      tracer = trace.get_tracer(__name__)
      ```
    </Tab>

    <Tab title="TypeScript">
      ```typescript lines theme={null}
      import { trace, context } from "@opentelemetry/api";
      import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
      import {
        BatchSpanProcessor,
        ConsoleSpanExporter,
      } from "@opentelemetry/sdk-trace-base";
      import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
      import { Resource } from "@opentelemetry/resources";

      // 설정
      const ENTITY = "<your-team-name>";
      const PROJECT = "<your-project-name>";
      const WANDB_API_KEY = process.env.WANDB_API_KEY;

      if (!WANDB_API_KEY) {
        console.error("Error: WANDB_API_KEY environment variable is not set");
        console.error("Run: export WANDB_API_KEY=your_api_key_here");
        process.exit(1);
      }

      // OTel 설정
      const OTEL_EXPORTER_OTLP_ENDPOINT = "https://trace.wandb.ai/otel/v1/traces";

      const exporter = new OTLPTraceExporter({
        url: OTEL_EXPORTER_OTLP_ENDPOINT,
        headers: { "wandb-api-key": WANDB_API_KEY },
      });

      // span processor로 tracer provider를 초기화합니다
      const provider = new NodeTracerProvider({
        resource: new Resource({
          "wandb.entity": ENTITY,
          "wandb.project": PROJECT,
        }),
        spanProcessors: [
          new BatchSpanProcessor(exporter),
          new BatchSpanProcessor(new ConsoleSpanExporter()),
        ],
      });

      // tracer provider를 등록합니다
      provider.register();

      // 전역 tracer provider에서 tracer를 생성합니다
      const tracer = trace.getTracer("threads-examples");
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="기본 단일 턴 스레드 트레이스하기">
  <Tabs>
    <Tab title="Python">
      ```python lines theme={null}
      def example_1_basic_thread_and_turn():
          """예제 1: 단일 턴이 있는 기본 스레드"""
          print("\n=== Example 1: Basic Thread and Turn ===")

          # 스레드 컨텍스트 생성
          thread_id = "thread_example_1"

          # 이 span은 턴을 나타냅니다(스레드의 직접 자식)
          with tracer.start_as_current_span("process_user_message") as turn_span:
              # 스레드 속성 설정
              turn_span.set_attribute("wandb.thread_id", thread_id)
              turn_span.set_attribute("wandb.is_turn", True)

              # 예시 속성 몇 가지 추가
              turn_span.set_attribute("input.value", "Hello, help me with setup")

              # 중첩된 span을 사용해 일부 작업 시뮬레이션
              with tracer.start_as_current_span("generate_response") as nested_span:
                  # 이는 턴 내부의 중첩 Call이므로 is_turn은 false이거나 설정되지 않아야 합니다
                  nested_span.set_attribute("wandb.thread_id", thread_id)
                  # 중첩 Call의 경우 wandb.is_turn은 설정하지 않거나 False로 설정합니다

                  response = "I'll help you get started with the setup process."
                  nested_span.set_attribute("output.value", response)

              turn_span.set_attribute("output.value", response)
              print(f"Turn completed in thread: {thread_id}")

      def main():
          example_1_basic_thread_and_turn()

      if __name__ == "__main__":
          main()
      ```
    </Tab>

    <Tab title="TypeScript">
      ```typescript twoslash lines theme={null}
      // @noErrors
      function example_1_basic_thread_and_turn() {
        console.log("\n=== Example 1: Basic Thread and Turn ===");

        // 스레드 컨텍스트 생성
        const threadId = "thread_example_1";

        // 이 span은 턴을 나타냅니다(스레드의 직접 자식)
        tracer.startActiveSpan("process_user_message", (turnSpan) => {
          // 스레드 속성 설정
          turnSpan.setAttribute("wandb.thread_id", threadId);
          turnSpan.setAttribute("wandb.is_turn", true);

          // 예시 속성 몇 가지 추가
          turnSpan.setAttribute("input.value", "Hello, help me with setup");

          let response: string;
          
          // 중첩된 span을 사용해 일부 작업 시뮬레이션
          tracer.startActiveSpan("generate_response", (nestedSpan) => {
            // 이는 턴 내부의 중첩 Call이므로 is_turn은 false이거나 설정되지 않아야 합니다
            nestedSpan.setAttribute("wandb.thread_id", threadId);
            // 중첩 Call의 경우 wandb.is_turn은 설정하지 않거나 false로 설정합니다

            response = "I'll help you get started with the setup process.";
            nestedSpan.setAttribute("output.value", response);
            nestedSpan.end();
          });
          
          turnSpan.setAttribute("output.value", response!);
          console.log(`Turn completed in thread: ${threadId}`);
          turnSpan.end();
        });
      }

      function main() {
        example_1_basic_thread_and_turn();
      }

      main();
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="동일한 스레드 ID를 공유하는 멀티턴 대화 트레이스하기">
  <Tabs>
    <Tab title="Python">
      ```python lines theme={null}
      def example_2_multiple_turns():
          """Example 2: Multiple turns in a single thread"""
          print("\n=== Example 2: Multiple Turns in Thread ===")

          thread_id = "thread_conversation_123"

          # 턴 1
          with tracer.start_as_current_span("process_message_turn1") as turn1_span:
              turn1_span.set_attribute("wandb.thread_id", thread_id)
              turn1_span.set_attribute("wandb.is_turn", True)
              turn1_span.set_attribute("input.value", "What programming languages do you recommend?")

              # 중첩된 오퍼레이션
              with tracer.start_as_current_span("analyze_query") as analyze_span:
                  analyze_span.set_attribute("wandb.thread_id", thread_id)
                  # 중첩 span의 경우 is_turn 속성을 지정하지 않거나 False로 설정

              response1 = "I recommend Python for beginners and JavaScript for web development."
              turn1_span.set_attribute("output.value", response1)
              print(f"Turn 1 completed in thread: {thread_id}")

          # 턴 2
          with tracer.start_as_current_span("process_message_turn2") as turn2_span:
              turn2_span.set_attribute("wandb.thread_id", thread_id)
              turn2_span.set_attribute("wandb.is_turn", True)
              turn2_span.set_attribute("input.value", "Can you explain Python vs JavaScript?")

              # 중첩된 오퍼레이션
              with tracer.start_as_current_span("comparison_analysis") as compare_span:
                  compare_span.set_attribute("wandb.thread_id", thread_id)
                  compare_span.set_attribute("wandb.is_turn", False)  # 중첩 span의 경우 명시적으로 false로 설정

              response2 = "Python excels at data science while JavaScript dominates web development."
              turn2_span.set_attribute("output.value", response2)
              print(f"Turn 2 completed in thread: {thread_id}")

      def main():
          example_2_multiple_turns()

      if __name__ == "__main__":
          main()
      ```
    </Tab>

    <Tab title="TypeScript">
      ```typescript twoslash lines theme={null}
      // @noErrors
      function example_2_multiple_turns() {
        console.log("\n=== Example 2: Multiple Turns in Thread ===");

        const threadId = "thread_conversation_123";

        // 턴 1
        tracer.startActiveSpan("process_message_turn1", (turn1Span) => {
          turn1Span.setAttribute("wandb.thread_id", threadId);
          turn1Span.setAttribute("wandb.is_turn", true);
          turn1Span.setAttribute(
            "input.value",
            "What programming languages do you recommend?"
          );

          // 중첩된 오퍼레이션
          tracer.startActiveSpan("analyze_query", (analyzeSpan) => {
            analyzeSpan.setAttribute("wandb.thread_id", threadId);
            // 중첩 span의 경우 is_turn 속성을 지정하지 않거나 false로 설정
            analyzeSpan.end();
          });

          const response1 =
            "I recommend Python for beginners and JavaScript for web development.";
          turn1Span.setAttribute("output.value", response1);
          console.log(`Turn 1 completed in thread: ${threadId}`);
          turn1Span.end();
        });

        // 턴 2
        tracer.startActiveSpan("process_message_turn2", (turn2Span) => {
          turn2Span.setAttribute("wandb.thread_id", threadId);
          turn2Span.setAttribute("wandb.is_turn", true);
          turn2Span.setAttribute("input.value", "Can you explain Python vs JavaScript?");

          // 중첩된 오퍼레이션
          tracer.startActiveSpan("comparison_analysis", (compareSpan) => {
            compareSpan.setAttribute("wandb.thread_id", threadId);
            compareSpan.setAttribute("wandb.is_turn", false); // 중첩 span의 경우 명시적으로 false로 설정
            compareSpan.end();
          });

          const response2 =
            "Python excels at data science while JavaScript dominates web development.";
          turn2Span.setAttribute("output.value", response2);
          console.log(`Turn 2 completed in thread: ${threadId}`);
          turn2Span.end();
        });
      }

      function main() {
        example_2_multiple_turns();
      }

      main();
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="여러 단계로 깊게 중첩된 오퍼레이션을 트레이스하고 최외곽 스팬만 턴으로 표시">
  <Tabs>
    <Tab title="Python">
      ```python lines theme={null}
      def example_3_complex_nested_structure():
          """Example 3: Complex nested structure with multiple levels"""
          print("\n=== Example 3: Complex Nested Structure ===")

          thread_id = "thread_complex_456"

          # 여러 단계로 중첩된 턴
          with tracer.start_as_current_span("handle_complex_request") as turn_span:
              turn_span.set_attribute("wandb.thread_id", thread_id)
              turn_span.set_attribute("wandb.is_turn", True)
              turn_span.set_attribute("input.value", "Analyze this code and suggest improvements")

              # 레벨 1 중첩 오퍼레이션
              with tracer.start_as_current_span("code_analysis") as analysis_span:
                  analysis_span.set_attribute("wandb.thread_id", thread_id)
                  # 중첩 오퍼레이션에는 is_turn을 설정하지 않음

                  # 레벨 2 중첩 오퍼레이션
                  with tracer.start_as_current_span("syntax_check") as syntax_span:
                      syntax_span.set_attribute("wandb.thread_id", thread_id)
                      syntax_span.set_attribute("result", "No syntax errors found")

                  # 또 다른 레벨 2 중첩 오퍼레이션
                  with tracer.start_as_current_span("performance_check") as perf_span:
                      perf_span.set_attribute("wandb.thread_id", thread_id)
                      perf_span.set_attribute("result", "Found 2 optimization opportunities")

              # 또 다른 레벨 1 중첩 오퍼레이션
              with tracer.start_as_current_span("generate_suggestions") as suggest_span:
                  suggest_span.set_attribute("wandb.thread_id", thread_id)
                  suggestions = ["Use list comprehension", "Consider caching results"]
                  suggest_span.set_attribute("suggestions", json.dumps(suggestions))

              turn_span.set_attribute("output.value", "Analysis complete with 2 improvement suggestions")
              print(f"Complex turn completed in thread: {thread_id}")

      def main():
          example_3_complex_nested_structure()

      if __name__ == "__main__":
          main()
      ```
    </Tab>

    <Tab title="TypeScript">
      ```typescript twoslash lines theme={null}
      // @noErrors
      function example_3_complex_nested_structure() {
        console.log("\n=== Example 3: Complex Nested Structure ===");

        const threadId = "thread_complex_456";

        // 여러 단계로 중첩된 턴
        tracer.startActiveSpan("handle_complex_request", (turnSpan) => {
          turnSpan.setAttribute("wandb.thread_id", threadId);
          turnSpan.setAttribute("wandb.is_turn", true);
          turnSpan.setAttribute(
            "input.value",
            "Analyze this code and suggest improvements"
          );

          // 레벨 1 중첩 오퍼레이션
          tracer.startActiveSpan("code_analysis", (analysisSpan) => {
            analysisSpan.setAttribute("wandb.thread_id", threadId);
            // 중첩 오퍼레이션에는 is_turn을 설정하지 않음

            // 레벨 2 중첩 오퍼레이션
            tracer.startActiveSpan("syntax_check", (syntaxSpan) => {
              syntaxSpan.setAttribute("wandb.thread_id", threadId);
              syntaxSpan.setAttribute("result", "No syntax errors found");
              syntaxSpan.end();
            });

            // 또 다른 레벨 2 중첩 오퍼레이션
            tracer.startActiveSpan("performance_check", (perfSpan) => {
              perfSpan.setAttribute("wandb.thread_id", threadId);
              perfSpan.setAttribute("result", "Found 2 optimization opportunities");
              perfSpan.end();
            });

            analysisSpan.end();
          });

          // 또 다른 레벨 1 중첩 오퍼레이션
          tracer.startActiveSpan("generate_suggestions", (suggestSpan) => {
            suggestSpan.setAttribute("wandb.thread_id", threadId);
            const suggestions = ["Use list comprehension", "Consider caching results"];
            suggestSpan.setAttribute("suggestions", JSON.stringify(suggestions));
            suggestSpan.end();
          });

          turnSpan.setAttribute(
            "output.value",
            "Analysis complete with 2 improvement suggestions"
          );
          console.log(`Complex turn completed in thread: ${threadId}`);
          turnSpan.end();
        });
      }

      function main() {
        example_3_complex_nested_structure();
      }

      main();
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="스레드에 속하지만 턴은 아닌 백그라운드 오퍼레이션 트레이스">
  <Tabs>
    <Tab title="Python">
      ```python lines theme={null}
      def example_4_non_turn_operations():
          """Example 4: Operations that are part of a thread but not turns"""
          print("\n=== Example 4: Non-Turn Thread Operations ===")

          thread_id = "thread_background_789"

          # 스레드에 속하지만 턴은 아닌 백그라운드 오퍼레이션
          with tracer.start_as_current_span("background_indexing") as bg_span:
              bg_span.set_attribute("wandb.thread_id", thread_id)
              # wandb.is_turn이 설정되지 않았거나 false인 경우 - 이는 턴이 아닙니다
              bg_span.set_attribute("wandb.is_turn", False)
              bg_span.set_attribute("operation", "Indexing conversation history")
              print(f"Background operation in thread: {thread_id}")

          # 같은 스레드의 실제 턴
          with tracer.start_as_current_span("user_query") as turn_span:
              turn_span.set_attribute("wandb.thread_id", thread_id)
              turn_span.set_attribute("wandb.is_turn", True)
              turn_span.set_attribute("input.value", "Search my previous conversations")
              turn_span.set_attribute("output.value", "Found 5 relevant conversations")
              print(f"Turn completed in thread: {thread_id}")

      def main():
          example_4_non_turn_operations()

      if __name__ == "__main__":
          main()
      ```
    </Tab>

    <Tab title="TypeScript">
      ```typescript twoslash lines theme={null}
      // @noErrors
      function example_4_non_turn_operations() {
        console.log("\n=== Example 4: Non-Turn Thread Operations ===");

        const threadId = "thread_background_789";

        // 스레드에 속하지만 턴은 아닌 백그라운드 오퍼레이션
        tracer.startActiveSpan("background_indexing", (bgSpan) => {
          bgSpan.setAttribute("wandb.thread_id", threadId);
          // wandb.is_turn이 설정되지 않았거나 false인 경우 - 이는 턴이 아닙니다
          bgSpan.setAttribute("wandb.is_turn", false);
          bgSpan.setAttribute("operation", "Indexing conversation history");
          console.log(`Background operation in thread: ${threadId}`);
          bgSpan.end();
        });

        // 같은 스레드의 실제 턴
        tracer.startActiveSpan("user_query", (turnSpan) => {
          turnSpan.setAttribute("wandb.thread_id", threadId);
          turnSpan.setAttribute("wandb.is_turn", true);
          turnSpan.setAttribute("input.value", "Search my previous conversations");
          turnSpan.setAttribute("output.value", "Found 5 relevant conversations");
          console.log(`Turn completed in thread: ${threadId}`);
          turnSpan.end();
        });
      }

      function main() {
        example_4_non_turn_operations();
      }

      main();
      ```
    </Tab>
  </Tabs>
</Accordion>

이러한 트레이스를 전송한 후에는 Weave UI의 **Threads** 탭에서 확인할 수 있습니다. 여기서 트레이스는 `thread_id`별로 그룹화되며, 각 턴은 별도의 행으로 표시됩니다。

<div id="attribute-mappings">
  ## 속성 매핑
</div>

Weave는 다양한 계측 프레임워크의 OpenTelemetry 스팬 속성을 내부 데이터 모델에 매핑합니다. 이 매핑 덕분에 Weave에서 풍부한 뷰를 얻기 위해 기존 계측의 속성 이름을 바꾸거나 변환할 필요가 없습니다. 여러 속성 이름이 동일한 필드에 매핑될 경우, Weave는 이를 우선순위에 따라 적용하므로 동일한 트레이스 내에서 여러 프레임워크를 함께 사용할 수 있습니다.

<div id="supported-frameworks">
  ### 지원되는 프레임워크
</div>

Weave는 다음 관측성 프레임워크 및 SDK의 속성 규약을 지원합니다:

* **OpenTelemetry GenAI**: 생성형 AI용 표준 시맨틱 규약 (`gen_ai.*`).
* **OpenInference**: Arize AI의 계측 라이브러리 (`input.value`, `output.value`, `llm.*`, `openinference.*`).
* **Vercel AI SDK**: Vercel의 AI SDK 속성 (`ai.prompt`, `ai.response`, `ai.model.*`, `ai.usage.*`).
* **MLflow**: MLflow tracking 속성 (`mlflow.spanInputs`, `mlflow.spanOutputs`).
* **Traceloop**: OpenLLMetry 계측 속성 (`traceloop.entity.*`, `traceloop.span.kind`).
* **Google Vertex AI**: Vertex AI agent 속성 (`gcp.vertex.agent.*`).
* **OpenLit**: OpenLit 관측성 속성 (`gen_ai.content.completion`).
* **Langfuse**: Langfuse 트레이싱 속성 (`langfuse.startTime`, `langfuse.endTime`).

<div id="attribute-reference">
  ### 속성 레퍼런스
</div>

| 속성 필드명                            | W\&B 매핑                       | 설명                       | 유형                      | 예시                                             |
| :-------------------------------- | :---------------------------- | :----------------------- | :---------------------- | :--------------------------------------------- |
| `ai.prompt`                       | `inputs`                      | 사용자 프롬프트 텍스트 또는 메시지.     | 문자열, 목록, dict           | `"여름에 관한 짧은 하이쿠를 써줘."`                         |
| `gen_ai.prompt`                   | `inputs`                      | AI 모델 프롬프트 또는 메시지 배열입니다. | 목록, dict, 문자열           | `[{"role":"user","content":"abc"}]`            |
| `input.value`                     | `inputs`                      | 모델 호출을 위한 입력 값입니다.       | 문자열, 목록, dict           | `{"text":"농담 하나 해줘"}`                          |
| `mlflow.spanInputs`               | `inputs`                      | Span 입력 데이터입니다.          | 문자열, 목록, dict           | `["프롬프트 텍스트"]`                                 |
| `traceloop.entity.input`          | `inputs`                      | entity 입력 데이터.           | 문자열, 목록, dict           | `"이것을 프랑스어로 번역하세요"`                            |
| `gcp.vertex.agent.tool_call_args` | `inputs`                      | 도구 call 인수.              | Dict                    | `{"args":{"query":"weather in SF"}}`           |
| `gcp.vertex.agent.llm_request`    | `inputs`                      | LLM 요청 페이로드.             | Dict                    | `{"contents":[{"role":"user","parts":[...]}]}` |
| `input`                           | `inputs`                      | 범용 입력값.                  | 문자열, 목록, dict           | `"이 텍스트를 요약해 줘"`                               |
| `inputs`                          | `inputs`                      | 범용 입력 배열.                | 목록, dict, 문자열           | `["이 텍스트를 요약해 줘"]`                             |
| `ai.response`                     | `outputs`                     | 모델 응답 텍스트 또는 데이터.        | 문자열, 목록, dict           | `"하이쿠를 하나 들려드릴게요..."`                          |
| `gen_ai.completion`               | `outputs`                     | AI completion 결과.        | 문자열, 목록, dict           | `"생성된 텍스트"`                                    |
| `output.value`                    | `outputs`                     | 모델의 출력값.                 | 문자열, 목록, dict           | `{"text":"답변 텍스트"}`                            |
| `mlflow.spanOutputs`              | `outputs`                     | 스팬 출력 데이터.               | String, 목록, dict        | `["answer"]`                                   |
| `gen_ai.content.completion`       | `outputs`                     | 콘텐츠 완성 결과.               | String                  | `"답변 텍스트"`                                     |
| `traceloop.entity.output`         | `outputs`                     | entity 출력 데이터.           | String, 목록, dict        | `"답변 텍스트"`                                     |
| `gcp.vertex.agent.tool_response`  | `outputs`                     | 도구 실행 응답.                | 딕셔너리, 문자열               | `{"toolResponse":"ok"}`                        |
| `gcp.vertex.agent.llm_response`   | `outputs`                     | LLM 응답 페이로드.             | 딕셔너리, 문자열               | `{"candidates":[...]}`                         |
| `output`                          | `outputs`                     | 일반 출력 값.                 | 문자열, 목록, 딕셔너리           | `"답변 텍스트"`                                     |
| `outputs`                         | `outputs`                     | 일반 출력 배열.                | 목록, dict, 문자열           | `["답변 텍스트"]`                                   |
| `gen_ai.usage.input_tokens`       | `usage.input_tokens`          | 사용된 입력 토큰 수.             | Int                     | `42`                                           |
| `gen_ai.usage.prompt_tokens`      | `usage.prompt_tokens`         | 사용된 프롬프트 토큰 수.           | Int                     | `30`                                           |
| `llm.token_count.prompt`          | `usage.prompt_tokens`         | 프롬프트 토큰 수.               | Int                     | `30`                                           |
| `ai.usage.promptTokens`           | `usage.prompt_tokens`         | 사용된 프롬프트 토큰 수.           | Int                     | `30`                                           |
| `gen_ai.usage.completion_tokens`  | `usage.completion_tokens`     | 생성된 완료 토큰 수.             | Int                     | `40`                                           |
| `llm.token_count.completion`      | `usage.completion_tokens`     | 완료 토큰 수.                 | Int                     | `40`                                           |
| `ai.usage.completionTokens`       | `usage.completion_tokens`     | 생성된 completion token 수.  | Int                     | `40`                                           |
| `llm.usage.total_tokens`          | `usage.total_tokens`          | Request에 사용된 총 token 수.  | Int                     | `70`                                           |
| `llm.token_count.total`           | `usage.total_tokens`          | 총 token 수.               | 정수                      | `70`                                           |
| `gen_ai.system`                   | `attributes.system`           | 시스템 프롬프트 또는 지침.          | 문자열                     | `"당신은 유용한 도우미입니다."`                            |
| `llm.system`                      | `attributes.system`           | 시스템 프롬프트 또는 지침.          | 문자열                     | `"당신은 도움이 되는 어시스턴트입니다."`                       |
| `weave.span.kind`                 | `attributes.kind`             | 스팬 유형 또는 카테고리.           | 문자열                     | `"llm"`                                        |
| `traceloop.span.kind`             | `attributes.kind`             | Span 유형 또는 범주.           | 문자열                     | `"llm"`                                        |
| `openinference.span.kind`         | `attributes.kind`             | Span 유형 또는 범주.           | 문자열                     | `"llm"`                                        |
| `gen_ai.response.model`           | `attributes.model`            | 모델 식별자.                  | 문자열                     | `"gpt-4o"`                                     |
| `llm.model_name`                  | `attributes.model`            | 모델 식별자.                  | 문자열                     | `"gpt-4o-mini"`                                |
| `ai.model.id`                     | `attributes.model`            | 모델 식별자.                  | 문자열                     | `"gpt-4o"`                                     |
| `llm.provider`                    | `attributes.provider`         | 모델 제공업체 이름.              | 문자열                     | `"openai"`                                     |
| `ai.model.provider`               | `attributes.provider`         | 모델 제공업체 이름.              | String                  | `"openai"`                                     |
| `gen_ai.request`                  | `attributes.model_parameters` | 모델 생성 파라미터.              | Dict                    | `{"temperature":0.7,"max_tokens":256}`         |
| `llm.invocation_parameters`       | `attributes.model_parameters` | 모델 호출 파라미터.              | Dict                    | `{"temperature":0.2}`                          |
| `wandb.display_name`              | `display_name`                | UI에 표시할 맞춤형 표시 이름.       | 문자열                     | `"사용자 메시지"`                                    |
| `gcp.vertex.agent.session_id`     | `thread_id`                   | 세션 또는 스레드 식별자입니다.        | 문자열                     | `"thread_123"`                                 |
| `wandb.thread_id`                 | `thread_id`                   | 대화의 스레드 식별자입니다.          | 문자열                     | `"thread_123"`                                 |
| `wb_run_id`                       | `wb_run_id`                   | 연관된 W\&B run 식별자입니다.     | 문자열                     | `"abc123"`                                     |
| `wandb.wb_run_id`                 | `wb_run_id`                   | 연결된 W\&B run 식별자입니다.     | 문자열                     | `"abc123"`                                     |
| `gcp.vertex.agent.session_id`     | `is_turn`                     | span을 대화 턴으로 표시합니다.      | 불리언                     | `true`                                         |
| `wandb.is_turn`                   | `is_turn`                     | span을 대화 턴으로 표시합니다.      | 불리언                     | `true`                                         |
| `langfuse.startTime`              | `start_time` (재정의)            | span 시작 타임스탬프를 재정의합니다.   | 타임스탬프 (ISO8601/unix ns) | `"2024-01-01T12:00:00Z"`                       |
| `langfuse.endTime`                | `end_time` (재정의)              | span 종료 타임스탬프를 재정의합니다.   | 타임스탬프 (ISO8601/unix ns) | `"2024-01-01T12:00:01Z"`                       |

<div id="limitations">
  ## 제한 사항
</div>

Weave UI는 Chat 뷰에서 OTel 트레이스 도구 call을 렌더링하는 기능을 지원하지 않습니다. 대신 원시 JSON으로 표시됩니다.