OpenTelemetry GenAI 추적을 결과 이벤트에 연결
OpenTelemetry 추적 및 Telemetry 구조화된 이벤트는 AI 에이전트 조사의 다양한 부분을 해결합니다. OTLP 호환 옵저버빌리티 백엔드에서 상세한 모델, 에이전트 및 도구 범위를 유지하세요. 성공, 비용, 대기 시간, 릴리스, 계정, 핸드오프 또는 검토된 제품 가치에 대해 검사 가능한 SQL을 원할 경우 더 작은 터미널 결과 이벤트를 Telemetry로 보냅니다.
Telemetry는 OTLP 엔드포인트를 노출하지 않으며 OpenTelemetry 추적 백엔드가 아닙니다. 연결은 모든 범위의 두 번째 내보내기가 아닌 애플리케이션 소유 상관 식별자입니다.
의도한 작업에 맞게 각 시스템을 사용하십시오.
OpenTelemetry 추적은 다음 응답에 매우 적합합니다.
- 어떤 범위 또는 도구가 하나의 느린 실행을 지배했는지;
- 에이전트, 모델, 검색 및 도구 작업 간에 제어가 이동되는 방식
- 어떤 예외 또는 종속성이 개별 실패를 설명하는지,
- 승인된 추적 유지 경계 내에 어떤 세부 속성이 존재했는지.
간략한 결과 이벤트는 다음과 같은 답변에 매우 적합합니다.
- 어떤 릴리스가 가장 높은 터미널 작업 성공률을 가지고 있는지;
- 승인된 결과당 비용이 가장 많이 드는 작업 흐름은 무엇입니까?
- 이번 주에 도구 재시도 또는 사람의 전달이 증가했는지 여부
- 제한된 오류 범주의 영향을 받은 고객 계층
- 프롬프트 또는 모델 버전 이후 평가 점수가 변경되었는지 여부.
모든 범위 속성을 이벤트에 복사하지 마십시오. 내구성 있는 열이 필요한 집계 질문을 결정하고 해당 필드를 허용 목록에 추가하세요.
의도적으로 의미 체계 매핑
OpenTelemetry 생성 AI 의미 체계는 모델, 에이전트 및 도구 작업에 대한 진화하는 속성과 범위 규칙을 정의합니다. 서비스에서 사용하는 의미 체계 및 계측 라이브러리 버전을 고정한 다음 업그레이드 중에 매핑을 검토하세요.
| OpenTelemetry 컨셉 | Telemetry 이벤트 필드 | 안내 |
|---|---|---|
| 활성 범위 추적 ID | trace_id |
승인되면 안전한 상관관계 포인터; 계정 ID로 사용하지 마세요 |
| 애플리케이션 실행 또는 작업 ID | run_id 또는 operation_id |
재시도 및 이후 검토 시 조인을 위해 애플리케이션 식별자를 선호합니다. |
gen_ai.operation.name |
operation_name |
제한된 작업 범주 유지 |
gen_ai.provider.name |
provider |
고정된 계측에서 내보낸 공급자 값을 사용합니다. |
| 요청 또는 응답 모델 | model |
하나의 의미를 선택하여 문서화하거나 requested_model 및 response_model를 별도로 보관하세요. |
| 입력 및 출력 사용법 | input_tokens, output_tokens |
숫자 사용량을 한 번만 기록하세요. 추론 토큰 세부정보를 이중으로 계산하지 마세요. |
| 에이전트 신원 | agent_name 또는 agent_version |
생성된 인스턴스 식별자 대신 안정적인 논리적 이름을 사용하세요. |
| 범위 상태 또는 예외 | status, error_type |
제한되지 않은 메시지를 허용 목록에 있는 애플리케이션 카테고리로 변환 |
의미론적 규칙은 성숙해지면서 변경될 수 있습니다. 하나의 SDK 또는 프레임워크에서 관찰된 속성이 모든 곳에서 동일한 안정성이나 가용성을 가지고 있다고 가정하지 마십시오. 버전이 지정된 애플리케이션 코드로 정확한 매핑을 처리합니다.
추적 옆에 하나의 최종 결과를 내보냅니다.
이 JavaScript 래퍼는 현재 추적 ID를 읽고 에이전트 실행 후 애플리케이션 결과를 기록합니다. 추적은 구성된 OpenTelemetry SDK에 의해 계속 내보내집니다. 선택한 필드만 Telemetry로 이동합니다.
import { trace } from "@opentelemetry/api";
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
export async function runSupportAgent({
agent,
input,
operationId,
accountId,
release,
}) {
const startedAt = Date.now();
let status = "success";
let errorType;
let result;
try {
result = await agent.run(input);
return result;
} catch (error) {
status = "failed";
errorType = classifyAgentError(error);
throw error;
} finally {
const activeSpan = trace.getActiveSpan();
const traceId = activeSpan?.spanContext().traceId;
await telemetry.log("agent_run_completed", {
operation_id: operationId,
trace_id: traceId,
workflow: "support_resolution",
account_id: accountId,
status,
error_type: errorType,
duration_ms: Date.now() - startedAt,
human_handoff: result?.handoffRequired ?? false,
tool_call_count: result?.toolCallCount ?? 0,
release,
});
}
}
비즈니스 작업 흐름에서 명시적으로 달리 요구하지 않는 한 이벤트 전달 실패를 치명적이지 않게 만듭니다. 일괄 처리, 배압 및 종료의 짧은 시간 초과, 제한된 재시도, 우아한 종료 및 전달 지침을 사용하세요.
모델 사용을 한 번만 추가하세요.
OpenTelemetry 계측이 이미 공급자 요청을 관찰하는 경우 Telemetry에 요청 사용량이 자동으로 포함되지 않습니다. 집계된 SQL 질문에 별도의 llm_request_completed 이벤트가 필요한지 여부를 결정합니다.
그렇다면 다음을 사용하여 청구 가능한 요청당 하나의 이벤트를 내보냅니다.
operation_id,run_id및 선택적으로 승인된trace_id;provider,requested_model,response_model및service_tier;- 입력, 캐시된 입력, 출력 및 기타 별도로 정의된 토큰 범주;
estimated_cost_usd및 버전별 가격 소스latency_ms,status,attempt,feature및release.
기간에서 비용을 파생하지 마십시오. 공급자가 보고한 사용량과 검토된 요금표를 사용한 다음 공급자 송장에 대한 추정치를 조정합니다. OpenAI 요청 비용 가이드에 해당 패턴이 나와 있습니다.
데이터 경계를 보호하세요
생성적 AI 텔레메트리에는 비정상적으로 민감한 데이터가 포함될 수 있습니다. 기본적으로 다음 필드를 Telemetry로 보내지 마십시오.
- 프롬프트 또는 완료 콘텐츠;
- 시스템 지침 또는 일련의 사고 내용;
- 검색된 문서 텍스트 또는 임베딩
- 도구 인수, 도구 응답, 셸 출력 또는 파일 내용
- 인증 헤더, 쿠키, API 키, 데이터베이스 자격 증명 또는 연결 문자열
- 무제한 예외 메시지 또는 OpenTelemetry 수하물;
- 제품의 수집 및 보유 심사를 통과하지 못한 개인정보
input_category, output_category, tool_name, error_type, policy_result 및 review_outcome와 같은 카테고리를 선호합니다. 수출업체에 전화하기 전에 허용 목록을 적용하세요. 대시보드에서 필드를 제거해도 저장된 데이터에서는 제거되지 않습니다.
결과 쿼리 및 추적 링크 보존
상관관계 포인터 응답자에게 필요한 사항을 유지하면서 집계 비교를 위해 SQL을 사용하세요.
SELECT
release,
workflow,
COUNT(*) AS completed_runs,
SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS successful_runs,
SUM(CASE WHEN human_handoff THEN 1 ELSE 0 END) AS handoffs,
ROUND(AVG(duration_ms), 0) AS average_duration_ms,
MAX(trace_id) AS example_trace_id
FROM agent_run_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release, workflow
ORDER BY completed_runs DESC;
MAX(trace_id)는 대표 트레이스가 아닌 그룹의 예시 포인터일 뿐입니다. 조사를 위해 기본 행을 열고 관련 실행을 선택한 다음 해당 trace_id를 추적 백엔드에 붙여넣습니다. 해당 백엔드가 안정적인 URL 템플릿을 지원하는 경우 공급업체 자격 증명이나 개인 호스트 이름을 이벤트 필드로 보내는 대신 액세스가 제어되는 내부 도구에서 링크를 구축하세요.
연결 확인
프로덕션 출시 전:
- 성공적인 실행 1회, 도구 실패 1회, 복구된 재시도 1회, 터미널 실패 1회를 생성합니다.
- 추적 백엔드에 예상되는 스팬 트리가 포함되어 있는지 확인하세요.
- Telemetry에 실행당 하나의 터미널 이벤트와 의도된 요청 또는 도구 이벤트가 포함되어 있는지 확인하세요.
- 추적 및 이벤트 상관 관계 식별자를 비교합니다.
- 프롬프트, 완성, 인수, 자격 증명 및 비공개 콘텐츠가 없는지 확인하세요.
- 내보내기가 느리거나 사용할 수 없을 때 동작을 테스트합니다.
- 문서 소유자, 보존, 의미 규칙 버전, 샘플링 및 조사 전달.
일반 아키텍처 및 SDK 예를 보려면 Telemetry 및 OpenTelemetry를 읽어보세요. 에이전트별 결과 설계를 위해서는 SQL로 AI 에이전트 평가 및 AI 에이전트 모니터링 제품 경계를 계속 진행하세요.