OTTL이란? Collector 텔레메트리 변환 문법과 예제

OTTL의 변환문, 경로, 컨텍스트를 설명하고 Collector에서 기존 상태 매핑을 수정하거나 속성을 제거하고 추출하는 방법을 보여 줍니다.

모범 사례
애플리케이션 성능 모니터링의 서비스 트레이스와 메트릭을 보여 주는 그림

계측 라이브러리를 바꾼 뒤 요청은 예전과 똑같이 처리되는데 대시보드의 오류 수만 달라질 수 있습니다. 이전 라이브러리가 모든 404를 오류로 표시했다 해도, 모든 404 스팬을 한꺼번에 고치면 클라이언트에서 실제로 실패한 요청까지 가릴 수 있습니다. 어느 스팬을 바꾸는지, 어떤 이유로 그 상태가 붙었는지부터 확인해야 합니다.

OTTL(OpenTelemetry Transformation Language)은 Collector가 텔레메트리를 검사하고 처리할 때 쓰는 언어입니다. transform processor는 필드를 바꾸고, filter processor는 OTTL 조건에 맞는 데이터를 버릴 수 있습니다. 둘 다 Collector 내부의 구조화된 데이터를 대상으로 합니다.

OTTL 핵심 정리

  • 변환문은 편집 함수를 호출하고, 필요하면 where 조건을 붙입니다.
  • span.attributes["http.request.method"]나 span.status.code 같은 경로는 컨텍스트 안의 필드를 가리킵니다.
  • 속성 이름 변경, 필드 삭제, 값 추출, 조건부 업데이트에 쓸 수 있습니다.
  • 처리 단계를 옮길 때는 필드와 값의 타입, 실패했을 때의 동작을 각각 비교합니다.

OTTL이 필요한 경우

백엔드로 보내기 전에 수집된 헤더를 제거하거나, 예전 속성 이름을 시맨틱 규약(영어)에 맞추는 경우가 있습니다. 상태가 잘못 붙은 원인을 확실히 안다면 그 값도 고칠 수 있습니다. OTTL을 쓰면 이런 작업을 Collector 설정에 표현할 수 있습니다. HTTP 상태 코드가 http.status_code로 들어오는지, http.response.status_code로 들어오는지는 계측 버전에 따라 다릅니다. 이름을 바꾸기 전에 서비스가 실제로 보내는 필드부터 확인합니다.

파이프라인 안의 데이터

트레이스에는 스팬과 스팬 이벤트, 메트릭에는 데이터 포인트, 로그에는 레코드가 있습니다. 컨텍스트는 무엇을 처리하고 어떤 경로에 접근할 수 있는지 정합니다. 스팬 컨텍스트에서는 현재 스팬과 리소스 속성에 접근할 수 있습니다. 리소스 속성은 공유되므로 값을 바꾸면 같은 리소스에 속한 다른 레코드에도 영향이 갈 수 있습니다.

OTTL 문법 읽기

변환문

변환문은 편집 함수 하나를 호출하고, 필요할 때 where 절을 덧붙입니다. 같은 그룹의 문은 순서대로 실행됩니다. 아래는 Collector Contrib v0.162.0의 스팬 컨텍스트를 사용하는 예입니다.

set(span.attributes["app.http.response_class"], "2xx") where IsInt(span.attributes["http.response.status_code"]) and span.attributes["http.response.status_code"] >= 200 and span.attributes["http.response.status_code"] < 300
delete_key(span.attributes, "http.request.header.authorization")

식과 리터럴

불리언, 숫자, 문자열 리터럴과 ==, != 같은 비교 연산자, and, or를 사용할 수 있습니다. 열거값은 컨텍스트에 따라 달라집니다. 예를 들어 스팬에서 STATUS_CODE_UNSET을 쓸 수 있습니다. 속성의 타입이 일정하지 않다면 숫자로 비교하기 전에 IsInt로 확인합니다.

경로와 컨텍스트

span.attributes["key"]는 현재 스팬의 속성, resource.attributes["service.name"]는 리소스 속성을 가리킵니다. span.name과 span.status.code는 스팬의 기본 필드입니다. transform processor는 접두사가 있는 경로에서 컨텍스트를 추론할 수 있고, 그룹의 context로 직접 지정할 수도 있습니다. 경로, 함수, 열거값은 선택한 컨텍스트에서 사용할 수 있는 것이어야 합니다.

조건

where가 참일 때만 해당 문을 실행합니다. 그룹 전체에는 conditions로 공통 조건을 지정할 수 있습니다. 목록에 여러 조건을 두면 OR로 결합됩니다. 모두 충족해야 하는 조건은 한 식에 두고 and로 연결합니다.

