[오픈텔레메트리] 트레이싱 API와 수동 계측을 통한 트레이스 데이터 생성

오픈텔레메트리 API를 사용하여 수동 계측을 통해 트레이스 데이터를 생성하고 사용자화 할 수 있다. 오픈텔레메트리의 API에서 트레이스 시그널과 관련된 인터페이스는 다음과 같다.

• 트레이서 프로바이더 (tracer provider): API의 엔트리포인트이다. 트레이서에 대한 접근을 제공한다.
• 트레이서 (tracer): 트레이스 데이터 생성기이다. 스팬을 생성한다.
• 스팬 (span): 작업을 추적하는 API이다. 스팬은 트레이스 내의 단일 작업을 나타낸다. 스팬을 중첩하여 트레이스 트리를 구성할 수 있다. 각각의 트레이스는 일반적으로 전체 작업을 설명하는 루트 스팬(root span)과 선택적으로 하위 작업에 대한 하나 이상의 하위 스팬(sub-span)을 포함한다.

API 구현에서 트레이서 프로바이더는 모든 구성 정보를 포함하는 상태 저장(stateful) 객체이다. 대부분의 애플리케이션에서 트레이스 프로바이더는 한 번 초기화되며, 라이프사이클은 애플리케이션의 라이프사이클과 일치한다. 일반적으로 트레이서 프로바이더는 중앙에서 전역으로 접근하는 것이 의도되며 API는 전역 글로벌의 기본 TracerProvider를 설정 및 등록하고 접근할 수 있는 방법을 제공해야 한다. 전역 글로벌 프로바이더는 애플리케이션 전반에 걸쳐 획득할 수 있는 프로바이더이며 자동 계측을 사용할 경우 환경 변수나 프로퍼티로 설정한 구성 정보를 갖는 트레이서 프로바이더를 획득할 수 있다. 일부 애플리케이션은 서로 다른 구성을 갖는 여러 개의 트레이서 프로바이더 인스턴스를 필요로 할 수도 있다. 예를 들어 서로 다른 스팬 프로세서를 설정해야 하는 경우 서로 다른 트레이서 프로버이더 인스턴스를 생성해야 한다. 따라서 트레이서 프로바이더의 구현은 임의의 수의 트레이서 프로바이더 인스턴스를 생성할 수 있어야 한다.

트레이서 프로바이더로부터 트레이스를 획득할 수 있다. 트레이스 획득 시 다음과 같은 파라미터 전달이 필요하다. 아래 파라미터들은 트레이스 데이터의 출처가 어디인지 사용자가 빠르게 식별할 수 있게 도와준다.

• name (필수): 계측 범위(instrumentation scope)의 이름을 지정한다. 이 이름은 계측 범위를 고유하게 식별해야 하며 계측하고자 하는 애플리케이션 범위 내에서 고유한 값이어야 한다. 계측 범위란 방출되는 텔레메트리 데이터와 연결되는 애플리케이션 코드의 논리적 단위이다. 보통 개발자가 계측 범위를 결정한다. 일반적으로 계측 범위는 계측 라이브러리이며, 모듈, 패키지 또는 클래스를 계측 범위로 선택할 수도 있다.
• version (선택): 계측 범위의 버전(예: 라이브러리 버전)이 있는 경우 지정합니다.
• schema_url (선택): 전송된 텔레메트리에 기록할 스키마 URL을 지정한다. 1.4.0 버전부터 지원된다.
• attributes (선택): 방출된 텔레메트리와 연결할 계측 범위 속성을 지정한다. 1.13.0 버전부터 지원된다.

트레이스 데이터가 애플리케이션 내부에서 계측 및 생성되고 외부로 내보내지는 과정은 트레이스 파이프라인을 통해 이루어진다. 다음 컴포넌트들이 트레이스 파이프라인을 구성한다.

• 트레이서 프로바이더 (tracer provider): 스팬의 생성 방법을 정의한다. 스팬 프로세서와 스팬 익스포터를 설정한 후 트레이스 프로바이더에 설정한다.
• 스팬 프로세서 (span processor): 스팬을 처리하는 방법을 정의한다.
• 스팬 익스포터 (span exporter): 스팬을 외부로 내보내는 방법을 정의한다. 내보내기 대상은 콘솔, 오픈텔레메트리 컬렉터, 기타 텔레메트리 백엔드가 될 수 있다.

