Confident OpenTelemetry 스킬

Confident OpenTelemetry 스킬 (Confident OpenTelemetry Skill)

에이전트에게 confident-trace 패키지 없이 어떤 언어에서든 원시 OpenTelemetry 트레이스를 Confident AI로 내보내는 법을 가르치는 스킬 문서예요. 이 문서에서는 스킬이 언제 발동하는지, 설치 방법, 코드베이스에서 바뀌는 것, 그리고 속성 규칙을 설명할게요.

출처: 문서

본문

개요 (Overview)

confident-otel Agent Skill은 코딩 에이전트에게 confident-trace 패키지 없이 AI 애플리케이션의 원시 OpenTelemetry 트레이스를 Confident AI로 내보내는 법을 가르쳐요. 계약(contract)이 OTLP exporter 엔드포인트와 각 스팬의 confident.* 속성이기 때문에 어떤 언어의 어떤 OpenTelemetry SDK에서도 작동해요.

이 스킬은 OTLP/HTTP traces exporter를 올바른 Confident AI 지역에 보내고, x-confident-api-key 헤더를 추가하고, 네이티브 OpenTelemetry 트레이스 컨텍스트를 보존하며, confident.span.*과 confident.trace.* 필드를 설정해요. 부모 관계(parentage), 트레이스 ID, 샘플링, 상태, 리소스, 링크, 전파(propagation)는 그대로 네이티브 OpenTelemetry의 몫으로 남겨요.

지역	기본 엔드포인트	직접 exporter 엔드포인트
US/AU	`https://otel.confident-ai.com`	`https://otel.confident-ai.com/v1/traces`
EU	`https://eu.otel.confident-ai.com`	`https://eu.otel.confident-ai.com/v1/traces`

confident_eu_... API 키만 EU 엔드포인트를 사용해요.

언제 발동하나요?

이 스킬은 다음과 같은 프롬프트에서 활성화돼요:

Send our OpenTelemetry AI traces to Confident AI.
Wire our OTel Collector to export agent spans to Confident AI.
Set confident.span.type on the LLM spans in our TypeScript service.
Which direct OTLP endpoint should our EU deployment use?

DeepEval 평가 스위트를 만들거나 confident-trace SDK로 애플리케이션을 계측하지는 않아요. 자동 통합과 커스텀 @span, span(), withSpan() 계측은 confident-tracing을 사용해요.

설치 (Installation)

Skills CLI

Cursor, Claude Code, Codex, Windsurf, OpenCode 등 Skills 호환 어시스턴트에서 작동해요:

npx skills add confident-ai/confident-trace --skill "confident-otel"

Claude Code (플러그인)

Confident Trace 플러그인은 confident-tracing과 confident-otel을 둘 다 번들해요:

/plugin marketplace add confident-ai/confident-trace
/plugin install confident-trace@confident-trace-plugins
/reload-plugins

수동 복사

스킬 폴더를 에이전트의 스킬 디렉토리에 복사해요:

git clone https://github.com/confident-ai/confident-trace
cp -r confident-trace/skills/confident-otel .claude/skills/

사전 조건 (Prerequisites)

프로젝트 범위 CONFIDENT_API_KEY
애플리케이션 언어용 OpenTelemetry SDK
Python의 경우 opentelemetry-sdk와 opentelemetry-exporter-otlp-proto-http

Confident AI의 직접 Cloud 엔드포인트는 gRPC가 아니라 OTLP/HTTP를 받아요. 애플리케이션은 자체 Collector에 gRPC로 보낼 수 있지만, Collector-to-Confident-AI 구간은 OTLP/HTTP를 사용해야 해요.

코드베이스에서 바뀌는 것

기존 OpenTelemetry 설정 검사

에이전트는 TracerProvider, 스팬 프로세서, exporter, Collector 설정, APM 계측을 확인해요. 애플리케이션의 provider를 보존하고, 중복 파이프라인을 추가하는 대신 기존 exporter를 다시 가리키는 걸 선호해요.

Send our OpenTelemetry AI traces to Confident AI.

직접 OTLP 내보내기 구성

