OpenTelemetry를 사용하여 LangGraph ReAct 에이전트 계측

프리뷰

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 OpenTelemetry로 LangGraph ReAct 에이전트를 계측하여 에이전트에서 원격 분석을 수집하는 단계를 설명합니다. 사용자 프롬프트와 에이전트 응답 및 선택사항은 스팬에 연결된 속성으로 원격 분석에 포함됩니다. 에이전트 응답도 생성형 AI 이벤트가 포함된 스팬과 상관관계가 있는 로그 항목에 포함됩니다. 이 문서의 안내는 에이전트가 Langchain의 ChatVertexAI를 사용하여 Gemini 모델을 호출하는 경우에 적용됩니다.

생성형 AI 애플리케이션을 계측하여 원격 분석 수집

로그, 측정항목, trace 데이터를 수집하도록 생성형 AI 애플리케이션을 계측하려면 다음을 수행합니다.

1. OpenTelemetry 패키지 설치
2. 원격 분석을 수집하고 전송하도록 OpenTelemetry 구성
3. 생성형 AI 에이전트 호출 추적

OpenTelemetry 패키지 설치

다음 OpenTelemetry 계측 및 내보내기 도구 패키지를 추가합니다.

pip install 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc'

로그 및 측정항목 데이터는 Cloud Logging API 또는 Cloud Monitoring API를 사용하여 Google Cloud 프로젝트로 전송됩니다. opentelemetry-exporter-gcp-logging 및 opentelemetry-exporter-gcp-monitoring 라이브러리는 이러한 API의 엔드포인트를 호출합니다.

trace 데이터는 OTLP 형식을 지원하는 Telemetry (OTLP) API를 사용하여 Google Cloud 로 전송됩니다. 이 엔드포인트를 통해 수신된 데이터도 OTLP 형식으로 저장됩니다. opentelemetry-exporter-otlp-proto-grpc 라이브러리는 Telemetry (OTLP) API 엔드포인트를 호출합니다.

원격 분석을 수집하고 전송하도록 OpenTelemetry 구성

LangGraph 에이전트의 초기화 코드 내에서 OpenTelemetry를 구성하여 원격 분석을 캡처하고 Google Cloud 프로젝트로 전송합니다.

전체 샘플을 보려면 더보기를 클릭한 다음 GitHub에서 보기를 선택합니다.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    VertexAIInstrumentor().instrument()

생성형 AI 에이전트 호출 추적

LangGraph 에이전트 호출의 실행을 추적하려면 에이전트 호출 주위에 커스텀 스팬을 만듭니다.

전체 샘플을 보려면 더보기를 클릭한 다음 GitHub에서 보기를 선택합니다.

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

애플리케이션 코드의 주요 위치에 이전 코드를 포함하는 것이 좋습니다.

커스텀 스팬 및 측정항목 추가에 대해 자세히 알아보려면 앱에 커스텀 trace 및 측정항목 추가를 참조하세요.

샘플 실행

이 샘플은 생성형 AI 프롬프트 및 응답과 함께 trace 및 로그를 전송하고 측정항목을Google Cloud 프로젝트로 전송하도록 OpenTelemetry로 계측된 LangGraph 에이전트입니다.

LangGraph 에이전트 페르소나

LangGraph 에이전트는 임시 SQLite 데이터베이스에 대한 전체 액세스 권한이 있는 SQL 전문가로 정의됩니다. 에이전트는 LangGraph 사전 빌드된 ReAct 에이전트로 구현되며 SQLDatabaseToolkit을 사용하여 처음에는 비어 있는 데이터베이스에 액세스합니다.

시작하기 전에

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

   gcloud services enable aiplatform.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

3. 샘플 애플리케이션에서 로그, 측정항목, trace 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

   • Cloud 원격 분석 trace 작성자(roles/telemetry.tracesWriter)
   • 로그 작성자(roles/logging.logWriter)
   • 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
   • Vertex AI 사용자(roles/aiplatform.user)

Run 샘플

샘플을 실행하려면 다음을 수행합니다.

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 저장소를 복제합니다.

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git
   

3. 샘플 디렉터리로 이동합니다.

   cd opentelemetry-operations-python/samples/langgraph-sql-agent
   

