OpenTelemetry 지원

이 페이지에서는 AI 에이전트의 트레이싱(tracing) 및 모니터링을 위해 Koog 에이전틱 프레임워크(agentic framework)에서 제공하는 OpenTelemetry 지원에 대한 자세한 내용을 설명합니다.

개요

OpenTelemetry는 애플리케이션에서 텔레메트리 데이터(트레이스)를 생성, 수집 및 내보내기 위한 도구를 제공하는 관측성(observability) 프레임워크입니다. Koog의 OpenTelemetry 기능을 사용하면 AI 에이전트를 계측(instrument)하여 다음과 같은 작업에 도움이 되는 텔레메트리 데이터를 수집할 수 있습니다.

에이전트 성능 및 동작 모니터링
복잡한 에이전트 워크플로의 문제 디버깅
에이전트 실행 흐름 시각화
LLM 호출 및 도구 사용 추적
에이전트 동작 패턴 분석

주요 OpenTelemetry 개념

스팬(Spans): 스팬은 분산 트레이스 내의 개별 작업 단위 또는 연산을 나타냅니다. 에이전트 실행, 함수 호출, LLM 호출 또는 도구 호출과 같이 애플리케이션 내 특정 활동의 시작과 끝을 나타냅니다.
속성(Attributes): 속성은 스팬과 같은 텔레메트리 관련 항목에 대한 메타데이터를 제공합니다. 속성은 키-값(key-value) 쌍으로 표현됩니다.
이벤트(Events): 이벤트는 스팬의 수명 주기 동안 발생한 잠재적으로 주목할 만한 특정 시점(스팬 관련 이벤트)을 나타냅니다.
익스포터(Exporters): 익스포터는 수집된 텔레메트리 데이터를 다양한 백엔드 또는 목적지로 전송하는 역할을 하는 구성 요소입니다.
컬렉터(Collectors): 컬렉터는 텔레메트리 데이터를 수신, 처리 및 내보냅니다. 애플리케이션과 관측성 백엔드 사이의 중개자 역할을 합니다.
샘플러(Samplers): 샘플러는 샘플링 전략에 따라 트레이스를 기록할지 여부를 결정합니다. 텔레메트리 데이터의 양을 관리하는 데 사용됩니다.
리소스(Resources): 리소스는 텔레메트리 데이터를 생성하는 엔티티를 나타냅니다. 리소스에 대한 정보를 제공하는 키-값 쌍인 리소스 속성으로 식별됩니다.

Koog의 OpenTelemetry 기능은 다음과 같은 다양한 에이전트 이벤트에 대해 스팬을 자동으로 생성합니다.

에이전트 실행 시작 및 종료
노드(Node) 실행
LLM 호출
도구(Tool) 호출

설치

Koog에서 OpenTelemetry를 사용하려면 에이전트에 OpenTelemetry 기능을 추가하세요.

kotlin

val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = "You are a helpful assistant.",
    installFeatures = {
        install(OpenTelemetry) {
            // 여기에 설정 옵션 작성
        }
    }
)

설정

기본 설정

에이전트에서 OpenTelemetry 기능을 설정할 때 사용할 수 있는 모든 속성 목록은 다음과 같습니다.

이름	데이터 타입	기본값	설명
`serviceName`	`String`	`ai.koog`	계측되는 서비스의 이름입니다.
`serviceVersion`	`String`	현재 Koog 라이브러리 버전	계측되는 서비스의 버전입니다.
`isVerbose`	`Boolean`	`false`	OpenTelemetry 설정 디버깅을 위해 상세 로깅을 활성화할지 여부입니다.
`sdk`	`OpenTelemetrySdk`		텔레메트리 수집에 사용할 OpenTelemetry SDK 인스턴스입니다.
`tracer`	`Tracer`		스팬 생성에 사용되는 OpenTelemetry 트레이서(tracer) 인스턴스입니다.

NOTE

sdk와 tracer 속성은 액세스할 수 있는 공개(public) 속성이지만, 아래에 나열된 공개 메서드를 통해서만 설정할 수 있습니다.

OpenTelemetryConfig 클래스에는 다양한 설정 항목과 관련된 동작을 나타내는 메서드도 포함되어 있습니다. 다음은 기본적인 설정 항목 세트로 OpenTelemetry 기능을 설치하는 예시입니다.

kotlin

install(OpenTelemetry) {
    // 서비스 정보 설정
    setServiceInfo("my-agent-service", "1.0.0")
    
    // Logging 익스포터 추가
    addSpanExporter(LoggingSpanExporter.create())
}

사용 가능한 메서드에 대한 참고 사항은 아래 섹션을 확인하세요.

setServiceInfo

이름과 버전을 포함한 서비스 정보를 설정합니다. 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`serviceName`	String	예		계측되는 서비스의 이름입니다.
`serviceVersion`	String	예		계측되는 서비스의 버전입니다.

addSpanExporter

텔레메트리 데이터를 외부 시스템으로 전송하기 위한 스팬 익스포터를 추가합니다. 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`exporter`	`SpanExporter`	예		커스텀 스팬 익스포터 목록에 추가할 `SpanExporter` 인스턴스입니다.

addSpanProcessor

스팬이 내보내지기 전에 처리하기 위한 스팬 프로세서 팩토리를 추가합니다. 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`processor`	`(SpanExporter) -> SpanProcessor`	예		지정된 익스포터에 대한 스팬 프로세서를 생성하는 함수입니다. 익스포터별로 처리를 커스텀할 수 있습니다.

addResourceAttributes

서비스에 대한 추가 컨텍스트를 제공하기 위해 리소스 속성을 추가합니다. 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`attributes`	`Map<AttributeKey<T>, T>`	예		서비스에 대한 추가 세부 정보를 제공하는 키-값 쌍입니다.

setSampler

수집할 스팬을 제어하기 위한 샘플링 전략을 설정합니다. 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`sampler`	`Sampler`	예		OpenTelemetry 설정에 적용할 샘플러 인스턴스입니다.

setVerbose

상세 로깅을 활성화하거나 비활성화합니다. 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`verbose`	`Boolean`	예	`false`	true인 경우 애플리케이션이 더 상세한 텔레메트리 데이터를 수집합니다.

NOTE

보안상의 이유로 OpenTelemetry 스팬의 일부 콘텐츠는 기본적으로 마스킹 처리됩니다. 예를 들어, LLM 메시지는 실제 메시지 내용 대신 HIDDEN:non-empty로 마스킹됩니다. 실제 내용을 확인하려면 verbose 인수의 값을 true로 설정하세요.

setSdk

사전에 설정된 OpenTelemetrySdk 인스턴스를 주입합니다.

setSdk(sdk)를 호출하면 제공된 SDK가 있는 그대로 사용되며, addSpanExporter, addSpanProcessor, addResourceAttributes 또는 setSampler를 통해 적용된 모든 커스텀 설정은 무시됩니다.
트레이서의 인스트루먼테이션 스코프 이름/버전은 서비스 정보와 일치하게 조정됩니다.

이름	데이터 타입	필수 여부	설명
`sdk`	`OpenTelemetrySdk`	예	에이전트에서 사용할 SDK 인스턴스입니다.

고급 설정

더 고급 설정을 위해 다음과 같은 설정 옵션을 커스텀할 수 있습니다.

샘플러(Sampler): 수집되는 데이터의 빈도와 양을 조절하기 위해 샘플링 전략을 설정합니다.
리소스 속성(Resource attributes): 텔레메트리 데이터를 생성하는 프로세스에 대한 정보를 추가합니다.

kotlin

install(OpenTelemetry) {
    // 서비스 정보 설정
    setServiceInfo("my-agent-service", "1.0.0")
    
    // Logging 익스포터 추가
    addSpanExporter(LoggingSpanExporter.create())
    
    // 샘플러 설정 
    setSampler(Sampler.traceIdRatioBased(0.5)) 

    // 리소스 속성 추가
    addResourceAttributes(mapOf(
        AttributeKey.stringKey("custom.attribute") to "custom-value")
    )
}

샘플러(Sampler)

샘플러를 정의하려면 사용하려는 샘플링 전략을 나타내는 opentelemetry-java SDK의 Sampler 클래스(io.opentelemetry.sdk.trace.samplers.Sampler) 메서드를 사용하세요.

기본 샘플링 전략은 다음과 같습니다.

Sampler.alwaysOn(): 모든 스팬(트레이스)이 샘플링되는 기본 샘플링 전략입니다.

사용 가능한 샘플러 및 샘플링 전략에 대한 자세한 내용은 OpenTelemetry Sampler 문서를 참조하세요.

리소스 속성(Resource attributes)

리소스 속성은 텔레메트리 데이터를 생성하는 프로세스에 대한 추가 정보를 나타냅니다. Koog에는 기본적으로 설정되는 리소스 속성 세트가 포함되어 있습니다.

service.name
service.version
service.instance.time
os.type
os.version
os.arch

service.name 속성의 기본값은 ai.koog이며, service.version 기본값은 현재 사용 중인 Koog 라이브러리 버전입니다.

기본 리소스 속성 외에도 커스텀 속성을 추가할 수 있습니다. Koog의 OpenTelemetry 설정에 커스텀 속성을 추가하려면 키와 값을 인수로 받는 addResourceAttributes() 메서드를 사용하세요.

kotlin

addResourceAttributes(mapOf(
    AttributeKey.stringKey("custom.attribute") to "custom-value")
)

스팬 유형 및 속성

OpenTelemetry 기능은 에이전트의 다양한 연산을 추적하기 위해 자동으로 다른 유형의 스팬을 생성합니다.

CreateAgentSpan: 에이전트를 실행할 때 생성되며, 에이전트가 종료되거나 프로세스가 종료될 때 닫힙니다.
InvokeAgentSpan: 에이전트의 호출을 나타냅니다.
StrategySpan: 에이전트 전략(최상위 실행 흐름)의 실행을 나타냅니다.
NodeExecuteSpan: 에이전트 전략 내 노드의 실행을 나타냅니다. 이는 Koog 전용 커스텀 스팬입니다.
SubgraphExecuteSpan: 에이전트 전략 내 서브그래프(subgraph)의 실행을 나타냅니다. 이는 Koog 전용 커스텀 스팬입니다.
InferenceSpan: LLM 호출을 나타냅니다.
ExecuteToolSpan: 도구 호출을 나타냅니다.
McpClientSpan: MCP(Model Context Protocol) 클라이언트 연산을 나타냅니다. 이 스팬은 MCP에 대한 OpenTelemetry 시맨틱 컨벤션을 따릅니다.

스팬은 중첩된 계층 구조로 구성됩니다. 다음은 스팬 구조의 예시입니다.

text

CreateAgentSpan
    InvokeAgentSpan
        StrategySpan
            NodeExecuteSpan
                InferenceSpan
            NodeExecuteSpan
                ExecuteToolSpan
            SubgraphExecuteSpan
                NodeExecuteSpan
                    InferenceSpan

스팬 속성

스팬 속성은 스팬과 관련된 메타데이터를 제공합니다. 각 스팬은 자체 속성 세트를 가지며, 일부 스팬은 속성을 반복해서 가질 수 있습니다.

Koog는 OpenTelemetry의 생성형 AI 이벤트를 위한 시맨틱 컨벤션(Semantic conventions for generative AI events)을 따르는 사전 정의된 속성 목록을 지원합니다. 예를 들어, 이 컨벤션은 스팬에 대개 필수적인 gen_ai.conversation.id라는 속성을 정의합니다. Koog에서 이 속성의 값은 에이전트 실행에 대한 고유 식별자이며, agent.run() 메서드를 호출할 때 자동으로 설정됩니다.

또한 Koog에는 Koog 전용 커스텀 속성도 포함되어 있습니다. 이러한 속성 대부분은 koog. 접두사로 식별할 수 있습니다. 사용 가능한 커스텀 속성은 다음과 같습니다.

