[Specs] - OTel 1.32.0 / Common concepts

Common specification concepts

공통적으로 사용되는 개념 내용.

 

Attribute

Attribute는 다음 속성을 반드시 포함하는 key-value 쌍의 값이다.

key는 반드시 non-null & non-empty

attribute의 값은

기본 유형: string, boolean, double precision floating point 또는 signed 64 bit integer

기본 유형의 배열: 다른 유형의 값을 포함해서는 안된다.

non-string 유형의 값을 지원하지 않는 프로토콜의 경우, non-string 유형의 값은 JSON 인코딩된 string으로 표현되어야 한다. 예를 들어, int64(100) 은 100으로 인코딩되고 floag64(1.5)는 1.5로 인코딩된다. 그리고 빈 문자열은 [ ]로 인코딩된다.

 

숫자 0, 빈 문자열, 빈 배열을 표현하는 attribute 값은 의미 있는 것으로 간주되며 반드시 저장하여 프로세서/익스포터에 전달해야 한다. 그러니까 의미없는 값은 없다.

 

attribute 값이 null이며 유효하지 않으며 null 값을 설정하려고 시도하는 것은 정의되지 않은 동작이다. 얘는 의미없는 애

 

배열에 널 값을 허용해서는 안됩니다. 그러나 컴파일 시 적절한 형식 검사 기능이 없는 언어와 같이 null 값을 허용하지 않도록 하는 것이 불가능한 경우(예: 적절한 컴파일 시간 형식 검사 기능이 없는 언어)에는 배열 내의 null 값을 그대로 보존해야 한다.(즉, 스팬 프로세서/내보내기에 null로 전달해야 함). 익스포터가 null 값을 지원하지 않는 경우 해당 값을 0, true 또는 false 또는 빈 문자열로 대체할 수 있다.

 

Attribute 제한

에러가 가득한 코드를 실행하면 예기치 못한 attribute가 생길 수 있다. 만약 attribute에 제한이 없으면 가용 메모리가 빠르게 부족해질 수 있으며 안전하게 복구하기 힘든 문제로 이어질 수 있다.

 

기본적으로 SDK는 아래 구성 가능한 매개변수 목록에 따라 truncatation을 적용해야 한다.

만약 SDK가

각 attribute 값의 길이를 제한한다면,

문자열인 경우, limit을 넘길 경우, SDK는 해당 값을 반드시 truncate해 limit에 가까워야 한다.

문자열 배열인 경우, 위의 규칙을 각 문자열에 적용한다.

그 외의 경우는 truncate 하지 않는다.

unique 한 key 에 대한 limit

각각의 unique 한 키에 대해, 추가할 때(? 뭘 추가할 때야?? value?? ) limit을 초과하는 경우 SDK는 반드시 해당 key/value 쌍을 버려야 한다.

attribute가 truncate 되거나 삭제된 경우 사용자에게 알리기 위해 로그를 생성할 수 있다. 과도한 로그를 방지하기 위해 attribute이 설정된 레코드당 로그를 두 번 이상 생성해서는 안된다.

 

만약 SDK가 위의 제한을 구현하는 경우 프로그래밍 방식을 통해 이러한 제한을 변경할 수 있는 방법을 제공해야 한다. 설정 옵션의 이름은 아래 목록과 동일해야 한다.

 

SDK는 모델별 제한을 구현할 수 있다.(예: SpanAttributeCountLimit 또는 LogRecordAttributeCountLimit). 일반 제한과 모델별 제한이 모두 구현된 경우 SDK는 먼저 모델별 제한을 사용하려고 시도하고, 설정되지 않은 경우 일반 제한을 사용하려고 시도한다. 둘 다 정의되어 있지 않으면 SDK는 모델별 제한 기본값을 사용한 다음 전역 제한 기본값을 사용하려고 시도한다.

 

설정 가능한 parameters

AttributeCountLimit (Default=128) - Maximum allowed attribute count per record;

AttributeValueLengthLimit (Default=Infinity) - Maximum allowed attribute value length;

 

Attribute Collections

리소스, 메트릭 데이터, 스팬, 스팬 이벤트, 스팬 링크 그리고 로그 리코드는 attribute의 컬렉션이 포함될 수 있다. 이런한 각 컬렉션의 키는 코유하며 동일한 키를 가진 key-value 쌍이 두 개 이상 존재하면 안된다. 고유성 적용은 특정 구현의 한계에 가장 적합한 여러 방식으로 수행될 수 있다.