HTTP 스팬 변환 예시

첫 번째 그룹은 원인이 확인된 오래된 상태 매핑을 고칩니다. 예시의 app.legacy_http_status_error는 서버가 4xx를 반환했다는 이유만으로 기존 규칙이 Error를 설정했다고 상위 단계에서 확인했을 때 표시하는 속성입니다. 이 약속이 있는 파이프라인에서만 첫 그룹을 활성화합니다. HTTP 시맨틱 규약에 따르면 계측에 추가 정보가 없을 때 서버 측 4xx 스팬 상태는 Unset으로 두며, 클라이언트 측 4xx는 Error로 설정하는 것이 권장됩니다. HTTP 스팬 상태 규약(영어)

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - context: span
        conditions:
          - >-
            span.kind == SPAN_KIND_SERVER
            and span.status.code == STATUS_CODE_ERROR
            and span.attributes["app.legacy_http_status_error"] == true
            and IsInt(span.attributes["http.response.status_code"])
            and span.attributes["http.response.status_code"] >= 400
            and span.attributes["http.response.status_code"] < 500
        statements:
          - set(span.status.message, "")
          - set(span.status.code, STATUS_CODE_UNSET)
      - context: span
        statements:
          - delete_key(span.attributes, "http.request.header.cookie")
          - set(span.cache["route_parts"], ExtractPatterns(span.attributes["url.path"], "^/api/(?P<group>orders|customers)(/|$)")) where IsString(span.attributes["url.path"])
          - set(span.attributes["app.route_group"], span.cache["route_parts"]["group"]) where span.cache["route_parts"]["group"] != nil

두 번째 그룹은 지정한 스팬 속성을 삭제합니다. Cookie 값이 리소스 속성이나 스팬 이벤트, 로그 본문에도 있다면 따로 처리해야 합니다. ExtractPatterns는 이름이 붙은 캡처를 맵으로 반환하고, 일치하는 값이 없으면 빈 맵을 반환합니다. 그다음 문은 맵의 group을 사용자 정의 문자열 속성에 씁니다. http.route의 원래 값은 그대로 둡니다.

규칙을 실행하려면 실제 service.pipelines.traces.processors 목록에 transform을 추가합니다. 다른 예는 OTTL 패턴 모음(중국어 간체)에서 볼 수 있습니다.

어느 단계에서 변환할까?

Collector에서 사용 중인 규칙은 내보내기 전에 계속 실행할 수 있습니다. DataKit의 Guance Pipeline(영어)에서 로그를 처리한다면 Platypus로 다시 작성하고 같은 레코드로 출력을 비교합니다. 필드 삭제, 타입 변환, 실패 처리 결과를 하나씩 확인합니다. 어느 단계에서 민감 정보를 제거하고 이름을 바꿀지 정한 뒤, 백엔드에 들어온 데이터를 조회합니다. 뒤쪽에서 민감한 값을 지우더라도 앞 단계에서는 원래 값을 다루게 됩니다.

자주 묻는 질문

OTTL과 filter processor는 어떻게 다른가요? OTTL은 언어입니다. transform processor는 OTTL을 사용해 필드를 수정하고, filter processor는 조건에 맞는 스팬이나 로그 등을 버립니다. 필터 조건이 바뀐 필드를 참조한다면 같은 파이프라인에서 transform을 먼저 실행합니다.

OTTL의 실행 비용은 어느 정도인가요? 규칙 실행 횟수, 데이터 양, 작업 종류에 따라 달라집니다. 레코드마다 정규식을 평가하거나 JSON을 파싱하면 CPU를 사용합니다. 규칙이나 처리 위치를 바꿀 때 처리량과 지연, Collector 자원 사용량을 비교합니다.

변환문이 실패하면 어떻게 되나요? 이 버전에서 transform의 기본값은 ignore입니다. 실행 중 발생한 오류를 기록하고 계속 진행합니다. silent는 기록 없이 계속하며, propagate는 오류를 파이프라인으로 반환하고 해당 데이터를 버리게 합니다. 문을 파싱할 수 없다면 설정 오류입니다. 민감 정보 제거에 ignore를 쓴다면 실패한 레코드에 원래 값이 남는지도 확인합니다.

Guance Pipeline에서 OTTL을 실행할 수 있나요? Pipeline은 Platypus 스크립트 문법을 사용합니다. 해당 함수와 데이터 타입에 맞게 규칙을 다시 작성하고 같은 샘플에서 처리 결과를 확인합니다.

관련 글

참고 자료 OTTL 언어 참조 v0.162.0(영어) · Guance OpenTelemetry 연동(영어) · DataKit Pipeline(영어) · DataKit 문서(영어)

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소