에이전트 트레이싱 (Agent tracing)은 실행 구조, 즉 어떤 단계가 실행되었는지, 어떤 도구 (tool)가 실패했는지, 어디서 재시도 (retry)가 발생했는지, 모델 호출에 시간이 얼마나 걸렸는지, 그리고 토큰 예산 (token budget)이 어떻게 변했는지를 보여주기 때문에 유용합니다.

가장 쉬운 구현 방법은 모든 프롬프트 (prompt), 인자 (argument), 결과 (result), 그리고 응답 (response)을 캡처하는 것입니다. 하지만 이는 관측성 시스템 (observability system)을 민감한 애플리케이션 데이터의 두 번째 복사본으로 만드는 가장 쉬운 방법이기도 합니다.

**메타데이터 전용 트레이싱 (Metadata-only tracing)**은 다른 접근 방식을 취합니다. 기본적으로 원시 페이로드 (raw payloads)를 저장하지 않고 에이전트의 동작을 기록합니다. 그 결과가 위험이 전혀 없는 텔레메트리 (telemetry)는 아니지만, 훨씬 더 작고 관리 가능한 데이터 표면 (data surface)을 제공합니다.

설계 목표

유용한 메타데이터 트레이스는 다음과 같은 운영 질문에 답할 수 있어야 합니다:

• 어떤 단계가 어떤 순서로 실행되었는가?
• 어떤 모델 및 도구 작업이 성공하거나 실패했는가?
• 지연 시간 (latency)이 어디에서 누적되었는가?
• 얼마나 많은 재시도 (retries)와 폴백 (fallbacks)이 발생했는가?
• 입력, 캐시된 입력 (cached-input), 그리고 출력 토큰이 얼마나 사용되었는가?
• 검색 (retrieval)이 결과를 반환했는가, 그리고 얼마나 많은 컨텍스트 (context)가 조립되었는가?
• 어떤 검증 (validation) 또는 정책 게이트 (policy gate)가 실행을 차단했는가?

별도의 캡처 정책이 명시적으로 허용하지 않는 한, 다음과 같은 질문에는 답하지 않아야 합니다:

• 사용자가 말한 내용은 토씨 하나 틀리지 않고 무엇인가?
• 전체 프롬프트 (prompt) 또는 모델 응답 (model response)은 무엇인가?
• 어떤 이메일 주소, 계좌 번호, 또는 인증 토큰 (authorization token)이 사용되었는가?
• 도구가 어떤 레코드나 문서를 반환했는가?

이러한 경계는 전체 충실도 캡처 (full-fidelity capture)를 기본값으로 설정하지 않으면서도 일상적인 트레이스를 유용하게 유지해 줍니다.

메타데이터 전용이 익명성을 의미하지는 않는다

메타데이터도 여전히 민감할 수 있습니다. 워크플로 이름, 세밀한 위치, 고유 식별자 (unique identifier), 결정 레이블 (decision label), 또는 드문 에러 카테고리는 개인을 식별하거나 기밀 비즈니스 활동을 드러낼 수 있습니다.

관련된 구분점은 "페이로드 (payload) 대 무해한 메타데이터"가 아닙니다. 그것은 **필요하고 분류된 메타데이터 (necessary, classified metadata) 대 무제한 콘텐츠 (unbounded content)**입니다. 모든 필드는 여전히 목적, 소유자, 그리고 보존 정책 (retention policy)이 필요합니다.

자유 형식의 메타데이터 뭉치(free-form metadata bags)를 피하십시오. Record<string, string | number>와 같은 타입은 값의 형태를 제한할 수는 있지만, 개발자가 email, prompt, 또는 accessToken을 추가하는 것을 막지는 못합니다.

작업(Operation)별 메타데이터 정의

작업별로 특화된 타입(Operation-specific types)을 사용하면 코드 리뷰 중에 의도된 스키마(schema)를 가시화할 수 있으며, 임의의 필드가 트레이스 시스템(trace system) 전체로 퍼지는 것을 방지할 수 있습니다.

