Google Cloud 플러그인

Google Cloud 플러그인은 Firebase Genkit의 원격 분석 및 로깅 데이터를 Firebase AI 모니터링 대시보드 (비공개 미리보기)를 지원하는 Google Cloud 운영 제품군으로 내보냅니다.

설치

npm i --save @genkit-ai/google-cloud

이 플러그인을 사용하는 흐름을 로컬에서 실행하려면 Google Cloud CLI 도구도 설치해야 합니다.

Google Cloud 계정 설정

이 플러그인에는 Google Cloud 계정(아직 계정이 없는 경우 가입)과 Google Cloud 프로젝트가 필요합니다.

플러그인을 추가하기 전에 프로젝트에 다음 API가 사용 설정되어 있는지 확인합니다.

이러한 API는 프로젝트의 API 대시보드에 표시되어야 합니다.

API 사용 설정 및 사용 중지에 대해 자세히 알아보려면 여기를 클릭하세요.

Genkit 구성

Google Cloud Trace, Logging, Monitoring으로 내보내기를 사용 설정하려면 enableGoogleCloudTelemetry()를 호출하면 됩니다.

import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';

enableGoogleCloudTelemetry();

프로덕션에서 실행하면 원격 분석이 자동으로 내보내집니다.

인증

이 플러그인에는 Google Cloud 프로젝트 ID와 Google Cloud 프로젝트 사용자 인증 정보가 필요합니다. Google Cloud 환경 (Cloud Functions, Cloud Run 등)에서 흐름을 실행하는 경우 프로젝트 ID와 사용자 인증 정보가 자동으로 설정됩니다.

애플리케이션 기본 사용자 인증 정보

다른 환경에서 실행하려면 GCLOUD_PROJECT 환경 변수를 Google Cloud 프로젝트로 설정하고 gcloud 도구를 사용하여 인증해야 합니다.

gcloud auth application-default login

자세한 내용은 애플리케이션 기본 사용자 인증 정보 문서를 참고하세요.

서비스 계정 사용자 인증 정보

서비스 계정을 사용하고 Google Cloud 환경 외부에서 실행하는 경우 사용자 인증 정보를 환경 변수로 설정할 수 있습니다. 여기의 안내에 따라 Google Cloud 서비스 계정 키를 설정합니다.

키 파일을 다운로드한 후에는 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용하여 파일 위치를 지정하거나 json 파일의 콘텐츠를 환경 변수 GCLOUD_SERVICE_ACCOUNT_CREDS에 직접 복사하는 두 가지 방법으로 사용자 인증 정보를 지정할 수 있습니다.

파일 경로:

GOOGLE_APPLICATION_CREDENTIALS = "path/to/your/key/file"

직접 사본:

GCLOUD_SERVICE_ACCOUNT_CREDS='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "your-private-key",
  "client_email": "your-client-email",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "your-cert-url"
}'

플러그인 구성

enableGoogleCloudTelemetry() 함수는 OpenTelemetry NodeSDK 인스턴스를 구성하는 선택적 구성 객체를 사용합니다.

import { AlwaysOnSampler } from '@opentelemetry/sdk-trace-base';

enableGoogleCloudTelemetry({
  forceDevExport: false, // Set this to true to export telemetry for local runs
  sampler: new AlwaysOnSampler(),
  autoInstrumentation: true,
  autoInstrumentationConfig: {
    '@opentelemetry/instrumentation-fs': { enabled: false },
    '@opentelemetry/instrumentation-dns': { enabled: false },
    '@opentelemetry/instrumentation-net': { enabled: false },
  },
  metricExportIntervalMillis: 5_000,
});

구성 객체를 사용하면 아래에 설명된 원격 분석 내보내기의 다양한 측면을 세부적으로 제어할 수 있습니다.

credentials

google-auth 라이브러리의 JWTInput을 사용하여 사용자 인증 정보를 직접 지정할 수 있습니다.

샘플러

모든 트레이스를 내보내는 것이 실용적이지 않은 경우 OpenTelemetry에서는 트레이스 샘플링을 허용합니다.

사전 구성된 샘플러는 4가지가 있습니다.

autoInstrumentation 및 autoInstrumentationConfig

자동 계측을 사용 설정하면 OpenTelemetry가 코드를 수정하지 않고도 서드 파티 라이브러리에서 원격 분석 데이터를 캡처할 수 있습니다.

metricExportIntervalMillis

이 필드는 측정항목 내보내기 간격을 밀리초 단위로 지정합니다.

metricExportTimeoutMillis

이 필드는 측정항목 내보내기의 제한 시간(밀리초)을 지정합니다.

disableMetrics

트레이스와 로그는 계속 내보내면서 측정항목 내보내기를 사용 중지하는 재정의를 제공합니다.

disableTraces

측정항목과 로그는 계속 내보내면서 트레이스 내보내기를 사용 중지하는 재정의를 제공합니다.

disableLoggingIO

입력 및 출력 로그 수집을 사용 중지하는 재정의를 제공합니다.

forceDevExport

이 옵션을 사용하면 dev 환경 (예: 로컬)에서 실행할 때 Genkit가 원격 분석 및 로그 데이터를 내보내도록 강제합니다.

통합 테스트

플러그인을 구성할 때 forceDevExport: true를 사용하여 로컬 실행의 원격 분석 내보내기를 사용 설정합니다. Google Cloud 로그, 측정항목 또는 Trace Explorer로 이동하여 원격 분석을 확인합니다. 또는 Firebase AI Monitoring 대시보드 (비공개 미리보기)로 이동하여 AI 용어로 된 원격 분석 보기를 확인할 수 있습니다.