Trace를 사용하여 MCP 호출 조사

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

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

도구 정보

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

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

trace 컨텍스트를 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 필드를 정의합니다. 클라이언트와 서버는 이 필드를 사용하여 trace 컨텍스트를 전달할 수 있습니다.

{
  "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)
  • trace의 ID (TRACE_ID)
  • 호출 스팬의 ID (PARENT_SPAN_ID)
  • 호출 스팬이 요청을 샘플링했는지 여부를 지정합니다 (SAMPLED_FLAG). 이 필드는 샘플링된 경우 01 값을 가지며 샘플링되지 않은 경우 00 값을 가집니다.

tracestate 필드는 공급업체별 추적 정보를 전달합니다.

제한사항

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

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

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

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

다음 제품에는 원격 MCP 서버가 tools/call 작업의 trace 스팬을 생성할 수 있도록 하는 통합이 포함되어 있습니다.

제품 참조
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 필드를 사용하여 trace 컨텍스트를 전달하는 프레임워크 또는 SDK를 사용할 수 있습니다. 이러한 프레임워크와 SDK에는 MCP의 OpenTelemetry 의미 체계를 지원하는 프레임워크와 SDK가 포함됩니다.

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

스팬을 보는 방법

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

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

tools/call NAME

이전 표현식에서 NAME은 호출된 엔드포인트를 나타냅니다. 예를 들어 list_keys와 유사할 수 있습니다. 이 이름 지정 규칙은 MCP의 OpenTelemetry 의미 체계에 의해 정의됩니다.

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

계측 샘플

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

Google에서 제공하는 계측 샘플은 OpenTelemetry를 사용합니다.