type StepMetadata = {
  retrieval: {
    source: 'knowledge_base' | 'ticket_index';
...

제어된 어휘 집합(Controlled vocabularies)은 의도적인 설계입니다. 이는 대시보드를 안정적으로 만들고, 고카디널리티 (high-cardinality) 필드를 줄이며, 새로운 데이터 수집이 스키마 변경으로서 검토되도록 강제합니다.

모델 이름은 동적으로 유지될 수 있지만, 여전히 길이를 제한하고 정규화 (normalized)해야 합니다. 사용자가 제어하는 문자열을 이러한 필드에 그대로 복사해서는 안 됩니다.

작고 버전 관리되는 이벤트 엔벨로프 (Event Envelope) 사용

트레이스 엔벨로프 (trace envelope)는 애플리케이션 페이로드 (payload)를 운반하지 않으면서 부모-자식 관계 (parent-child relationships)를 지원해야 합니다.

type TraceStatus = 'ok' | 'error';

type StepCompleted<K extends StepKind = StepKind> = {
...

버전 관리는 중요합니다. 트레이스 아티팩트 (trace artifacts)는 종종 이를 생성한 코드보다 더 오래 유지되기 때문입니다. 버전 필드를 사용하면 읽는 이가 데이터의 형태를 추측하는 대신, 호환되지 않는 이벤트를 마이그레이션하거나 거부할 수 있습니다.

기본 이벤트에 가공되지 않은 에러 메시지나 스택 트레이스 (stack traces)를 포함하지 마십시오. 두 가지 모두 페이로드 조각, 파일 경로, 헤더 또는 쿼리 값을 포함하는 경우가 빈번합니다. 예외 (exceptions)를 제어된 카테고리로 매핑하고, 더 상세한 진단 정보는 제한된 캡처 모드 (restricted capture mode) 뒤에 유지하십시오.

TypeScript에서 부모-자식 컨텍스트 보존

AsyncLocalStorage를 사용하면 모든 함수 시그니처 (function signature)를 통해 전달하지 않고도 프로미스 체인 (promise chains)을 따라 트레이스 및 부모 스팬 (parent-span) 식별자를 전달할 수 있습니다. 아래의 트레이서 (tracer)는 완료 이벤트를 방출하며, 각 작업이 선언된 종류 (kind)와 일치하는 메타데이터를 반환하도록 요구합니다.

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

...

Sink(싱크)는 개발 중에 로컬 NDJSON 파일에 기록하거나, 승인된 이벤트를 관측성 (Observability) 백엔드로 내보낼 수 있습니다. 캡처 정책 (Capture policy)은 Sink 앞에 위치해야 하며, 그래야만 목적지를 변경하더라도 수집되는 데이터가 조용히 늘어나는 것을 방지할 수 있습니다.

콘텐츠를 캡처하지 않고 에이전트 계측하기

모델 및 검색 (Retrieval) 작업은 메모리 내에서 민감한 값을 사용할 수 있지만, 트레이서 (Tracer)에는 제한된 운영 메타데이터 (Operational metadata)만을 반환할 수 있습니다.

const answer = await runTrace(async () => {
  const documents = await traceStep(
    sink,
...

이 트레이스는 빈 검색 결과, 과도하게 큰 컨텍스트 (Context), 길이 제한이 걸린 응답, 또는 예상치 못하게 비용이 많이 드는 모델 호출 등을 드러낼 수 있습니다. 사용자 질문이나 문서 텍스트는 전혀 필요하지 않습니다.

유용한 트레이스의 모습

support_agent  1,184 ms  ok
├─ retrieve_support_docs   96 ms  ok
│  source=knowledge_base resultCount=5 contextTokens=0
...

트레이스가 문서를 노출하지 않더라도, 제로 토큰 (Zero-token) 검색 컨텍스트는 즉시 의심스러운 상황임을 알 수 있습니다. 메타데이터는 조사 범위를 좁혀줍니다. 개발자는 다른 방법으로 문제를 재현할 수 없는 경우, 해당 단계에 대해 선택적인 로컬 캡처를 활성화할 수 있습니다.

런타임 제한도 강제하기

TypeScript 타입은 런타임 (Runtime)에 사라지며, 트레이스 데이터는 JavaScript 어댑터나 외부 라이브러리에서 올 수 있습니다. 이벤트를 기록하기 전에 반드시 검증하십시오.

• 알 수 없는 키(Key) 및 지원되지 않는 스키마 (Schema) 버전을 거부합니다.
• 이름 및 기타 문자열의 길이를 작은 최대치로 제한합니다.
• 유한하고 음수가 아닌 숫자 값만을 요구합니다.
• 메타데이터 필드 수와 직렬화된 이벤트 크기를 제한합니다.
• 페이로드 (Payload), 자격 증명 (Credentials), 헤더 (Headers) 또는 자유 형식의 콘텐츠와 관련된 키를 거부합니다.
• 검증을 완료할 수 없는 경우 'Fail closed(실패 시 차단)' 방식으로 동작합니다.

스키마 검증 라이브러리를 통해 구조적 규칙을 강제할 수 있습니다. 하지만 작업별 빌더 (Operation-specific builders)가 여전히 주요 정책 경계로 유지되어야 합니다.

부정적 요구사항 (Negative Requirements) 테스트하기

개인정보 보호 요구사항은 종종 '절대로 나타나서는 안 되는 것'에 관한 것입니다. 이러한 기대 사항을 테스트 코드에 인코딩하십시오.

const forbiddenKeys = [
  'prompt',
  'response',
...

테스트용 피스처 (test fixtures)에 대표적인 비밀 정보와 개인 데이터를 추가하고, 에이전트를 실행한 뒤, 방출된 트레이스 (trace)에 해당 값들이 전혀 나타나지 않는지 확인(assert)하십시오. 이것이 광범위한 보안 검토를 대신할 수는 없지만, 계측 (instrumentation) 변경 시 발생하는 회귀 (regressions)를 잡아낼 수 있습니다.

메타데이터만으로는 부족한 시점

메타데이터 전용 트레이싱 (Metadata-only tracing)은 타이밍 (timing), 토폴로지 (topology), 재시도 (retries), 토큰 사용량 (token usage), 정책 결과 (policy outcomes), 그리고 광범위한 에러 국지화 (error localization)에 매우 탁월합니다. 하지만 모든 의미론적 실패 (semantic failure)를 설명할 수는 없습니다.

정확한 콘텐츠가 반드시 필요한 경우에는 다음과 같은 제약 사항을 가진 별도의 진단 모드 (diagnostic mode)를 사용하십시오:

• 특정 트레이스 (trace), 단계 (step), 또는 짧은 시간 범위에 대해서만 활성화하십시오.
• 캡처된 데이터를 로컬에 유지하거나 제한된 사고 대응 환경 (incident environment) 내에 두십시오.
• 전체 객체를 기록하는 대신 허용 목록 (allowlist) 필드만 사용하십시오.
• 결정론적 비식별화 (deterministic redaction) 및 비밀 정보 스캐닝 (secret scanning)을 적용하십시오.
• 강화된 캡처 기능이 활성화되어 있음을 표시하십시오.
• 짧은 보존 기간이 지나면 아티팩트 (artifact)를 자동으로 삭제하십시오.

에스컬레이션 (escalation) 경로가 명확해야 하지만, 반드시 의도적인 동작을 필요로 해야 합니다.

실용적인 기본 설정

버전 관리된 이벤트 엔벨로프 (event envelope), 작업별 메타데이터 타입 (operation-specific metadata types), 비동기 부모-자식 컨텍스트 (async parent-child context), 제어된 에러 카테고리 (controlled error categories), 그리고 런타임 검증 (runtime validation)으로 시작하십시오. 타이밍 (timing), 상태 (status), 토큰 사용량 (token usage), 카운트 (counts), 그리고 제한된 레이블 (bounded labels)을 저장하십시오. 프롬프트 (prompts), 출력 (outputs), 도구 페이로드 (tool payloads), 검색된 텍스트 (retrieved text), 헤더 (headers), 그리고 환경 변수 (environment values)는 기본 스키마 (default schema)에서 제외하십시오.

메타데이터 전용 트레이싱이 모든 디버깅 질문에 답을 주지는 않을 것입니다. 하지만 관측성 시스템 (observability system)이 보호해야 하는 민감한 데이터의 양을 실질적으로 줄이면서, 질문의 상당 부분에 대한 답을 제공할 것입니다.

다음 기사에서는 TypeScript 런타임 자체에 초점을 맞출 것입니다: 비동기 컨텍스트 전파 (async context propagation), 모듈 경계 (module boundaries), 서버리스 실행 (serverless execution), 그리고 트레이싱 도구가 깔끔하게 처리해야 하는 훅 (hooks)에 대해 다룹니다.