Docs
개발
로컬 개발

로컬 개발 가이드 (Local development guide)

이 가이드는 개발 트레이싱과 같은 로컬 개발 기능을 설정하고 사용하는 방법에 대한 지침을 제공합니다.

개발 트레이싱 (Development tracing)

개발 트레이스(dev traces)는 모델 호출, 도구 스케줄러, 도구 호출 등과 같은 흥미로운 이벤트를 계측하여 코드를 디버깅하는 데 도움이 되는 OpenTelemetry(OTel) 트레이스입니다.

개발 트레이스는 상세하며 에이전트 동작을 이해하고 문제를 디버깅하기 위한 것입니다. 기본적으로 비활성화되어 있습니다.

개발 트레이스를 활성화하려면 Gemini CLI를 실행할 때 GEMINI_DEV_TRACING=true 환경 변수를 설정하세요.

개발 트레이스 보기 (Viewing dev traces)

Jaeger 또는 Genkit Developer UI를 사용하여 개발 트레이스를 볼 수 있습니다.

Genkit 사용 (Using Genkit)

Genkit은 트레이스 및 기타 원격 측정 데이터를 보기 위한 웹 기반 UI를 제공합니다.

  1. Genkit 텔레메트리 서버 시작:

    Genkit 서버를 시작하려면 다음 명령을 실행하세요:

    npm run telemetry -- --target=genkit

    스크립트는 Genkit Developer UI의 URL을 출력합니다. 예:

    Genkit Developer UI: http://localhost:4000

  2. 개발 트레이싱으로 Gemini CLI 실행:

    별도의 터미널에서 GEMINI_DEV_TRACING 환경 변수와 함께 Gemini CLI 명령을 실행하세요:

    GEMINI_DEV_TRACING=true gemini

  3. 트레이스 보기:

    브라우저에서 Genkit Developer UI URL을 열고 Traces 탭으로 이동하여 트레이스를 봅니다.

Jaeger 사용 (Using Jaeger)

Jaeger UI에서 개발 트레이스를 볼 수 있습니다. 시작하려면 다음 단계를 따르세요:

  1. 텔레메트리 수집기 시작:

    터미널에서 다음 명령을 실행하여 Jaeger 및 OTEL 수집기를 다운로드하고 시작합니다:

    npm run telemetry -- --target=local

    이 명령은 또한 로컬 텔레메트리에 맞게 작업 공간을 구성하고 Jaeger UI에 대한 링크(일반적으로 http://localhost:16686)를 제공합니다.

  2. 개발 트레이싱으로 Gemini CLI 실행:

    별도의 터미널에서 GEMINI_DEV_TRACING 환경 변수와 함께 Gemini CLI 명령을 실행하세요:

    GEMINI_DEV_TRACING=true gemini

  3. 트레이스 보기:

    명령을 실행한 후 브라우저에서 Jaeger UI 링크를 열어 트레이스를 봅니다.

텔레메트리에 대한 자세한 내용은 텔레메트리 문서를 참조하십시오.

개발 트레이스로 코드 계측 (Instrumenting code with dev traces)

더 자세한 계측을 위해 자신의 코드에 개발 트레이스를 추가할 수 있습니다. 이는 실행 흐름을 디버깅하고 이해하는 데 유용합니다.

runInDevTraceSpan 함수를 사용하여 코드 섹션을 트레이스 범위로 래핑하세요.

다음은 기본적인 예입니다:

import { runInDevTraceSpan } from '@google/gemini-cli-core';
 
await runInDevTraceSpan({ name: 'my-custom-span' }, async ({ metadata }) => {
  // `metadata` 객체를 사용하면 입력 및 출력을 기록할 수 있습니다.
  // 작업뿐만 아니라 다른 속성도 기록할 수 있습니다.
  metadata.input = { key: 'value' };
  // 사용자 정의 속성 설정.
  metadata.attributes['gen_ai.request.model'] = 'gemini-4.0-mega';
 
  // 트레이스될 코드는 여기에 들어갑니다.
  try {
    const output = await somethingRisky();
    metadata.output = output;
    return output;
  } catch (e) {
    metadata.error = e;
    throw e;
  }
});

이 예제에서:

  • name: 트레이스에 표시될 스팬의 이름입니다.
  • metadata.input: (선택 사항) 트레이스된 작업에 대한 입력 데이터를 포함하는 객체입니다.
  • metadata.output: (선택 사항) 트레이스된 작업의 출력 데이터를 포함하는 객체입니다.
  • metadata.attributes: (선택 사항) 스팬에 추가할 사용자 정의 속성의 레코드입니다.
  • metadata.error: (선택 사항) 작업이 실패할 경우 기록할 오류 객체입니다.
이슈 및 PR 자동화NPM 패키지 구조