에이전트는 지역 엔드포인트를 선택하고 x-confident-api-key 헤더를 구성해요. 표준 OpenTelemetry 환경 변수로 패키지별 SDK 없이 직접 exporter를 구성할 수 있어요:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.confident-ai.com"
export OTEL_EXPORTER_OTLP_HEADERS="x-confident-api-key=<CONFIDENT_API_KEY>"

Python 예시

import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://otel.confident-ai.com/v1/traces",
            headers={"x-confident-api-key": os.environ["CONFIDENT_API_KEY"]},
        )
    )
)
trace.set_tracer_provider(provider)

AI 스팬·트레이스 필드 설정

에이전트는 AI 구성 요소에 confident.span.* 필드를, 전체 트레이스에 confident.trace.* 필드를 설정해요. 객체와 메타데이터는 JSON으로 인코딩하고, 목록은 네이티브 문자열 배열을 쓰며, 네이티브 OpenTelemetry 부모-자식 컨텍스트를 보존해요.

원시 OpenTelemetry 예시

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("support-agent") as root:
    root.set_attribute("confident.span.type", "agent")
    root.set_attribute("confident.trace.name", "support-chat")

    with tracer.start_as_current_span("chat-completion") as llm:
        llm.set_attribute("confident.span.type", "llm")
        llm.set_attribute("confident.llm.model", "gpt-4o")

비-AI 스팬 빼기

프로세스가 HTTP, 데이터베이스, 캐시, 인프라 스팬도 내보낸다면, 에이전트는 전용 AI provider를 사용하거나 Confident AI로 향하는 프로세서·exporter를 필터링해요. 중간 스팬을 제거할 때 부모 관계는 보존해요.

플러시와 검증

provider를 소유하는 구성 요소가 종료(shutdown)도 소유해요. 에이전트는 진행 중인 작업과 스트림을 마치고, provider를 플러시하거나 종료한 뒤 Confident AI에서 AI 트레이스 계층을 검증해요.

속성 규칙 (Attribute Rules)

원시 스팬 유형은 llm, tool, agent, retriever, base예요.
알려졌을 때 confident.span.type을 명시적으로 설정해요.
트레이스 전반의 입력, 출력, 태그, 메타데이터, 환경, 사용자 ID, 고객 ID, 스레드 ID, 턴 ID, 지표 컬렉션은 confident.trace.*에 둬요.
구조화된 사용자·고객 필드는 점(dotted) 속성(confident.trace.user.id, confident.trace.user.name, confident.trace.customer.id, confident.trace.customer.name)으로 설정하고, 각 구조화 ID를 축약된 *_id 별칭과 짝지어요.
구성 요소 입력, 출력, 메타데이터, 검색 컨텍스트, 기대 출력, 도구, 지표 컬렉션은 confident.span.*에 둬요.
오류는 네이티브 OpenTelemetry 상태와 예외 기록을 사용해요.
기존 gen_ai.* 속성은 모델, 토큰 수, 도구 이름, 기본 스팬 유형 추론의 폴백이 될 수 있어요.

자주 묻는 질문 (FAQs)

confident-trace 패키지가 설치되어야 하나요?

아니요. confident-otel은 원시 OpenTelemetry 내보내기를 위한 언어 중립 경로예요. Python 또는 TypeScript SDK와 그 통합을 원한다면 confident-tracing을 사용해요.

gRPC로 직접 내보낼 수 있나요?

아니요. Confident AI의 직접 Cloud 엔드포인트는 OTLP/HTTP를 받아요. 애플리케이션은 자체 Collector가 OTLP/HTTP로 Confident AI에 내보내는 한, gRPC를 자체 Collector에 보낼 수는 있어요.

이미 APM 에이전트를 운영 중인데 모든 스팬이 보내지나요?

파이프라인이 올바르게 구성되면 아니에요. 이 스킬은 전용 provider를 사용하거나 Confident AI로 향하는 프로세서·exporter를 필터링해서 AI 스팬만 보내요.

내 앱이 이미 gen_ai.* 필드를 내보내는데 confident.*도 필요한가요?

Confident AI는 모델, 토큰 수, 도구 이름, 기본 유형 추론에 표준 gen_ai.* 필드로 폴백할 수 있어요. 둘 다 있으면 명시적 confident.* 필드가 우선해요.

Confident OpenTelemetry 스킬