Trace를 사용하여 MCP 호출 조사

Cloud Trace는 도구 호출, 메서드 호출, 프롬프트 및 응답과 같은 데이터를 수집하고 표시하여 에이전트 애플리케이션의 동작을 이해하는 데 도움을 줍니다. 이 문서에서는 원격 Google Cloud MCP 서버를 호출하는 에이전트 애플리케이션을 구성하여 이러한 서버가 호출 상태를 기록하는 스팬을 생성하도록 하는 방법을 설명합니다.

스팬은 더 큰 엔드 투 엔드 작업의 일부인 단일 함수 또는 작업을 기록합니다. 트레이스는 단일 엔드 투 엔드 작업을 나타내며 스팬으로 구성됩니다. 따라서 트레이스는 호출된 함수의 시퀀스와 전체 지연 시간에 관한 정보를 제공하고 스팬은 특정 함수의 상태 및 지연 시간 정보를 제공합니다.

도구 정보

도구를 사용하면 에이전트가 일반적으로 외부 API와 상호작용하여 학습 데이터 외부의 정보를 수집할 수 있습니다. Google Cloud MCP 서버를 사용하면 에이전트 애플리케이션이 Google Cloud API 메서드를 호출하는 도구를 호출할 수 있습니다. 예를 들어 애플리케이션은 list_log_entries 도구를 호출하여 최근 로그 데이터를 가져올 수 있습니다.

모델 컨텍스트 프로토콜 (MCP)은 AI 에이전트가 외부 도구, 데이터 소스, 리소스와 통신하고 상호작용하는 표준화된 방법을 정의하는 사양입니다. MCP 서버를 제공하는 제품의 전체 목록과 참조 문서 링크는 지원되는 제품을 참고하세요.

추적 컨텍스트가 MCP 서버에 전달되는 방식

list_log_entries 문서와 같은 MCP 참조 페이지에서는 도구에 HTTP 요청을 전송하는 데 사용할 수 있는 curl 명령의 예를 제공합니다. 요청에서 전송된 JSON 페이로드는 다음과 유사합니다.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

name 필드의 값은 list_log_entries과 같은 도구 이름을 나열합니다. arguments 필드에는 요청을 완료하기 위해 작업에 필요한 정보가 포함됩니다.

MCP 표준은 클라이언트와 서버가 상호작용에 메타데이터를 연결할 수 있는 _meta 필드를 정의합니다. 클라이언트와 서버는 이 필드를 사용하여 추적 컨텍스트를 전달할 수 있습니다.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
    "_meta": {
        "traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG"
        "tracestate": "Vendor specific information."
      }
  },
  "id": 1
}

_meta 데이터에는 traceparent 필드가 포함됩니다. 이 필드의 값 형식은 월드 와이드 웹 컨소시엄 (W3C) traceparent 헤더에 의해 정의됩니다. 값에는 다음이 포함됩니다.

  • traceparent 사양 (00)의 버전입니다.
  • 트레이스 ID (TRACE_ID)입니다.
  • 호출 스팬의 ID (PARENT_SPAN_ID)입니다.
  • 호출 스팬이 요청을 샘플링했는지 여부를 지정합니다 (SAMPLED_FLAG). 이 필드는 샘플링된 경우 01 값을 갖고 샘플링되지 않은 경우 00 값을 갖습니다.

tracestate 필드에는 공급업체별 추적 정보가 포함됩니다.

제한사항

  • 트레이스 컨텍스트는 W3C 트레이스 컨텍스트 표준을 따라야 하며 sampled 플래그는 1로 설정해야 합니다.

  • 원격 Google Cloud MCP 서버는 tools/call 작업에 대해 단일 스팬을 생성할 수 있지만 다른 유형의 작업이나 tools/call 작업의 하위 스팬에 대해서는 스팬을 생성하지 않습니다.

  • 원격 Google Cloud MCP 서버는 요청이 인증되고, 승인되고, 기타 내부 검사를 통과한 경우에만 스팬을 생성합니다.

추적을 지원하는 원격 Google 및 Google Cloud MCP 서버

다음 제품에는 원격 MCP 서버가 tools/call 작업의 추적 범위를 생성할 수 있는 통합이 포함되어 있습니다.

Product 참조
Cloud Logging Cloud Logging MCP 참조
Cloud Monitoring Cloud Monitoring MCP 참조
Maps Grounding Lite Maps Grounding Lite MCP 참조
GKE GKE MCP 참조
Cloud Run Cloud Run MCP 참조
Compute Engine Compute Engine MCP 참조

애플리케이션 구성 방법

_meta 필드를 사용하여 추적 컨텍스트를 전달하는 프레임워크나 SDK를 사용할 수 있습니다. 이러한 프레임워크와 SDK에는 MCP용 OpenTelemetry 시맨틱 규칙을 지원하는 항목이 포함됩니다.

예를 들어 에이전트 개발 키트 (ADK) 프레임워크를 사용할 수 있습니다. 자세한 내용은 OpenTelemetry를 사용하여 ADK 애플리케이션 계측을 참고하세요.

스팬을 보는 방법

trace 데이터를 보려면 Trace 탐색기를 사용하세요. 이 페이지에서는 trace 데이터에 관한 집계 정보를 확인하고 개별 trace와 스팬을 살펴볼 수 있습니다. 자세한 내용은 trace 찾기 및 탐색을 참고하세요.

MCP 서버에서 작성한 스팬을 보려면 스팬 이름으로 트레이스 데이터를 필터링하세요. 예를 들어 일부 원격 Google Cloud MCP 서버는 tools/call 작업을 수신할 때 추적 스팬을 생성할 수 있습니다. 이러한 스팬에는 다음과 같은 명명 규칙이 있습니다.

tools/call NAME

이전 표현식에서 NAME는 호출된 엔드포인트를 참조합니다. 예를 들어 list_keys와 비슷할 수 있습니다. 이 이름 지정 규칙은 MCP용 OpenTelemetry 시맨틱 규칙에 의해 정의됩니다.

이러한 스팬을 찾으려면 필터 표시줄을 사용하고 mcp.method.name의 속성 필터를 추가합니다. 필터 값을 tools/call로 설정합니다.

계측 샘플

계측 권장사항은 계측 방법 선택을 참고하세요.

제공되는 계측 샘플은 OpenTelemetry를 사용합니다.