스팬은 다음 부가적인 속성 데이터를 갖고 있다.

• 이름 (name): 계측 라이브러리에 의해 자동으로 생성되거나 수동 계측 시 직접 지정하는 스팬 이름이다.
• 트레이스 아이디 (trace id): 단일 요청에 대한 고유한 식별 값이다. 여러 스팬이 하나의 트레이스 아이디를 갖는다. 128비트 정수형 값이다.
• 스팬 아이디 (span id): 단일 요청 내에 특정 작업을 식별하기 위한 고유한 값이다. 여러 스팬 간 관계를 설정할 수 있으며 이 경우 스팬 아이디를 사용하여 스팬들을 연결한다. 64비트 정수형 값이다.
• 부모 아이디 (parent id): 부모와 자식의 계층 구조로 스팬 간 관계를 설정할 수 있다. 부모 스팬를 갖는 자식 스팬은 부모 스팬의 스팬 아이디를 속성으로 갖는다. 부모 스팬이 없는 루트 스팬은 부모 아이디 값이 null이다.
• 컨텍스트 (context): 스팬을 식별하기 위한 데이터를 포함하는 객체이다. 트레이스 아이디와 스팬 아이디를 포함한다. 컨텍스트와 관련된 API를 사용하여 수동으로 컨텍스트를 관리할 수 있다. 컨텍스트 API를 통해 현재 스팬 조회, 새로운 스팬 객체 생성, 스팬을 컨텍스트에 할당 및 스팬 활성화(스팬을 컨텍스트의 현재 스팬으로 지정), 스팬 종료와 같은 작업이 가능하다. 컨텍스트는 서로 다른 서비스 간에 전달될 수 있다.
• 리소스 (resource): 스팬의 출처를 정의한다.
• 속성 (attribute):
• 이벤트 (event):
• 예외 (exception): 스팬의 예외를 지정한다. 해당 스팬과 관련된 작업 도중 발생 가능한 예외의 종류와 예외가 갖는 다양한 정보(메시지, 스택 트레이스, 원인 등)를 표시하기 위해 사용한다. 예외는 이벤트에 기록할 수 있다.
• 상태 (status): 스팬의 상태를 지정한다. 해당 스팬과 관련된 작업이 정상적으로 처리되었는지, 도중에 에러가 발생하였는지에 관한 정보를 표시하기 위해 사용한다.

컨텍스트

오픈텔레메트리에서 컨텍스트(context)는 서비스의 경계를 넘어 논리적으로 연결된 코드 실행 단위(execution unit) 간에 실행 스코프 값을 전달하는 전파(propagation) 메커니즘이다. 교차(cross-cutting) 컴포넌트는 동일한 공유 컨텍스트 객체를 사용하여 처리 중인 데이터에 접근한다.

컨텍스트는 각각의 스팬을 식별하며 서비스 간 전파를 통해 서비스 경계를 넘어서 전달되어야 하는 트레이스 데이터를 갖고 있다. 서로 다른 서비스 간에 컨텍스트가 전달되는 것을 컨텍스트 전파(context propagation)라고 한다.

컨텍스트는 불변이어야 하며 컨텍스트 데이터 쓰기 작업은 원래 데이터를 포함하는 새로운 컨텍스트를 생성 시 특정 값을 변경함으로써 초기화하는 방법을 사용해야 한다.

수동 계측 시 컨텍스트와 스팬 관리

오픈텔레메트리 API를 사용한다면 스팬을 직접 생성하고 조회하는 것은 어렵지 않다. 컨텍스트 API를 사용하면 된다.

새로운 스팬을 생성하려면 트레이스 프로바이더로부터 트레이서를 얻은 후 트레이서를 통해 스팬을 생성하면 된다. 새로 생성된 스팬을 활성화하려면 스팬을 컨택스트에 할당해야 한다.

현재 스팬을 조회하려면

참고

• <>