스팬 태그, 속성 및 패싯 (Span Tags, Attributes, and Facets)
스팬 패싯(span facet)과 패싯 패널에 대해 알아봐요. 스팬 메타데이터는 속성(attributes) 과 태그(tags) 로 구성돼요.
출처: 문서
본문
개요 (Overview)
스팬 메타데이터는 속성(attributes) 과 태그(tags) 로 구성돼요.
-
스팬 속성 (Span attributes) 은 애플리케이션에서 자동 또는 수동 계측으로 수집되는 스팬의 내용이에요.
-
스팬 태그 (Span tags) 는 스팬과 관련된 컨텍스트의 보강이에요. 예를 들어 서비스가 실행되는 인프라를 설명하는 호스트 또는 컨테이너 태그가 있어요.
trace explorer에서 모든 스팬 태그와 속성으로 스팬을 쿼리할 수 있어요.
예약 속성 (Reserved attributes)
예약 속성은 모든 스팬에 존재하는 스팬 속성의 부분집합이에요. 이 속성들은 @ 문자를 앞에 붙이지 않고도 쿼리할 수 있어요. 예약 속성의 전체 목록은 env, service, operation_name, resource_name, status, ingestion_reason, trace_id예요. 이 용어들의 전체 정의는 APM 용어와 개념을 참고하세요.
스팬 속성 (Span attributes)
스팬 속성은 스팬의 내용이에요. 이들은 SDK에서 자동 계측을 사용해 기본 제공으로 수집되거나, 커스텀 계측으로 수동 수집되거나, 소스 속성을 기반으로 Datadog 백엔드에서 리매핑돼요(peer 속성 참고, 일부 소스 속성에서 리매핑됨). 특정 스팬 속성을 검색하려면 속성 키 앞에 @ 문자를 붙여야 해요.
예를 들어 postgres 데이터베이스의 users 테이블에 대한 호출을 나타내는 스팬을 찾으려면 다음 쿼리를 사용해요: @peer.db.name:users @peer.db.system:postgres.
스팬 태그 (Span tags)
스팬 태그는 스팬 주변의 컨텍스트로, 스팬이 전송되는 서비스가 실행되는 호스트나 컨테이너를 기반으로 보강돼요. 스팬 태그를 쿼리할 때는 @ 문자를 앞에 붙일 필요가 없어요.
패싯 (Facets)
스팬 태그와 속성 위에 패싯(facets) 을 만들어 속성을 올바른 유형(예: 문자열 또는 정수)에 매핑하고 이 속성들이 패싯 목록에 표시되게 할 수 있어요.
참고: 패싯 생성은 스팬 검색, 스팬에서 메트릭 생성, 또는 보존 필터로 스팬 인덱싱에 필수는 아니에요.
{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/facets/facet_panel.1d39a2232227c130f0e9f1d874f67f8c.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/facets/facet_panel.1d39a2232227c130f0e9f1d874f67f8c.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The Facets panel in the Trace Explorer" /%}
정성적 패싯 (Qualitative facets)
다음이 필요할 때 정성적 패싯을 사용해요:
- 값에 대한 상대적 인사이트 얻기. 예를 들어 느린 요청이 감지되었을 때 조사를 특정 리전으로 좁히기 위해
datacenter스팬 태그에 패싯을 만들 수 있어요. - 고유 값 세기. 예를 들어 특정 리소스를 로드할 때 오류를 겪는 고유한 사용자 수를 보려면
usr.email에 패싯을 만들 수 있어요. - 특정 값에 대해 스팬을 자주 필터링. 예를 들어 문제 해결을 개발, 스테이징, 프로덕션 환경으로 좁히기 위해 환경 태그에 패싯을 만들 수 있어요.
참고: 태그 필터링에 패싯이 필수는 아니지만, 조사 중 자주 사용하는 태그에 대한 패싯을 정의하면 해결 시간을 줄이는 데 도움이 될 수 있어요.
정량적 패싯 (측정값, Quantitative facets/measures)
다음이 필요할 때 측정값(measure)을 사용해요:
- 여러 트레이스의 값을 집계. 예를 들어 Cassandra의 행 수에 대한 측정값을 만들고 요청된 파일 크기 합계별 p95 또는 상위 리퍼러를 볼 수 있어요.
- 숫자로 최고 지연 시간 서비스를 계산. 예를 들어 $1000가 넘는 쇼핑 카트 값에 대해 계산할 수 있어요.
- 연속 값 필터링. 예를 들어 비디오 스트림의 각 페이로드 청크의 바이트 크기 같은 값을 필터링할 수 있어요.
측정값 유형 (Measure types)
측정값은 동일한 기능을 위해 (long) 정수 또는 double 값을 가져요.
단위 (Units)
측정값은 쿼리 시점과 표시 시점에 차수(orders of magnitude)를 처리하기 위해 단위(초 단위 시간 또는 바이트 단위 크기)를 지원해요. 단위는 필드가 아니라 측정값 자체의 속성이에요.
예를 들어 나노초 단위의 duration 측정값을 생각해 봐요. service:A의 스팬이 duration:1000(즉 1000 밀리초)이라고 가정해요. service:B의 스팬이 duration:500(즉 500 마이크로초)이라고 가정해요. duration:>20ms를 사용하면 두 서비스의 스팬 태그를 한 번에 일관되게 쿼리할 수 있어요. 쿼리에 대한 더 많은 참고 정보는 쿼리 구문을 읽어보세요.
패싯 패널 (Facet panel)
검색창은 데이터를 필터링하고 그룹화하는 가장 포괄적인 상호작용 집합을 제공해요. 그러나 많은 경우 패싯 패널이 데이터로 이동하는 간단한 방법이에요. 패싯을 열어 현재 쿼리 범위에 대한 내용 요약을 확인해요.
검색창과 URL은 패싯 패널에서의 선택을 자동으로 반영해요.
- 패싯(정성적)은 고유 값의 상위 목록과 각각에 일치하는 스팬 수와 함께 제공돼요.
- 측정값(정량적)은 최소·최대 값을 나타내는 슬라이더와 함께 제공돼요. 슬라이더를 사용하거나 숫자 값을 입력해 검색 쿼리의 범위를 다른 경계로 한정해요.
패싯 숨기기 (Hiding facets)
조직에는 트레이스를 사용하는 다양한 팀의 사용 사례를 다루는 많은 패싯이 있어요. 대부분 특정 문제 해결 컨텍스트에서 이 중 일부만 가치가 있을 가능성이 커요.
문제 해결 세션에 가장 관련성 높은 패싯만 유지하려면 일상적으로 필요하지 않은 패싯을 숨기세요.
{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/facets/hide_facets.82646de8c44e72fd6eefe4bfd1962fb7.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/facets/hide_facets.82646de8c44e72fd6eefe4bfd1962fb7.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Hide Facet" /%}
숨겨진 패싯은 필요할 때를 대비해 패싯 검색(Filter Facet 섹션 참고)에서 여전히 볼 수 있어요. 패싯 검색에서 숨겨진 패싯을 다시 표시해요.
{% image source="https://docs.dd-static.net/images/logs/explorer/facet/unhide_facet.dd6a46987317ee4c917b420e1e52b404.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/logs/explorer/facet/unhide_facet.dd6a46987317ee4c917b420e1e52b404.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Unhide Facet" /%}
숨겨진 패싯과 팀원 (Hidden facets and teammates)
패싯 숨기기는 사용자 자신의 문제 해결 컨텍스트에 특정되며, 저장된 뷰를 업데이트하지 않는 한 팀원의 뷰에는 영향을 주지 않아요. 숨겨진 패싯은 저장된 뷰에 저장되는 컨텍스트의 일부예요.
패싯 그룹화 (Grouping facets)
패싯 목록에서 패싯은 의미 있는 테마로 그룹화돼요. 패싯의 그룹을 지정하거나 다시 지정하는 것은 패싯 목록에만 영향을 주며, 검색이나 분석에는 영향을 주지 않아요.
{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/facets/group_facets.8ecaae32c2a910778473cab4b00eed55.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/facets/group_facets.8ecaae32c2a910778473cab4b00eed55.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Group Facets" /%}
패싯 필터링 (Filtering facets)
패싯 패널의 search facets 상자를 사용해 전체 패싯 목록의 범위를 좁히고 상호작용해야 하는 패싯으로 더 빠르게 이동해요. Search facets는 패싯 표시 이름과 필드 이름을 사용해 결과 범위를 좁혀요.
{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/facets/filter_facets.09d7ea70bb5f330d775d85e6943c0ce1.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/facets/filter_facets.09d7ea70bb5f330d775d85e6943c0ce1.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Search Facet" /%}
패싯 만들기 (Creating facets)
스팬 속성/태그에 패싯을 만드는 것은 스팬을 검색하기 위한 필수 단계가 아니에요. 패싯은 특정 스팬 속성에 의미 있는 설명을 추가하거나, 스팬 속성 값이 스팬 목록 왼쪽의 Facet 목록에 나타나기를 원할 때 유용해요.
트레이스 사이드 패널에서 패싯 만들기 (Creating facets from the trace side panel)
패싯을 만드는 가장 쉬운 방법은 트레이스 사이드 패널에서 추가해 필드 경로와 기본 유형 같은 대부분의 패싯 세부 정보를 미리 채우는 것이에요. Trace Explorer에서 패싯을 만들 필드가 포함된 관심 스팬으로 이동해요. 목록에서 스팬을 선택해 이 스팬의 트레이스 사이드 패널을 열어요. 원하는 필드(스팬 태그 또는 인프라 태그)를 클릭하고 그곳에서 패싯을 만들어요:
- 필드가 숫자 값을 가지면 패싯 또는 측정값을 만들 수 있어요.
- 필드가 문자열 값을 가지면 패싯 생성만 가능해요.
{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/facets/create_facet.423cc923346aadf4dd02defa4da8f899.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/facets/create_facet.423cc923346aadf4dd02defa4da8f899.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Add Facet from tags" /%}
패싯 목록에서 패싯 만들기 (Creating facets from the facet list)
원하는 필드가 있는 스팬을 찾는 것이 어렵다면 패싯 패널에서 + Add를 클릭해 직접 패싯을 만들어요.
이 패싯의 기본 필드(키) 이름을 정의해요:
- 인프라 태그에는 태그 키 이름을 사용해요.
- 스팬 속성에는
@접두사를 사용한 속성 경로를 사용해요.
현재 뷰의 스팬 내용을 기반으로 한 자동 완성은 올바른 필드 이름을 정의하는 데 도움이 돼요. 그러나 이 값은 실질적으로 무엇이든 사용할 수 있어요. 특히 Datadog이 아직 일치하는 스팬을 수신하지 않은 경우에 그렇죠.
{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/facets/create_facet_from_scratch.c200025374f3ca681886fa66f8bba1df.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/facets/create_facet_from_scratch.c200025374f3ca681886fa66f8bba1df.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Add Facet from scratch" /%}
더 알아보기 (Learn more)
도움이 되는 추가 문서, 링크, 아티클이에요: