목록으로
기술

OpenTelemetry 지원

·6분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — index 이 글은 Koog 공식 문서의 index 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

OpenTelemetry 지원

이 페이지에서는 추적 및 추적을 위한 Koog 에이전트 프레임워크를 사용한 OpenTelemetry 지원에 대한 세부정보를 제공합니다. AI 에이전트를 모니터링합니다.

개요

OpenTelemetry는 원격 측정 데이터를 생성, 수집 및 내보내기 위한 도구를 제공하는 관찰 프레임워크입니다. (추적) 귀하의 응용 프로그램에서. Koog OpenTelemetry 기능을 사용하면 AI 에이전트를 계측하여 수집할 수 있습니다. 다음을 수행하는 데 도움이 되는 원격 측정 데이터

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

주요 OpenTelemetry 개념

  • 범위: 범위는 분산 추적 내의 개별 작업 단위 또는 작업을 나타냅니다. 그들은 다음을 나타냅니다. 에이전트 실행, 함수 호출, LLM 호출과 같은 애플리케이션의 특정 활동의 시작과 끝 또는 도구 호출.
  • 속성: 속성은 범위와 같은 원격 분석 관련 항목에 대한 메타데이터를 제공합니다. 속성이 표현됩니다. 키-값 쌍으로.
  • 이벤트: 이벤트는 범위(범위 관련 이벤트) 기간 동안 다음을 나타내는 특정 시점입니다. 잠재적으로 주목할만한 일이 일어났습니다.
  • 내보내기: 내보내기는 수집된 원격 측정 데이터를 다양한 백엔드 또는 목적지.
  • 수집기: 수집기는 원격 측정 데이터를 수신, 처리 및 내보냅니다. 그들은 귀하 사이의 중개자 역할을 합니다. 애플리케이션 및 관측 가능성 백엔드.
  • 샘플러: 샘플러는 샘플링 전략에 따라 추적을 기록해야 하는지 여부를 결정합니다. 그들은 익숙하다 원격 측정 데이터의 양을 관리합니다.
  • 리소스: 리소스는 원격 측정 데이터를 생성하는 엔터티를 나타냅니다. 리소스 속성으로 식별됩니다. 이는 리소스에 대한 정보를 제공하는 키-값 쌍입니다.

Koog의 OpenTelemetry 기능은 다음을 포함한 다양한 에이전트 이벤트에 대한 범위를 자동으로 생성합니다.

  • 에이전트 실행 시작 및 종료
  • 노드 실행
  • LLM 통화
  • 도구 호출

설치

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

코틀린

1val agent = AIAgent(2    promptExecutor = promptExecutor,3    llmModel = OpenAIModels.Chat.GPT4o,4    systemPrompt = "You are a helpful assistant.",5    installFeatures = {6        install(OpenTelemetry) {7            // Configuration options go here8        }9    }10)

자바

1var agent = AIAgent.builder()2    .promptExecutor(promptExecutor)3    .llmModel(OpenAIModels.Chat.GPT4o)4    .systemPrompt("You are a helpful assistant.")5    .install(OpenTelemetry.Feature, config -> {6        // Configuration options go here7    })8    .build();

구성

기본 구성

다음은 에이전트에서 OpenTelemetry 기능을 구성할 때 설정하는 사용 가능한 속성의 전체 목록입니다.

이름 데이터 유형 기본값 설명
serviceName String ai.koog 계측 중인 서비스의 이름입니다.
serviceVersion String 현재 Koog 라이브러리 버전 계측 중인 서비스의 버전입니다.
isVerbose Boolean false OpenTelemetry 구성 디버깅을 위해 자세한 로깅을 활성화할지 여부입니다.
sdk OpenTelemetrySdk 원격 측정 수집에 사용할 OpenTelemetry SDK 인스턴스입니다.
tracer Tracer 범위 생성에 사용되는 OpenTelemetry 추적기 인스턴스입니다.

참고 sdk 및 tracer 속성은 액세스할 수 있는 공용 속성이지만 아래에 나열된 공개 메소드.

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

코틀린

1install(OpenTelemetry) {2    // Set your service configuration3    setServiceInfo("my-agent-service", "1.0.0")4    5    // Add the Logging exporter6    addSpanExporter(LoggingSpanExporter.create())7}

자바

1install(OpenTelemetry.Feature, config -> {2    // Set your service configuration3    config.setServiceInfo("my-agent-service", "1.0.0");45    // Add the Logging exporter6    config.addSpanExporter(LoggingSpanExporter.create());7})

사용 가능한 방법에 대한 참조는 아래 섹션을 참조하세요.

setServiceInfo

이름, 버전 등 서비스 정보를 설정합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
serviceName 끈 예 계측 중인 서비스의 이름입니다.
serviceVersion 끈 예 계측 중인 서비스의 버전입니다.

addSpanExporter

원격 측정 데이터를 외부 시스템으로 보내기 위해 범위 내보내기를 추가합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
exporter SpanExporter 예 사용자 정의 범위 내보내기 목록에 추가할 SpanExporter 인스턴스입니다.

addSpan프로세서

범위를 내보내기 전에 처리하기 위해 범위 프로세서 팩토리를 추가합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
processor (SpanExporter) -> SpanProcessor 예 특정 내보내기에 대한 범위 프로세서를 생성하는 함수입니다. 내보내기별로 처리를 사용자 정의할 수 있습니다.

addResourceAttributes

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

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

세트샘플러

수집되는 범위를 제어하기 위해 샘플링 전략을 설정합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
sampler Sampler 예 OpenTelemetry 구성을 위해 설정할 샘플러 인스턴스입니다.

setVerbose

자세한 로깅을 활성화하거나 비활성화합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
verbose Boolean 예 false true인 경우 애플리케이션은 더 자세한 원격 측정 데이터를 수집합니다.

참고

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

setSdk

사전 구성된 OpenTelemetrySdk 인스턴스를 삽입합니다.

  • setSdk(sdk)를 호출하면 제공된 SDK가 있는 그대로 사용되며 addSpanExporter, addSpanProcessor, addResourceAttributes 또는 setSampler를 통해 적용된 모든 맞춤 구성은 무시됩니다.
  • 추적 프로그램의 계측 범위 이름/버전은 서비스 정보와 일치합니다.
이름 데이터 유형 필수의 설명
sdk OpenTelemetrySdk 예 에이전트에서 사용할 SDK 인스턴스입니다.

addMetricExporter

메트릭 데이터를 외부 시스템으로 보내기 위해 메트릭 내보내기를 추가합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
exporter MetricExporter 예 주기적 메트릭 리더에 등록하기 위한 MetricExporter 인스턴스입니다.
meterInterval Duration 아니요 1s 측정항목 읽기 사이의 간격입니다. java.time.Duration로도 사용 가능합니다.

등록된 메트릭 내보내기가 없으면 Koog는 로컬 개발 중에 메트릭이 표시되도록 콘솔 LoggingMetricExporter으로 대체됩니다.

addMetricFilter

특정 측정항목에 대해 보고되는 속성 키를 제한합니다. 이는 나열되지 않은 속성을 삭제하는 OpenTelemetry View을 설치합니다. 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본값 설명
metricName String 예 필터를 적용할 미터법 기기의 이름입니다.
keysToRetain Set<String> 예 이 측정항목에 대해 보관해야 하는 속성 키입니다.

이를 사용하면 지표 자체를 내보내는 동안 카디널리티가 높은 속성(예: 요청 식별자)이 지표 백엔드를 폭파하는 것을 방지할 수 있습니다.

고급 구성

고급 구성을 위해 다음 구성 옵션을 사용자 정의할 수도 있습니다.

  • 샘플러: 수집되는 데이터의 빈도와 양을 조정하기 위해 샘플링 전략을 구성합니다.
  • 리소스 속성: 원격 측정 데이터를 생성하는 프로세스에 대한 추가 정보를 추가합니다.

코틀린

1install(OpenTelemetry) {2    // Set your service configuration3    setServiceInfo("my-agent-service", "1.0.0")4    5    // Add the Logging exporter6    addSpanExporter(LoggingSpanExporter.create())7    8    // Set the sampler 9    setSampler(Sampler.traceIdRatioBased(0.5)) 1011    // Add resource attributes12    addResourceAttributes(mapOf(13        AttributeKey.stringKey("custom.attribute") to "custom-value")14    )15}

자바

1install(OpenTelemetry.Feature, config -> {2    // Set your service configuration3    config.setServiceInfo("my-agent-service", "1.0.0");45    // Add the Logging exporter6    config.addSpanExporter(LoggingSpanExporter.create());78    // Set the sampler9    config.setSampler(Sampler.traceIdRatioBased(0.5));1011    // Add resource attributes12    config.addResourceAttributes(Map.of(13        AttributeKey.stringKey("custom.attribute"), "custom-value"14    ));15})

샘플러

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

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

  • Sampler.alwaysOn(): 모든 범위(추적)가 샘플링되는 기본 샘플링 전략입니다.

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

자원 속성

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

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

service.name 속성의 기본값은 ai.koog이고, 기본 service.version 값은 현재 Koog 라이브러리 버전을 사용하고 있습니다.

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

코틀린

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

자바

1config.addResourceAttributes(Map.of(2    AttributeKey.stringKey("custom.attribute"), "custom-value"3));

추적되는 내용

OpenTelemetry 기능은 다음 에이전트 활동을 캡처합니다.

  • 에이전트 수명 주기 이벤트: 에이전트 시작, 중지, 오류
  • LLM 상호 작용: 프롬프트, 응답, 토큰 사용, 대기 시간 및 실패(LLM 호출이 발생하면 범위는 범위 상태 ERROR 및 error.type로 표시됨)
  • 도구 호출: 도구 호출에 대한 실행 추적
  • 시스템 컨텍스트: 모델명, 환경, Koog 버전 등의 메타데이터

기본적으로 LLM 프롬프트 및 응답의 내용은 민감한 데이터 노출을 방지하기 위해 내보낸 범위에서 마스킹됩니다. 전체 콘텐츠를 포함하려면 setVerbose(true)을 호출하세요.

개별 범위 유형 및 속성에 대한 자세한 분석은 Span types and attributes을 참조하세요.

스팬 유형 및 속성

OpenTelemetry 기능은 에이전트의 다양한 작업을 추적하기 위해 다양한 유형의 범위를 자동으로 생성합니다.

  • CreateAgentSpan: 에이전트를 실행할 때 생성되고, 에이전트가 닫히거나 프로세스가 종료되면 닫힙니다.
  • InvokeAgentSpan: 에이전트 호출입니다.
  • StrategySpan: 에이전트 전략의 실행(최상위 실행 흐름)
  • NodeExecuteSpan: 에이전트 전략의 노드 실행입니다. 이는 사용자 정의된 Koog 전용 범위입니다.
  • SubgraphExecuteSpan: 에이전트 전략 내의 하위 그래프 실행입니다. 이는 사용자 정의된 Koog 전용 범위입니다.
  • InferenceSpan: LLM 호출입니다.
  • ExecuteToolSpan: 도구 호출.
  • McpClientSpan: MCP(모델 컨텍스트 프로토콜) 클라이언트 작업입니다. 이 범위는 MCP에 대한 OpenTelemetry 의미 체계 규칙을 따릅니다.

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

1CreateAgentSpan2    InvokeAgentSpan3        StrategySpan4            NodeExecuteSpan5                InferenceSpan6            NodeExecuteSpan7                ExecuteToolSpan8            SubgraphExecuteSpan9                NodeExecuteSpan10                    InferenceSpan

스팬 속성

범위 속성은 범위와 관련된 메타데이터를 제공합니다. 각 범위에는 고유한 속성 세트가 있지만 일부 범위에는 속성을 반복합니다.

Koog는 OpenTelemetry의 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 통화가 시작되거나 완료된 경우입니다. 이벤트에도 속성이 있으며 추가로 이벤트가 포함됩니다. 본문 필드.

OpenTelemetry의 Semantic conventions for generative AI events에 따라 다음 이벤트 유형이 지원됩니다.

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

참고 optentelemetry-java SDK는 이벤트 추가 시 이벤트 본문 필드 매개변수를 지원하지 않습니다. 따라서 Koog의 OpenTelemetry 지원, 이벤트 본문 필드는 키가 body이고 값 유형이 다음과 같은 별도의 속성입니다. 문자열. 문자열에는 일반적으로 JSON과 유사한 개체인 이벤트 본문 필드에 대한 콘텐츠 또는 페이로드가 포함됩니다. 에 대한 이벤트 본문 필드의 예는 OpenTelemetry documentation을 참조하세요. 행사 주체 지원 현황에 대해 opentelemetry-java의 필드에 대해서는 관련 GitHub issue을 참조하세요.

측정항목

범위 외에도 OpenTelemetry 기능은 OpenTelemetry의 Semantic conventions for GenAI metrics을 따르는 측정항목을 내보냅니다. 메트릭은 addMetricExporter을 통해 구성된 미터 공급자를 통해 내보내집니다. 등록된 내보내기가 없으면 기본적으로 콘솔 LoggingMetricExporter이 사용됩니다.

다음 악기가 등록되어 있습니다:

이름 기구 단위 설명
gen_ai.client.token.usage 히스토그램 {token} 각 LLM 호출에 대해 보고된 토큰 사용량은 gen_ai.token.type(input/output)으로 나뉩니다.
gen_ai.client.operation.duration 히스토그램 s GenAI 작업 기간 — text_completion(LLM 호출) 및 execute_tool(도구 호출) 모두.
koog.gen_ai.client.tool.call.count 계수기 {call} 도구 이름과 통화 상태로 라벨이 지정된 에이전트가 수행한 도구 호출의 Koog 관련 카운터입니다.

명시적인 히스토그램 버킷 경계는 의미론적 규칙에 따라 조언으로 제공됩니다.

  • gen_ai.client.token.usage: [1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864]
  • gen_ai.client.operation.duration: [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]

gen_ai.provider.name

모든 데이터 포인트에는 gen_ai.provider.name 속성이 있습니다.

  • text_completion 작업의 경우 값은 LLM 공급자 ID입니다(예: openai, anthropic).
  • execute_tool 작업의 경우 도구 실행이 타사 공급자가 아닌 프로세스 중에 발생하므로 값은 koog입니다. MCP 도구 실행은 이 값을 유지하고 해당 범위의 별도 mcp.* 속성을 통해 MCP 관련 세부 정보를 표시하므로 도구 메트릭은 낮은 카디널리티로 유지됩니다.

오류.유형

error.type은 GenAI semconv 요구 사항에 따라 실패한 gen_ai.client.operation.duration 데이터 포인트에만 설정됩니다. 값은 실패를 일으킨 오류의 표준 Java 클래스 이름이므로 예외 계층 구조로 제한되며 측정항목 차원으로 사용해도 안전합니다.

  • AIAgentError의 하위 클래스 — execute_tool 실패 및 도구 검증 실패에 대한 것입니다.
  • 에이전트 수준 오류 후크를 통해 표면화되는 text_completion 오류의 경우 LLM 클라이언트 또는 에이전트 런타임에서 발생하는 모든 Throwable.
  • _OTHER — 관련 오류 없이 에이전트 종료 시 진행 중인 작업이 플러시되는 경우의 대체입니다.

성공적인 작업에는 속성이 설정되지 않습니다.

제한도구이름카디널리티

도구 메트릭에는 gen_ai.tool.name 레이블이 지정됩니다. 이름이 동적이거나 사용자가 생성한 도구를 노출하는 경우 도구 이름 카디널리티가 제한 없이 커질 수 있습니다. restrictToolNameCardinality을 사용하여 허용 목록 외부의 모든 이름을 단일 대체 값에 매핑합니다.

모든 계측기 및 속성 키에 적용되는 메트릭별 속성 필터링의 경우 addMetricFilter을 사용하세요.

수출업체

내보내기자는 수집된 원격 측정 데이터를 OpenTelemetry Collector나 기타 유형의 대상 또는 백엔드로 보냅니다. 구현. 내보내기를 추가하려면 OpenTelemetry 기능을 설치할 때 addSpanExporter() 방법을 사용하십시오. 는 메서드는 다음 인수를 사용합니다.

이름 데이터 유형 필수의 기본 설명
exporter SpanExporter 예 사용자 정의 범위 내보내기 목록에 추가할 SpanExporter 인스턴스입니다.

아래 섹션에서는 opentelemetry-java SDK에서 가장 일반적으로 사용되는 일부 내보내기 프로그램에 대한 정보를 제공합니다.

참고 사용자 정의 내보내기 도구를 구성하지 않으면 Koog는 기본적으로 LoggingSpanExporter 콘솔을 사용합니다. 이는 로컬 개발 및 디버깅 중에 도움이 됩니다.

로깅 내보내기

콘솔에 추적 정보를 출력하는 로깅 내보내기입니다. LoggingSpanExporter (io.opentelemetry.exporter.logging.LoggingSpanExporter)은 opentelemetry-java SDK의 일부입니다.

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

코틀린

1install(OpenTelemetry) {2    // Add the logging exporter3    addSpanExporter(LoggingSpanExporter.create())4    // Add more exporters as needed5}

자바

1install(OpenTelemetry.Feature, config -> {2    // Add the logging exporter3    config.addSpanExporter(LoggingSpanExporter.create());4    // Add more exporters as needed5})

OpenTelemetry HTTP 내보내기

OpenTelemetry HTTP 내보내기(OtlpHttpSpanExporter)는 opentelemetry-java SDK의 일부입니다. (io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter)을 수행하고 HTTP를 통해 스팬 데이터를 백엔드로 보냅니다.

코틀린

1install(OpenTelemetry) {2    // Add OpenTelemetry HTTP exporter 3    addSpanExporter(4        OtlpHttpSpanExporter.builder()5            // Set the maximum time to wait for the collector to process an exported batch of spans 6            .setTimeout(30, TimeUnit.SECONDS)7            // Set the OpenTelemetry endpoint to connect to8            .setEndpoint("http://localhost:3000/api/public/otel/v1/traces")9            // Add the authorization header10            .addHeader("Authorization", "Basic $AUTH_STRING")11            .build()12    )13}

자바

1install(OpenTelemetry.Feature, config -> {2    // Add OpenTelemetry HTTP exporter3    config.addSpanExporter(4        OtlpHttpSpanExporter.builder()5            // Set the maximum time to wait for the collector to process an exported batch of spans6            .setTimeout(30, TimeUnit.SECONDS)7            // Set the OpenTelemetry endpoint to connect to8            .setEndpoint("http://localhost:3000/api/public/otel/v1/traces")9            // Add the authorization header10            .addHeader("Authorization", "Basic " + AUTH_STRING)11            .build()12    );13})

OpenTelemetry gRPC 내보내기 도구

OpenTelemetry gRPC 내보내기(OtlpGrpcSpanExporter)는 opentelemetry-java SDK의 일부입니다. (io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter). gRPC를 통해 원격 측정 데이터를 백엔드로 내보냅니다. 데이터를 수신하는 백엔드, 수집기 또는 엔드포인트의 호스트와 포트를 정의할 수 있습니다. 기본 포트는 다음과 같습니다. 4317.

코틀린

1install(OpenTelemetry) {2    // Add OpenTelemetry gRPC exporter 3    addSpanExporter(4        OtlpGrpcSpanExporter.builder()5            // Set the host and the port6            .setEndpoint("http://localhost:4317")7            .build()8    )9}

자바

1install(OpenTelemetry.Feature, config -> {2    // Add OpenTelemetry gRPC exporter3    config.addSpanExporter(4        OtlpGrpcSpanExporter.builder()5            // Set the host and the port6            .setEndpoint("http://localhost:4317")7            .build()8    );9})

Langfuse와의 통합

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

도우미 함수를 사용하여 OpenTelemetry 추적을 Langfuse로 직접 내보내도록 Koog를 구성할 수 있습니다.

코틀린

1install(OpenTelemetry) {2    addLangfuseExporter(3        langfuseUrl = "https://cloud.langfuse.com",4        langfusePublicKey = "...",5        langfuseSecretKey = "..."6    )7}

자바

1install(OpenTelemetry.Feature, config -> {2    config.addLangfuseExporter(3        "https://cloud.langfuse.com",4        "...",5        "...",6        null,7        null8    );9})

Langfuse와의 통합에 관한 full documentation을 읽어보세요.

W&B Weave와의 통합

W&B Weave는 LLM/에이전트 워크로드에 대한 추적 시각화 및 분석을 제공합니다. W&B Weave와의 통합은 사전 정의된 내보내기를 통해 구성할 수 있습니다.

코틀린

1install(OpenTelemetry) {2    addWeaveExporter(3        weaveOtelBaseUrl = "https://trace.wandb.ai",4        weaveEntity = "my-team",5        weaveProjectName = "my-project",6        weaveApiKey = "..."7    )8}

자바

1install(OpenTelemetry.Feature, config -> {2    config.addWeaveExporter(3        "https://trace.wandb.ai",4        "my-team",5        "my-project",6        "..."7    );8})

W&B Weave와의 통합에 관한 full documentation을 읽어보세요.

Datadog과의 통합

Datadog은 클라우드 규모 애플리케이션에 대한 모니터링, 관찰 가능성 및 분석을 제공합니다. Datadog과의 통합은 사전 정의된 내보내기를 통해 구성할 수 있습니다.

코틀린

1install(OpenTelemetry) {2    addDatadogExporter(3        datadogApiKey = "...",4        datadogSite = "datadoghq.com"5    )6}

자바

1install(OpenTelemetry.Feature, config -> {2    config.addDatadogExporter(3        "...",           // datadogApiKey4        "datadoghq.com", // datadogSite5        null,6        null7    );8})

Datadog과의 통합에 관한 full documentation을 읽어보세요.

Jaeger와의 통합

Jaeger는 OpenTelemetry와 함께 작동하는 널리 사용되는 분산 추적 시스템입니다. opentelemetry 디렉터리 Koog 저장소의 examples에는 Jaeger 및 Koog 에이전트와 함께 OpenTelemetry를 사용하는 예가 포함되어 있습니다.

전제 조건

Koog 및 Jaeger로 OpenTelemetry를 테스트하려면 제공된 도구를 사용하여 Jaeger OpenTelemetry 올인원 프로세스를 시작하십시오. docker-compose.yaml 파일, 다음 명령을 실행하여:

1docker compose up -d

제공된 Docker Compose YAML 파일에는 다음 콘텐츠가 포함되어 있습니다.

1## docker-compose.yaml2services:3  jaeger-all-in-one:4    image: jaegertracing/all-in-one:1.395    container_name: jaeger-all-in-one6    environment:7      - COLLECTOR_OTLP_ENABLED=true8    ports:9      - "4317:4317"10      - "16686:16686"

Jaeger UI에 액세스하고 추적을 보려면 http://localhost:16686을 엽니다.

예

Jaeger에서 사용할 원격 측정 데이터를 내보내려면 예제에서는 LoggingSpanExporter을 사용합니다. (io.opentelemetry.exporter.logging.LoggingSpanExporter) 및 OtlpGrpcSpanExporter (io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter) opentelemetry-java SDK에서.

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

코틀린

1fun main() = runBlocking {2    val agent = AIAgent(3        promptExecutor = promptExecutor,4        llmModel = OpenAIModels.Chat.O4Mini,5        systemPrompt = "You are a code assistant. Provide concise code examples."6    ) {7        install(OpenTelemetry) {8            // Add a console logger for local debugging9            addSpanExporter(LoggingSpanExporter.create())1011            // Send traces to OpenTelemetry collector12            addSpanExporter(13                OtlpGrpcSpanExporter.builder()14                    .setEndpoint("http://localhost:4317")15                    .build()16            )17        }18    }1920    agent.use { agent ->21        println("Running the agent with OpenTelemetry tracing...")2223        val result = agent.run("Tell me a joke about programming")2425        println("Agent run completed with result: '$result'." +26                "\nCheck Jaeger UI at http://localhost:16686 to view traces")27    }28}

자바

1public static void main(String[] args) {2    var agent = AIAgent.builder()3        .promptExecutor(promptExecutor)4        .llmModel(OpenAIModels.Chat.O4Mini)5        .systemPrompt("You are a code assistant. Provide concise code examples.")6        .install(OpenTelemetry.Feature, config -> {7            // Add a console logger for local debugging8            config.addSpanExporter(LoggingSpanExporter.create());910            // Send traces to OpenTelemetry collector11            config.addSpanExporter(12                OtlpGrpcSpanExporter.builder()13                    .setEndpoint("http://localhost:4317")14                    .build()15            );16        })17        .build();1819    System.out.println("Running the agent with OpenTelemetry tracing...");2021    var result = agent.run("Tell me a joke about programming");2223    System.out.println(24        "Agent run completed with result: '" + result + "'." +25            "\nCheck Jaeger UI at http://localhost:16686 to view traces"26    );27}

문제 해결

일반적인 문제

  1. 백엔드에 흔적이 나타나지 않습니다
  • 모든 필수 환경 변수가 셸에서 설정되고 내보내졌는지 확인하세요.
  • API 키 또는 비밀이 유효하고, 취소되지 않았으며, 쓰기/추적 권한이 있는지 확인하세요.
  • 서비스가 실행 중이고 OpenTelemetry 포트(4317)에 액세스할 수 있는지 확인하세요.
  • 내보내기가 올바른 엔드포인트로 구성되어 있는지 확인하세요.
  • 에이전트 실행 후 몇 초 정도 기다리십시오. 추적이 즉시 나타나지 않을 수도 있습니다.
  1. 연결 문제
  • 환경이 수출자의 섭취 엔드포인트에 도달할 수 있는지 확인하세요.
  • 아웃바운드 HTTPS 트래픽을 차단하는 방화벽 또는 프록시 설정을 확인하세요.
  1. 누락된 범위 또는 불완전한 추적
  • 에이전트 실행이 성공적으로 완료되었는지 확인합니다.
  • 에이전트 실행 후 애플리케이션을 너무 빨리 닫지 않는지 확인하세요.
  • 범위를 내보내는 데 걸리는 시간을 허용하려면 에이전트 실행 후 지연을 추가하세요.
  1. 경간 개수가 너무 많음
  • sampler 속성을 구성하여 다른 샘플링 전략을 사용해 보세요.
  • 예를 들어, 추적의 10%만 샘플링하려면 Sampler.traceIdRatioBased(0.1)을 사용하십시오.
  1. 스팬 어댑터는 서로 재정의됩니다
  • 현재 OpenTelemetry 에이전트 기능은 다중 범위 어댑터 KG-265 적용을 지원하지 않습니다.

MCP(모델 컨텍스트 프로토콜) 원격 측정 지원

Koog는 official OpenTelemetry semantic conventions for MCP에 따라 MCP 작업을 위한 포괄적인 OpenTelemetry 계측을 제공합니다.

개요

MCP 원격 측정 지원에는 다음이 포함됩니다.

  • MCP 관련 속성을 사용한 도구 실행 범위의 자동 강화
  • MCP 클라이언트 작업(도구/호출)을 위한 클라이언트 측 계측
  • 모든 필수, 조건부 필수 및 권장 속성을 포함하는 전체 의미 규칙 준수

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 클라이언트

코틀린

1// Create MCP tools registry2val toolRegistry = McpToolRegistryProvider.fromSseUrl("http://localhost:3000")34// Create agent with OpenTelemetry enabled and pass the tool registry5val agent = AIAgent(6    promptExecutor = promptExecutor,7    llmModel = OpenAIModels.Chat.GPT4o,8    systemPrompt = "You are a helpful assistant.",9    toolRegistry = toolRegistry10) {11    install(OpenTelemetry) {12        setServiceInfo("mcp-agent-service", "1.0.0")13        addSpanExporter(LoggingSpanExporter.create())14    }15}1617// Run agent - MCP tool calls will be automatically instrumented18agent.use {19    it.run("Use the search tool to find information")20}

이 설정은 OpenTelemetry 모범 사례 및 의미 체계 규칙에 따라 최소한의 코드 변경으로 MCP 작업에 대한 완전한 관찰 가능성을 제공합니다.

#Koog#JetBrains#AI Agent#Kotlin#Java#JVM