Overview
This document provides an overview of the OpenTelemetry project and defines important fundamental terms. Additional term definitions can be found in the glossary. OpenTelemetry Client Architecture At the highest architectural level, OpenTelemetry clients a
opentelemetry.io
Client Architecture
OpenTelemetry는 context propagation이라 불리는 공유 매커니즘 위에 구현된 signal이라 불리는 별개의 관측가능성 도구들의 모음으로 설계됐다.
signal은 여러 라이브러리가 섞여있는 횡단 관심사로 작동하며 각각의 signal은 애플리케이션의 소유자(owner)가 각각 관리할 수 있는 부분과 별개로 관리된다. 쉽게 생각하면 애플리케이션 코드와 별개로 관린된다고 생각해도 될 거 같다.
아키텍처 최상단 수준에서 클라이언트는 signal로 구성된다. (여기서 말하는 클라이언트가 정확히 뭘까?). 각 신호는 특화된 형태의 관측 가능성을 제공한다. 예를 들어 트레이싱, 매트릭, 그리고 baggage는 세 개의 별개 신호다. signal들은 context-propagation이라는 공통 하위 시스템을 공유하지만 서로 독립적으로 작동한다. 즉, context-propagation이라는 개념 위에 각각의 signal이 작동한다.
각 signal은 소프트웨어가 스스로를 나타낼 수 있는 매커니즘을 제공한다. 웹 프레임워크나 데이터베이스 클라이언트와 같은 코드베이스는 자신을 설명하기 위해 다양한 signal에 종속성을 취한다. 그런 다음 OpenTelemetry는 계측(instrumentation) 코드를 해당 코드베이스 내의 다른 코드에 섞을 수 있다.
(아마 여기서 말하는 자신을 설명한다는거는 속성을 말하는게 아닐까?
그리고 다른 코드에 섞는다는 말에서 다른 코드는 프레임워크를 이용해 개발한 코드를 말하는게 아닐까.)
아무튼 이런 것이 OpenTelemetry가 횡단 관심사(가치있는 값을 제공하기 위해 여러 소프트웨어에 섞여있는 소프트웨어)로서 작동할 수 있게 만든다. 횡단 관심사는 핵심 설계 원칙인 관심사의 분리를 위반하기 때문에 횡단 관심사 API에 의존하는 코드베이스에 문제가 발생하지 않도록 OpenTelemetry 클라이언트 설계에 주의가 필요하다.
API
API 패키지는 instrumentation에 사용되는 cross-cutting public interface로 구성된다. cross-cutting public interface가 뭐야... 타사 라이브러리 및 애플리케이션 코드에 import된 OpenTelemetry의 모든 부분은 API의 일부분으로 간주된다. 이게 뭔 소리일까... 이해가 안되지.
API is used to instrument a library ( 참고 사이트 )
즉, API는 라이브러리를 instrument 하기 위해 사용한다. 내가 이해한거는 특정 라이브러리를 계측하기 위해 만들 함수나 패키지 등이 될 수 있겠다.
SDK
SDK는 OpenTelemetry 프로젝트에서 제공하는 API의 구현체다. 이건 또 뭔 소리야 구현체라니. 애플리케이션 내에서 SDK는 애플리케이션 owner에 의해 설치되고 관리된다. SDK에는 API 패키지의 일부로 간주되지 않는 추가 공용 인터페이스가 포함되어 있다. 이런 공용 인터페이스는 constructor 및 플러그인 인터페이스로 정의된다... ? 이건 뭔 소리야. 애플리케이션 owner는 SDK생성자를 사용하고, 플러그인 작성자는 SDK 플러그인 인터페이스를 사용한다. instrumentation 작성자는 어떤 종류의 SDK 패키지도 직접 참조해서는 안되면 API만 참조해야 한다.
SDK to send telemetry into Processing and Exporting pipeline
정말 간략하게 이해한거는 SDK는 API를 이용해 계측 데이터를 처리하는 것.
Sementic Conventions
시맨틱 규칙은 애플리케이션에서 일반적으로 관찰되는 개념, 프로토콜 및 연산을 설명하는 키와 값을 정의한다.
collector와 클라이언트 라이브러리는 모두 시맨틱 규칙 키와 열거형 값을 상수로 자동 생성해야 한다. 생성된 값은 시맨틱 규칙이 stable 해질 때까지 stable 패키지로 배포해서는 안된다.
각 언어 구현은 code generator에 대한 언어별 지원을 제공해야 한다.
또한 specification에서 요구하는 속성(attribute)은 다음과 같다.
<추가 설명>
일반적으로 시맨틱 규칙이라고하면 특정 언어 또는 문화권 내에서 합의된 단어와 구의 의미를 의미한다. 이는 기호에 대한 공통된 이해를 제공함으로써 서로 소통하는 데 도움이 된다. 예를 들어 "개" 라는 단어는 '가축으로 사람을 잘 따르는 포유류' 를 의미한다. 개라는 단어로 사람들은 의사소통을 할 수 있다.
OpenTelemetry에서 시맨틱 규칙은 시스템의 여러 구성 요소 간에 데이터를 구조화하고 교환하는 방법을 정의하는 방법을 제공하기 때문에 필수적이다.
그러니까 otel의 시맨틱 규칙은 일반적으로 관찰되는 개념, 프로토콜 및 연산을 설명하는 키와 값을 미리 정의하고 이를 사용하는 사람들간에 합의된 의미로 사용할 수 있는거다.
Contrib Paackge
... 추가 필요 ...
Tracing Signal
분산 추적은 단일 논리 작업의 결과로 트리거되는 일련의 이벤트로, 애플리케이션의 다양한 구성 요소에 걸쳐 통합된다. (통합된다는게 뭘까?). 분산 추적에는 프로세스, 네트워크, 보안 경계를 넘나드는 이벤트가 포함된다. 분산 추적은 누군가가 웹사이트에서 작업을 시작하기 위해 버튼을 누를 때 시작될 수 있다. 이 예에서 추적은 이 버튼 누름으로 시작된 일련의 요청을 처리한 다운스트림 서비스 간의 호출을 나타낸다.
Traces
OpenTelemetry의 트레이스는 span에 의해 암시적으로 정의된다. 특히, 트레이스는 스팬 간의 edge(에지)가 부모/자식 관계로 정의되는 스팬의 방향성 비순환 그래프(Directed Acylic Graph)로 생각할 수 있다. (이게 뭔 소릴까? 일단 간단하게 이해하면 비순환 그래프다. 즉 부모/자식 관계가 순환하지 않는다)
예를 들어 아래 그림은 6개의 스팬으로 구성된 트레이스다.
시간 축을 이용해 표현할수도 있다.
Spans
스팬은 트랜잭션 내의 작업을 나타낸다. 각 스팬의 다음과 같은 상태를 캡슐화한다.
- 작업 이름
- 시작, 종료 시간
- 속성: 키-값 쌍
- 0개 이상의 이벤트 집합으로, 각 이벤트는 그 자체로 튜플(타임스탬프, 이름, 속성)이다. 이름은 문자열이어야 한다.
- 부모 스팬 식별자
- 인과관계가 있는 0개 이상의 스팬에 대한 링크(관련 스팬의 컨텍스트를 통해)
- 스팬을 참조하는데 필요한 스팬컨텍스트 정보
SpanContext
추적에서 스팬을 식별하는 모든 정보를 나타내며, 반드시 하위 스팬과 프로세스 경계를 가로질러 전파되어야 한다. 프로세스 경계를 가로질러 전파된다는건 여러 프로세스를 건너서 전파된다고 이해해도 된다. spancontext는 부모 스팬에서 자식 스팬으로 전파되는 추적 식별자와 옵션이 포함된다.
- TraceId: 추적 식별자. 무작위로 생성된 16바이트로 만들어져 worldwide하게 유일한 값일 수 있다. TraceId는 모든 프로세스에서 특정 추적에 대한 모든 스팬을 그룹화하는데 사용된다.
- SpanId: 스팬 식별자. 무작위로 생성된 8바이트이다. 이 식별자가 하위 스팬에 전달되면 하위 스팬의 상위 스팬 ID가 된다.
- TraceFlags: 트레이스에 대한 옵션. 1 바이트 비트맵으로 표현된다. Sampling bit는 트레이스가 샘플리되는지 여부를 결정하는 비트다
- Tracestate: 키 값 쌍의 목록에 추적 시스템별 컨텍스트를 전달한다. Tracestate는 여러 공급업체가 추가 정보를 전파하고 기존 ID 형식과 상호 운용할 수 있게 한다.
Links between spans
스팬은 인과관계가 있는 0개 이상의 다른 스팬에 연결될 수 있다. 링크는 단일 트레이스 내부 또는 여러 트레이스에 걸쳐 있는 스팬을 가리킬 수 있다. 링크는 스팬이 여러 개의 시작 스팬에 의해 시작된 일괄 작업을 나타내는 데 사용할 수 있으며, 각 스팬의 배치에서 처리되는 단일 항목을 나타낸다. 그러니까 여러 스팬이 배치로 처리되는 과정에서 링크를 이용하면 여러 스팬을 하나로 묶어서 볼 수 있다. 배치되는 모든 스팬을 하나의 작업처럼 볼 수 있다는 아니고 묶어서 볼 수 있다 정도.
링크를 사요하는 또 다른 예시는 시작 추적과 다음 추적 간의 관계를 선언하는 것이다. 이는 트레이스가 서비스의 신뢰할 수 있는 경계에 들어가고 서비스 정책에 따라 들어오는 트레이스 컨텍스트를 신뢰하지 않고 새 스테이스 생성이 필요한 경우에 사용할 수 있다.... 무슨 말일까?? 새로 링크된 트레이스는 빠르게 들어오는 많은 요청 중 하나에 의해 시작된 장기 실행 비동기 데이터 처리 작업을 나타낼 수 있다.
분산/수집(포크/조인이라고도 함) 패턴을 사용하는 경우, 루트 작업을 여러 다운스트림 처리 작업을 싲가하고 모든 작업은 단일 스팬으로 다시 집계된다. 이 마지막 스팬은 이 스팬이 집계하는 여러 작업과 연결된다. 이들 모두는 동일한 추적의 스팬이다. 그리고 스팬의 부모 필드와 유사하다. 그러나 의미상 부모 필드는 단일 부모 시나리오를 나타내며 대부분의 경우 부모 스팬이 자식 스팬을 완전히 둘러싸기 때문에 이 시나리오에서는 스팬의 부모를 설정하지 않는 것이 좋다. 얘는 또 무슨 말이냐.....
Tracer
Span을 만드는 책임을 갖는다.
일반적으로 Tracer는 설정에 대한 책임이 없고, TracerProvider가 설정에 대한 책임을 갖는다.
Tracer는 반드시 새로운 span을 생성하는 함수를 제공해야한다.
'OpenTelemetry > 번역' 카테고리의 다른 글
| [Specs] - OTLP 1.1.0 (1) | 2024.04.14 |
|---|---|
| [Specs] - OTel 1.32.0 / Common concepts (0) | 2024.04.14 |
| [Concepts] Instrumentation / Code-base (0) | 2024.04.14 |
| [Concepts] Observability Primer (0) | 2024.04.14 |
| [Demo] Architecture (0) | 2024.04.12 |