koog.strategy.name: 에이전트 전략의 이름입니다. 전략은 에이전트의 목적을 설명하는 Koog 관련 엔티티입니다. StrategySpan 스팬에서 사용됩니다.
koog.node.id: 실행 중인 노드의 식별자(이름)입니다. NodeExecuteSpan 스팬에서 사용됩니다.
koog.node.input: 실행 시작 시 노드에 전달된 입력입니다. 노드가 시작될 때 NodeExecuteSpan에 존재합니다.
koog.node.output: 완료 시 노드에서 생성된 출력입니다. 노드가 성공적으로 완료될 때 NodeExecuteSpan에 존재합니다.
koog.subgraph.id: 실행 중인 서브그래프의 식별자(이름)입니다. SubgraphExecuteSpan 스팬에서 사용됩니다.
koog.subgraph.input: 실행 시작 시 서브그래프에 전달된 입력입니다. 서브그래프가 시작될 때 SubgraphExecuteSpan에 존재합니다.
koog.subgraph.output: 완료 시 서브그래프에서 생성된 출력입니다. 서브그래프가 성공적으로 완료될 때 SubgraphExecuteSpan에 존재합니다.

이벤트

스팬에는 이벤트(event)가 연결될 수도 있습니다. 이벤트는 관련 있는 무언가가 발생한 특정 시점을 설명합니다. 예를 들어, LLM 호출이 시작되거나 종료된 시점 등이 해당됩니다. 이벤트에도 속성이 있으며, 추가적으로 이벤트 본문 필드(body fields)가 포함됩니다.

OpenTelemetry의 생성형 AI 이벤트를 위한 시맨틱 컨벤션에 따라 다음 이벤트 유형이 지원됩니다.

SystemMessageEvent: 모델에 전달된 시스템 지침입니다.
UserMessageEvent: 모델에 전달된 사용자 메시지입니다.
AssistantMessageEvent: 모델에 전달된 어시스턴트 메시지입니다.
ToolMessageEvent: 모델에 전달된 도구 또는 함수 호출의 응답입니다.
ChoiceEvent: 모델의 응답 메시지입니다.
ModerationResponseEvent: 모델 모더레이션(moderation) 결과 또는 신호입니다.

NOTE

opentelemetry-java SDK는 이벤트를 추가할 때 이벤트 본문 필드 파라미터를 지원하지 않습니다. 따라서 Koog의 OpenTelemetry 지원에서 이벤트 본문 필드는 키가 body이고 값 타입이 문자열인 별도의 속성으로 처리됩니다. 이 문자열에는 대개 JSON과 유사한 객체인 이벤트 본문 필드의 내용 또는 페이로드가 포함됩니다. 이벤트 본문 필드의 예시는 OpenTelemetry 문서를 참조하세요. opentelemetry-java의 이벤트 본문 필드 지원 현황은 관련 GitHub 이슈를 확인하세요.

익스포터(Exporters)

익스포터는 수집된 텔레메트리 데이터를 OpenTelemetry 컬렉터 또는 다른 유형의 목적지나 백엔드 구현으로 전송합니다. 익스포터를 추가하려면 OpenTelemetry 기능을 설치할 때 addSpanExporter() 메서드를 사용하세요. 이 메서드는 다음 인수를 받습니다.

이름	데이터 타입	필수 여부	기본값	설명
`exporter`	SpanExporter	예		커스텀 스팬 익스포터 목록에 추가할 SpanExporter 인스턴스입니다.

아래 섹션에서는 opentelemetry-java SDK에서 가장 흔히 사용되는 몇 가지 익스포터에 대한 정보를 제공합니다.

NOTE

커스텀 익스포터를 설정하지 않으면 Koog는 기본적으로 콘솔 LoggingSpanExporter를 사용합니다. 이는 로컬 개발 및 디버깅 중에 도움이 됩니다.

Logging 익스포터

