Agent 모니터링 애플리케이션 생성¶
Agent 애플리케이션이나 프레임워크를 연동하면 Agent 모니터링에서 호출 체인, 모델 사용 현황 및 관련 성능 데이터를 확인할 수 있습니다. 연동 방식은 유형에 따라 다릅니다.
- Agent 모니터링 > 요약으로 이동합니다.
- Agent 탭을 선택합니다.
- Agent 연동을 클릭하여 연동 구성 페이지를 엽니다.
Agent 유형¶
Agent 모니터링에서 지원하는 유형은 다음과 같습니다.
| 분류 | Agent 유형 | 연동 방식 |
|---|---|---|
| Agent 애플리케이션 | Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, DeepSeek Harness, Opm, mimo, pi, Qwen Work(데스크톱) | obs-agent-connector 설치 프로그램으로 연동 |
| Agent 프레임워크 | AgentScope, Spring AI Alibaba, Deep Agents | OpenTelemetry로 수동 연동. Deep Agents 예시는 연동 단계 참조 |
설치 프로그램으로 연동¶
Codex, Claude Code, OpenClaw, Hermes, Qoder, WorkBuddy, OpenCode, CodeBuddy, Cursor, Opm, DeepSeek Harness, mimo, pi 및 Qwen Work(데스크톱)은 obs-agent-connector 설치 프로그램으로 연동하며, 커넥터는 한 번만 설치하면 됩니다. 연동 전에 먼저 모니터링할 Agent를 설치하고 obs-agent-connector agents 명령어로 현재 커넥터가 해당 유형과 운영 체제를 지원하는지 확인하세요.
1단계: Agent 유형 선택¶
연동 구성 페이지에서 연동할 분류와 Agent 유형을 선택합니다.
2단계: User ID 구성¶
연동 구성에서 현재 워크스페이스 구성원의 개인 정보 연동 여부를 선택할 수 있습니다.
- 기본적으로 '워크스페이스 개인 정보 연동'이 체크되어 있습니다. 시스템이 구성원 이름 등의 개인 정보를 업로드하며, 구성원 UUID를
user_id로, 사용자 이름을 user_name으로 사용합니다. - 체크하지 않으면 시스템이 무작위 ID를 생성하여
user_id로 사용하며, user_name은 직접 입력해야 합니다. user_id는 User 데이터의 집계, 필터링 및 드릴다운에 사용됩니다.user_name은 표시와 검색에만 사용되며 User의 고유 식별자로 사용되지 않습니다.- 동일한 Connector로 연동한 여러 Agent 유형은 동일한
user_id를 공유합니다.
익명 user_id는 Connector를 재시작하거나 업그레이드하거나 플러그인을 업데이트한 후에도 유지됩니다. ID 구성을 완전히 삭제하거나 ID를 직접 재설정하는 경우에만 시스템이 새로운 익명 ID를 생성합니다.
3단계: 커넥터 설치¶
Agent가 설치된 호스트의 운영 체제에 따라 해당 명령어를 실행합니다.
설치가 완료된 후 현재 터미널에서 obs-agent-connector 명령어가 인식되지 않으면 터미널을 다시 연 다음 후속 작업을 진행하세요.
4단계: 플러그인 설치¶
다음 명령어를 실행하면 현재 환경의 Agent를 자동으로 검색하여 연동을 완료합니다.
플러그인 업데이트 또는 제거¶
플러그인 업데이트:
플러그인 제거:
추가 명령어
지원되는 Agent, 자주 사용하는 명령어, 설치 파라미터 및 사용 예시는 obs-agent-connector 명령어 참조를 참조하세요.
AgentScope 수동 연동¶
AgentScope는 obs-agent-connector를 사용하지 않으며 OpenTelemetry를 통해 수동으로 연동해야 합니다. 언어별 연동 방식은 약간 다르며, 여기서는 Java를 예로 설명합니다.
1단계: AgentScope 선택¶
연동 구성 페이지에서 AgentScope를 선택한 다음 인스턴스 이름을 입력합니다. 인스턴스 이름은 중국어, 영어, 숫자, 밑줄 및 하이픈을 지원하며 동일한 Agent 유형 내에서 고유해야 합니다.
2단계: OpenTelemetry 활성화¶
AgentScope 공식 문서를 참조하여 AgentScope 코드에서 TelemetryTracer를 등록합니다.
import io.agentscope.core.tracing.TraceRegistry;
import io.agentscope.core.tracing.telemetry.TelemetryTracer;
TraceRegistry.register(
TelemetryTracer.builder()
.build()
);
ReActAgent agent = ReActAgent.builder()
.name("Assistant")
.model(model)
.build();
3단계: 환경 변수 구성¶
연동 구성 페이지는 현재 인스턴스를 기준으로 Endpoint, X-Token, Agent ID 및 Agent Name을 생성합니다. 페이지에서 생성된 실제 값을 복사하여 다음 환경 변수를 구성하세요.
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<Endpoint>/v1/write/otel-llm"
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="<Endpoint>/v1/write/otel-metrics"
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="<Endpoint>/v1/write/otel-logs"
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.0.0,deployment.environment=production,agent_id=<Agent ID>,agent_name=<Agent Name>,agent_runtime=agentscope"
export OTEL_EXPORTER_OTLP_HEADERS="X-token=<X-Token>,to-headless=true"
4단계: 연동 검증¶
AgentScope 애플리케이션을 재시작하고 테스트 요청을 한 번 보낸 다음 Agent 모니터링에서 Trace 및 Metrics 데이터가 생성되었는지 확인합니다. 데이터가 없으면 Endpoint, X-Token, Agent ID 및 OpenTelemetry 환경 변수가 올바르게 적용되었는지 중점적으로 확인하세요.
Deep Agents 수동 연동¶
Deep Agents는 OpenTelemetry를 통해 호출 체인을 전송하며 런타임 식별자는 langchain입니다. 아래 구성은 OpenTelemetry 분산 추적 수집을 활성화한 Python 애플리케이션에 적용되며, Agent, 모델, 도구 및 하위 에이전트의 호출 과정을 전송합니다.
1단계: 인스턴스 생성¶
연동 구성 페이지로 이동하여 Agent 프레임워크에서 Deep Agents를 선택하고 인스턴스 이름과 User ID 정보를 입력합니다. 페이지에서 생성된 Endpoint, X-Token, Agent ID, Agent Name, User ID 및 User Name을 복사하여 후속 구성에 사용합니다.
2단계: OpenTelemetry 구성¶
애플리케이션을 시작하는 터미널에서 다음 구성을 실행합니다(macOS/Linux 기준). 꺾쇠괄호 안의 플레이스홀더 내용을 1단계 페이지에서 생성된 실제 값으로 바꾸세요. Endpoint는 페이지에서 제공하는 기본 주소를 사용하며 /v1/write/otel-llm을 중복으로 추가하지 않습니다.
export OTEL_SERVICE_NAME="langchain-deep-agent"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export TRACELOOP_TRACE_CONTENT=false
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<Endpoint>/v1/write/otel-llm"
export OTEL_RESOURCE_ATTRIBUTES="agent_id=<Agent ID>,agent_name=<Agent Name>,user_id=<User ID>,user_name=<User Name>,agent_runtime=langchain"
export OTEL_EXPORTER_OTLP_HEADERS="X-token=<X-Token>,to-headless=true"
이 예시는 Trace만 전송하며 Metrics와 Logs 내보내기는 비활성화합니다. 입력·출력 본문은 기본적으로 수집되지 않습니다. 본문을 확인하려면 데이터 수집 범위를 확인한 후 TRACELOOP_TRACE_CONTENT를 true로 설정하고 새 호출 기록을 생성하세요. 구성을 변경해도 기존 Trace의 본문은 추가로 기록되지 않습니다.
3단계: 시작 및 검증¶
애플리케이션 자체의 시작 명령어로 Deep Agents 애플리케이션을 시작하거나 재시작하여 프로세스가 위 환경 변수를 로드하도록 하고 테스트 호출을 한 번 실행합니다.
호출을 한 번 완료한 후 Agent 모니터링의 Deep Agents 유형 페이지로 이동하여 해당 인스턴스를 선택하고 새로 생성된 Trace를 확인합니다. agent_id 또는 서비스 이름으로 찾아 호출 계층과 모델·도구 호출 정보를 확인할 수 있습니다.
데이터가 없으면 먼저 모델 요청이 성공했는지 확인한 다음 Endpoint, X-Token, 프로토콜 및 네트워크 연결을 확인하세요. Token 등 필드 표시 여부는 실제 수집된 데이터에 따라 달라집니다. 본문 수집을 비활성화한 상태에서는 입력·출력 본문이 비어 있다고 해서 분산 추적 전송이 실패한 것으로 판단해서는 안 됩니다.