4. 환경 변수를 구성합니다.

   # Capture GenAI prompts and responses
   export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
   # Capture application logs automatically
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
   

5. 가상 환경을 만들고 샘플을 실행합니다.

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   python main.py
   

   애플리케이션에 다음과 유사한 메시지가 표시됩니다.

   Starting agent using ephemeral SQLite DB.
   

6. 데이터베이스를 만들려면 SQL 에이전트와 대화 >> 프롬프트에 값을 입력한 다음 Enter를 누릅니다.

   그러면 에이전트가 수행한 작업이 Cloud Shell에 표시됩니다.

   다음은 사용자와 애플리케이션 간의 샘플 상호작용을 보여줍니다.

   Talk to the SQL agent >> Create a new table to hold weather data.
   👤 User: Create a new table to hold weather data.
   🤖 Agent: I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation.
   
   Talk to the SQL agent >> Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
   👤 User: Create a new table to hold weather data. Include date, location, temperature, humidity, and precipitation.
   🤖 Agent
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   

7. 종료하려면 Ctrl-C를 입력합니다.

생성형 AI 에이전트가 수행하는 작업은 확정적이지 않으므로 동일한 프롬프트에 다른 응답이 표시될 수 있습니다.

trace, 측정항목, 로그 보기

이 섹션에서는 생성형 AI 이벤트를 보는 방법을 설명합니다.

시작하기 전에

로그, 측정항목, trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• 로그 뷰어(roles/logging.viewer)
• 모니터링 뷰어(roles/monitoring.viewer)
• Cloud Trace 사용자(roles/cloudtrace.user)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

원격 분석 보기

생성형 AI 이벤트를 보려면 Trace 탐색기 페이지를 사용합니다.

1. Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.

   Trace 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

2. 툴바에서 필터 추가를 선택하고 스팬 이름을 선택한 다음 invoke agent를 선택합니다.

   샘플 실행 섹션에는 애플리케이션에 두 개의 프롬프트가 전송되는 실행 예시가 포함되어 있습니다. 다음은 데이터를 필터링한 후의 Trace 탐색기 페이지를 보여줍니다.

   

   Cloud Trace를 사용한 적이 없는 경우 Google Cloud Observability에서 trace 데이터를 저장할 데이터베이스를 만들어야 합니다. 데이터베이스를 만드는 데 몇 분 정도 걸릴 수 있으며 이 기간에는 trace 데이터를 볼 수 없습니다.

3. 스팬 및 로그 데이터를 탐색하려면 스팬 테이블에서 스팬을 선택합니다.

   세부정보 페이지가 열립니다. 이 페이지에는 연결된 trace와 그 스팬이 표시됩니다. 페이지의 테이블에는 선택한 스팬에 대한 세부정보가 표시됩니다. 이 정보에는 다음이 포함됩니다.

   • 생성형 AI 탭에는 생성형 AI 에이전트의 이벤트가 표시됩니다. 이러한 이벤트에 대해 자세히 알아보려면 생성형 AI 이벤트 보기를 참조하세요.

     다음 스크린샷은 하나의 스팬에 invoke_agent라는 이름이 있는 trace를 보여줍니다. 이 스팬은 Gemini를 호출합니다. Gemini 스팬에는 생성형 AI 이벤트가 포함됩니다.

     

   • 로그 및 이벤트 탭에는 스팬과 연결된 로그 항목과 이벤트가 나열됩니다. 로그 탐색기에서 로그 데이터를 보려면 이 탭의 툴바에서 로그 보기를 선택합니다.

     로그 데이터에는 LangGraph 에이전트의 응답이 포함됩니다. 예를 들어 샘플 실행의 경우 JSON 페이로드에는 다음 콘텐츠가 포함됩니다.

     {
       logName: "projects/my-project/logs/otel_python_inprocess_log_name_temp"
       jsonPayload: {
         finish_reason: "stop"
         message: {
           role: "model"
           content: [
             0: {
               text: "I need to know what columns the table should have. What information about the weather do you want to store? For example, I could include columns for date, location, temperature, humidity, and precipitation."
             }
           ]
         }
       index: 0
       }
     ...
     }
     

현재 샘플은 측정항목 데이터를 Google Cloud 프로젝트로 전송하도록 계측되어 있지만 측정항목을 생성하지는 않습니다.