트레이스 정보를 콘솔에 출력하는 로깅 익스포터입니다. LoggingSpanExporter (io.opentelemetry.exporter.logging.LoggingSpanExporter)는 opentelemetry-java SDK의 일부입니다.

이 유형의 내보내기는 개발 및 디버깅 목적으로 유용합니다.

kotlin

install(OpenTelemetry) {
    // logging 익스포터 추가
    addSpanExporter(LoggingSpanExporter.create())
    // 필요에 따라 더 많은 익스포터 추가
}

OpenTelemetry HTTP 익스포터

OpenTelemetry HTTP 익스포터(OtlpHttpSpanExporter)는 opentelemetry-java SDK(io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter)의 일부이며 HTTP를 통해 스팬 데이터를 백엔드로 전송합니다.

kotlin

install(OpenTelemetry) {
   // OpenTelemetry HTTP 익스포터 추가 
   addSpanExporter(
      OtlpHttpSpanExporter.builder()
         // 컬렉터가 내보낸 스팬 배치를 처리할 때까지 기다릴 최대 시간 설정 
         .setTimeout(30, TimeUnit.SECONDS)
         // 연결할 OpenTelemetry 엔드포인트 설정
         .setEndpoint("http://localhost:3000/api/public/otel/v1/traces")
         // 인증 헤더 추가
         .addHeader("Authorization", "Basic $AUTH_STRING")
         .build()
   )
}

OpenTelemetry gRPC 익스포터

OpenTelemetry gRPC 익스포터(OtlpGrpcSpanExporter)는 opentelemetry-java SDK(io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter)의 일부입니다. gRPC를 통해 텔레메트리 데이터를 백엔드로 내보내며 데이터를 수신할 백엔드, 컬렉터 또는 엔드포인트의 호스트와 포트를 정의할 수 있습니다. 기본 포트는 4317입니다.

kotlin

install(OpenTelemetry) {
   // OpenTelemetry gRPC 익스포터 추가 
   addSpanExporter(
      OtlpGrpcSpanExporter.builder()
          // 호스트 및 포트 설정
         .setEndpoint("http://localhost:4317")
         .build()
   )
}

Langfuse와 통합

Langfuse는 LLM/에이전트 워크로드에 대한 트레이스 시각화 및 분석을 제공합니다.

도우미 함수를 사용하여 OpenTelemetry 트레이스를 Langfuse로 직접 내보내도록 Koog를 설정할 수 있습니다.

kotlin

install(OpenTelemetry) {
    addLangfuseExporter(
        langfuseUrl = "https://cloud.langfuse.com",
        langfusePublicKey = "...",
        langfuseSecretKey = "..."
    )
}

Langfuse와의 통합에 대한 자세한 내용은 전체 문서를 읽어보세요.

W&B Weave와 통합

W&B Weave는 LLM/에이전트 워크로드에 대한 트레이스 시각화 및 분석을 제공합니다. W&B Weave와의 통합은 사전 정의된 익스포터를 통해 설정할 수 있습니다.

kotlin

install(OpenTelemetry) {
    addWeaveExporter(
        weaveOtelBaseUrl = "https://trace.wandb.ai",
        weaveEntity = "my-team",
        weaveProjectName = "my-project",
        weaveApiKey = "..."
    )
}

W&B Weave와의 통합에 대한 자세한 내용은 전체 문서를 읽어보세요.

Jaeger와 통합

Jaeger는 OpenTelemetry와 함께 작동하는 인기 있는 분산 트레이싱 시스템입니다. Koog 리포지토리의 examples 내에 있는 opentelemetry 디렉토리에는 Jaeger 및 Koog 에이전트와 함께 OpenTelemetry를 사용하는 예시가 포함되어 있습니다.

사전 요구 사항

Koog 및 Jaeger로 OpenTelemetry를 테스트하려면 제공된 docker-compose.yaml 파일을 사용하여 다음 명령어를 실행하여 Jaeger OpenTelemetry 올인원(all-in-one) 프로세스를 시작하세요.

bash

docker compose up -d

제공된 Docker Compose YAML 파일의 내용은 다음과 같습니다.

yaml

# docker-compose.yaml
services:
  jaeger-all-in-one:
    image: jaegertracing/all-in-one:1.39
    container_name: jaeger-all-in-one
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    ports:
      - "4317:4317"
      - "16686:16686"

Jaeger UI에 액세스하여 트레이스를 확인하려면 http://localhost:16686을 여세요.

예시

Jaeger에서 사용할 텔레메트리 데이터를 내보내기 위해 예시에서는 opentelemetry-java SDK의 LoggingSpanExporter (io.opentelemetry.exporter.logging.LoggingSpanExporter) 및 OtlpGrpcSpanExporter (io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter)를 사용합니다.

전체 코드 샘플은 다음과 같습니다.

kotlin

fun main() {
    runBlocking {
        val agent = AIAgent(
            promptExecutor = simpleOpenAIExecutor(openAIApiKey),
            llmModel = OpenAIModels.Chat.O4Mini,
            systemPrompt = "You are a code assistant. Provide concise code examples."
        ) {
            install(OpenTelemetry) {
                // 로컬 디버깅을 위해 콘솔 로거 추가
                addSpanExporter(LoggingSpanExporter.create())

                // OpenTelemetry 컬렉터로 트레이스 전송
                addSpanExporter(
                    OtlpGrpcSpanExporter.builder()
                        .setEndpoint("http://localhost:4317")
                        .build()
                )
            }
        }

        agent.use { agent ->
            println("OpenTelemetry 트레이싱과 함께 에이전트 실행 중...")

            val result = agent.run("Tell me a joke about programming")

            println("에이전트 실행 완료. 결과: '$result'." +
                    "
트레이스를 확인하려면 Jaeger UI(http://localhost:16686)를 방문하세요.")
        }
    }
}

문제 해결

일반적인 문제

Jaeger, Langfuse 또는 W&B Weave에 트레이스가 나타나지 않음
- 서비스가 실행 중이고 OpenTelemetry 포트(4317)에 액세스 가능한지 확인하세요.
- OpenTelemetry 익스포터가 올바른 엔드포인트로 설정되었는지 확인하세요.
- 에이전트 실행 후 트레이스가 내보내질 수 있도록 몇 초간 기다려야 합니다.
스팬이 누락되거나 트레이스가 불완전함
- 에이전트 실행이 성공적으로 완료되는지 확인하세요.
- 에이전트 실행 직후에 애플리케이션을 너무 빨리 종료하지 않았는지 확인하세요.
- 스팬을 내보낼 시간을 확보하기 위해 에이전트 실행 후에 지연 시간을 추가하세요.
스팬 수가 너무 많음
- sampler 속성을 설정하여 다른 샘플링 전략 사용을 고려해 보세요.
- 예를 들어, 트레이스의 10%만 샘플링하려면 Sampler.traceIdRatioBased(0.1)를 사용하세요.
스팬 어댑터가 서로를 덮어씀
- 현재 OpenTelemetry 에이전트 기능은 여러 스팬 어댑터를 적용하는 것을 지원하지 않습니다 KG-265.

MCP (Model Context Protocol) 텔레메트리 지원

Koog는 MCP를 위한 공식 OpenTelemetry 시맨틱 컨벤션을 따르는 MCP 연산에 대한 포괄적인 OpenTelemetry 계측을 제공합니다.

개요

MCP 텔레메트리 지원에는 다음이 포함됩니다.

도구 실행 스팬을 MCP 관련 속성으로 자동 보강(Automatic enrichment)
MCP 클라이언트 연산(tools/call)에 대한 클라이언트 측 계측
모든 필수, 조건부 필수 및 권장 속성을 포함한 전체 시맨틱 컨벤션 준수

MCP 속성

MCP 텔레메트리는 OpenTelemetry 시맨틱 컨벤션을 따르며 다음 속성 그룹을 포함합니다.

필수 속성:

mcp.method.name: MCP 메서드 이름 (예: "tools/call")

조건부 필수 속성:

gen_ai.tool.name: 연산에 도구가 포함된 경우
gen_ai.prompt.name: 연산에 프롬프트가 포함된 경우
jsonrpc.request.id: (알림이 아닌) 요청을 실행할 때
error.type: 연산이 실패할 때

권장 속성:

mcp.session.id: 세션 식별자
mcp.protocol.version: MCP 프로토콜 버전 (예: "2025-06-18")
network.transport: 전송 유형 (stdio의 경우 "pipe", HTTP의 경우 "tcp")
server.address 및 server.port: 클라이언트 연산용

스팬 명명 규칙

MCP 스팬은 {mcp.method.name} {target} 명명 규칙을 따릅니다.

여기서 {target}은 해당하는 경우 도구 이름 또는 프롬프트 이름입니다. 예:

"tools/call search" - "search"라는 이름의 도구 호출

모범 사례

세션 추적을 가능하게 하려면 영구적인 MCP 세션으로 작업할 때 항상 세션 ID를 설정하세요.
전체 요청 트레이싱을 위해 JSON-RPC 요청의 요청 ID를 전파하세요.
MCP 연산의 성능 병목 현상을 식별하기 위해 메트릭을 모니터링하세요.

예시: 텔레메트리가 포함된 전체 MCP 클라이언트

kotlin

// MCP 도구 레지스트리 생성
val toolRegistry = McpToolRegistryProvider.fromSseUrl("http://localhost:3000")

// OpenTelemetry가 활성화된 에이전트를 생성하고 도구 레지스트리 전달
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = "You are a helpful assistant.",
    toolRegistry = toolRegistry
) {
    install(OpenTelemetry) {
        setServiceInfo("mcp-agent-service", "1.0.0")
        addSpanExporter(LoggingSpanExporter.create())
    }
}

// 에이전트 실행 - MCP 도구 호출이 자동으로 계측됩니다.
agent.use {
    it.run("Use the search tool to find information")
}

이 설정은 OpenTelemetry 모범 사례 및 시맨틱 컨벤션을 따르면서 최소한의 코드 변경으로 MCP 연산에 대한 완전한 관측성을 제공합니다.

OpenTelemetry 지원 ​

개요 ​

주요 OpenTelemetry 개념 ​

설치 ​

설정 ​

기본 설정 ​

setServiceInfo ​

addSpanExporter ​

addSpanProcessor ​

addResourceAttributes ​

setSampler ​

setVerbose ​

setSdk ​

고급 설정 ​

샘플러(Sampler) ​

리소스 속성(Resource attributes) ​

스팬 유형 및 속성 ​

스팬 속성 ​

이벤트 ​

익스포터(Exporters) ​

Logging 익스포터 ​

OpenTelemetry HTTP 익스포터 ​

OpenTelemetry gRPC 익스포터 ​

Langfuse와 통합 ​

W&B Weave와 통합 ​

Jaeger와 통합 ​

사전 요구 사항 ​

예시 ​

문제 해결 ​

일반적인 문제 ​

MCP (Model Context Protocol) 텔레메트리 지원 ​

개요 ​

MCP 속성 ​

스팬 명명 규칙 ​

모범 사례 ​

예시: 텔레메트리가 포함된 전체 MCP 클라이언트 ​

OpenTelemetry 지원

개요

주요 OpenTelemetry 개념

설치

설정

기본 설정

setServiceInfo

addSpanExporter

addSpanProcessor

addResourceAttributes

setSampler

setVerbose

setSdk

고급 설정

샘플러(Sampler)

리소스 속성(Resource attributes)

스팬 유형 및 속성

스팬 속성

이벤트

익스포터(Exporters)

Logging 익스포터

OpenTelemetry HTTP 익스포터

OpenTelemetry gRPC 익스포터

Langfuse와 통합

W&B Weave와 통합

Jaeger와 통합

사전 요구 사항

예시

문제 해결

일반적인 문제

MCP (Model Context Protocol) 텔레메트리 지원

개요

MCP 속성

스팬 명명 규칙

모범 사례

예시: 텔레메트리가 포함된 전체 MCP 클라이언트