본문 바로가기
WIKI 기술 지식 베이스

쿼리 구문 (Query Syntax)

원문 보기 위키 갱신

태그로 모든 트레이스를 전역 검색하는 쿼리 구문에 대해 알아봐요. 검색 매개변수는 페이지의 URL에 모두 포함되어 있어 뷰를 공유하는 데 유용해요.

출처: 문서

본문

검색 쿼리 (Search query)

모든 검색 매개변수는 페이지의 URL에 포함돼요. 이는 뷰를 공유하는 데 도움이 될 수 있어요.

검색 구문 (Search syntax)

쿼리는 용어(terms) 와 연산자(operators) 로 구성돼요.

두 가지 유형의 용어 가 있어요:

  • 스팬 속성 (Span attribute): 애플리케이션에서 자동 또는 수동 계측으로 수집되는 스팬의 내용.
  • 스팬 태그 (Span tag): 스팬과 관련된 컨텍스트의 보강. 예를 들어 서비스가 실행되는 인프라를 설명하는 호스트 또는 컨테이너 태그.

여러 용어 를 복잡한 쿼리로 결합하려면 다음 불리언 연산자 중 하나를 사용해요:

연산자 (Operator) 설명 (Description) 예시 (Example)
AND 교집합 (Intersection): 두 용어가 모두 선택한 이벤트에 있음(아무것도 추가하지 않으면 기본적으로 AND가 적용됨) authentication AND failure
OR 합집합 (Union): 두 용어 중 하나가 선택한 이벤트에 포함됨 authentication OR password
- 제외 (Exclusion): 다음 용어가 이벤트에 없음 authentication AND -password

스팬 속성을 검색하려면 속성 키 앞에 @를 추가해야 해요.

예를 들어 아래 속성이 있는 스팬에 접근하려면 다음을 사용할 수 있어요:

@git.commit.sha:12345

  "git": {
    "commit": {
      "sha": "12345"
    },
    "repository": {
      "id": "github.com/datadog/datadog"
    }
  }

스팬 속성은 트레이스 사이드 패널의 Overview 탭에서 볼 수 있어요.

참고: 예약 속성 (reserved attributes)에는 @를 사용할 필요가 없어요: env, operation_name, resource_name, service, status, span_id, timestamp, trace_id, type, link.

스팬은 이를 생성하는 호스트와 통합의 태그를 상속받아요.

예를 들어:

쿼리 (Query) 일치 (Match)
(hostname:web-server OR env:prod) 인프라 태그 hostname:web-server 또는 예약 속성 env:prod가 있는 모든 트레이스
(availability-zone:us-east OR container_name:api-frontend) 이러한 인프라 태그 중 하나를 가진 모든 트레이스
(service:api AND -kube_deployment:canary) canary 배포에 배포되지 않은 api 서비스의 모든 트레이스

스팬 태그는 트레이스 사이드 패널의 Infrastructure 탭에서 볼 수 있어요.

비표준 태그 형식 (Non-standard tag formats)

태그가 태그 모범 사례 (tags best practices)를 따르지 않는다면 key:value 구문을 사용하지 말고 다음 검색 쿼리를 사용해요:

tags:<MY_TAG>

예를 들어 이 태그는 모범 사례를 따르지 않아요: auto-discovery.cluster-autoscaler.k8s.io/daffy

이 태그를 검색하려면 다음 쿼리를 사용해요: tags:"auto-discovery.cluster-autoscaler.k8s.io/daffy"

와일드카드 (Wildcards)

다중 문자 와일드카드 검색을 수행하려면 다음과 같이 * 기호를 사용해요:

  • service:web* 는 web으로 시작하는 서비스가 있는 모든 트레이스와 일치해요
  • @url:data* 는 data로 시작하는 url이 있는 모든 트레이스와 일치해요.

숫자 값 (Numerical values)

숫자 속성에 대한 검색을 수행하려면 <,>, <= 또는 >=를 사용해요. 예를 들어 응답 시간이 100ms가 넘는 모든 트레이스를 검색하려면:

@http.response_time:>100

특정 범위 내의 숫자 속성을 검색할 수도 있어요. 예를 들어 모든 4xx 오류를 검색하려면:

@http.status_code:[400 TO 499]

자동 완성 (Autocomplete)

복잡한 쿼리를 입력하는 것은 번거로울 수 있어요. 검색창의 자동 완성 기능을 사용해 기존 값으로 쿼리를 완성해요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/search_bar_autocomplete.d2625217396f4abc2224119cdfd1a002.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/search_bar_autocomplete.d2625217396f4abc2224119cdfd1a002.png?auto=format&fit=max&w=850&dpr=2 2x" alt="search bar autocomplete " /%}

특수 문자 이스케이프 (Escaping of special characters)

다음 속성은 특수 문자로 간주돼요: ?, >, <, :, =,", ~, /, \는 이스케이프가 필요해요. 예를 들어 url에 user=JaneDoe가 포함된 트레이스를 검색하려면 다음 검색을 입력해야 해요:

@url:*user\=JaneDoe*

동일한 논리가 트레이스 속성의 공백에도 적용돼야 해요. 트레이스 속성에 공백을 두는 것은 권장되지 않지만, 이런 경우 공백은 이스케이프가 필요해요. 속성이 user.first name이라면 공백을 이스케이프해 이 속성을 검색해요:

@user.first\ name:myvalue

저장된 검색 (Saved searches)

매일 같은 뷰를 만드는 데 시간을 낭비하지 마세요. 저장된 검색에는 검색 쿼리, 열, 시간 범위가 포함돼요. 그러면 검색 이름이나 쿼리와 일치하는 자동 완성 덕분에 검색창에서 사용할 수 있어요.

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/saved_search.292577aebf243e5ead5901f6a0b013d7.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/saved_search.292577aebf243e5ead5901f6a0b013d7.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Saved Search" /%}

저장된 검색을 삭제하려면 Trace search 드롭다운 메뉴 아래의 휴지통 아이콘을 클릭해요.

서비스와 엔터티 검색 (Search for services and entities)

{% callout %}

다음 Datadog 사이트 사용자에게 중요한 안내: ap1.datadoghq.com, ap2.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, app.datadoghq.com, uk1.datadoghq.com

서비스를 검색하려면 service 속성을 사용해요. 다른 엔터티 유형(예: 데이터베이스, 큐, 타사 제공자)을 검색하려면 Datadog이 APM으로 계측되지 않은 종속성을 설명하는 데 사용하는 다른 peer 속성 (peer attributes)을 사용해요. 예를 들어 postgres 데이터베이스의 users 테이블에 대한 호출을 나타내는 스팬을 찾으려면 다음 쿼리를 사용해요: @peer.db.name:users @peer.db.system:postgres

참고: DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAME_ENABLED=true를 설정해 전역 서비스 이름 지정 (global service naming)으로 마이그레이션했다면 스팬의 service 태그는 스팬을 전송하는 서비스를 나타내요.

{% /callout %}

시간 범위 (Time range)

시간 범위를 사용하면 주어진 기간 내의 트레이스를 표시할 수 있어요. 드롭다운 메뉴에서 사전 설정된 범위를 선택해(또는 커스텀 시간 범위 입력) 시간 범위를 빠르게 변경해요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/time_frame2.6107237490500cfe31a3ef0b9d740d97.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/time_frame2.6107237490500cfe31a3ef0b9d740d97.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Select time frame" /%}

스팬 테이블 (Span table)

스팬 테이블은 선택한 컨텍스트와 일치하는 스팬 목록이에요. 컨텍스트는 검색창 필터와 시간 범위로 정의돼요.

{% callout %}

다음 Datadog 사이트 사용자에게 중요한 안내: ap1.datadoghq.com, ap2.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, app.datadoghq.com, uk1.datadoghq.com

서비스 열 (The service column)

기본적으로 서비스 열은 스팬의 service 예약 속성을 보여줘요.

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/span_table_service.bd9ac366b87deafda7a7583115eb39f1.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/span_table_service.bd9ac366b87deafda7a7583115eb39f1.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Span table service column" /%}

스팬이 계측된 서비스에서 추론 서비스로의 클라이언트 호출을 나타내면 서비스 열은 다음을 보여줘요:

서비스 이름이 기본 서비스 이름의 재정의(override)인 경우 서비스 열은 다음을 보여줘요:

{% /callout %}

전체 트레이스 표시하기 (Displaying a full trace)

아무 스팬이나 클릭하면 연결된 트레이스에 대한 세부 정보가 표시돼요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/trace_in_tracestream.60b61aedcc65474c3f92dd18309e93b1.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/trace_in_tracestream.60b61aedcc65474c3f92dd18309e93b1.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Trace in tracestream" /%}

열 (Columns)

다른 스팬 태그나 속성을 목록의 열로 추가하려면 Options 버튼을 클릭하고 추가하려는 차원을 선택해요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/trace_list_with_column.6d547280f56951feaf03a05300bfbcec.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/trace_list_with_column.6d547280f56951feaf03a05300bfbcec.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Trace list with columns" /%}

트레이스 그룹 (Trace Groups)

쿼리를 아무 스팬 태그나 속성으로 그룹화해 목록 뷰에서 요청 수, 오류율, 지연 시간 분포를 관찰해요. Group by 절에서 최대 4개의 차원을 선택할 수 있어요.

{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/trace_groups/group_by_clause.dc961e826bbfb96ab2b2f2509c29d0fb.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/trace_groups/group_by_clause.dc961e826bbfb96ab2b2f2509c29d0fb.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Group by clause" /%}

고급 'Group By' 쿼리 (Advanced 'Group By' queries)

그룹화할 차원을 선택한 후 from 드롭다운을 사용해 차원의 값을 어디서 가져올지 지정할 수 있어요:

  • Span: 쿼리된 스팬의 차원으로 그룹화(기본). 예: a.
  • Parent of span: 쿼리와 일치하는 스팬의 부모 스팬에서 지정한 차원으로 그룹화. 예를 들어 API 엔드포인트가 호출하는 서비스에 따라 어떻게 동작하는지 시각화하려면 parent(a)에서 service로 그룹화해요.
  • Root span: 트레이스의 루트 스팬에서 지정한 차원으로 그룹화. 예를 들어 프론트엔드 페이지에서 요청이 시작되는 방식에 따라 백엔드 요청 패턴을 분석하려면 root에서 @view.name으로 그룹화해요.

{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/trace_groups/group_by_root.c311e7190c9de1e54bc79bb9f12071ad.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/trace_groups/group_by_root.c311e7190c9de1e54bc79bb9f12071ad.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Group by from root" /%}

그룹 목록에서 트레이스 그룹 보기 (View trace groups in the group list)

트레이스 그룹은 선택한 차원의 고유 값으로 표시돼요. 각 그룹은 세 가지 핵심 메트릭과 함께 표시돼요:

  • REQUESTS: 그룹 내 스팬 수.
  • ERRORS: 오류율과 오류 수.
  • P95 Latency: 스팬의 p95 지연 시간.

이 메트릭을 쿼리된 스팬 대신 부모 또는 루트 스팬에 대해 집계해 보려면 Show metrics from 문에서 parent(a) 또는 root를 선택해요.

추가로 Latency Breakdown은 각 그룹의 요청 내에서 서로 다른 서비스 간에 시간이 어떻게 소비되는지 표면화해, 특정 그룹의 지연 병목 지점을 시각적으로 찾을 수 있게 해 줘요.

{% image source="https://docs.dd-static.net/images/tracing/trace_explorer/trace_groups/group_list.763a57fd12c7b77e0eca792148542975.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_explorer/trace_groups/group_list.763a57fd12c7b77e0eca792148542975.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Group list" /%}

더 깊은 분석을 위해 아무 그룹이나 클릭해 집계된 메트릭을 구성하는 개별 스팬 이벤트를 검사해요.

패싯 (Facets)

패싯은 속성이나 태그의 모든 고유 값을 표시하고 대표되는 트레이스 수 같은 기본 분석을 제공해요. 이는 데이터를 필터링하는 스위치이기도 해요.

패싯을 사용하면 주어진 속성에 따라 데이터셋을 피벗하거나 필터링할 수 있어요. 패싯의 예로는 사용자, 서비스 등이 있어요.

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/facets_demo.6b5ebc17c97f364e6226da161f84fd4a.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/facets_demo.6b5ebc17c97f364e6226da161f84fd4a.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Facets demo" /%}

측정값 (Measures)

측정값은 정량적 값에 대한 특정 유형의 패싯이에요.

다음이 필요할 때 측정값을 사용해요:

  • 여러 트레이스의 값을 집계. 예를 들어 Cassandra의 행 수에 대한 측정값을 만들고 요청된 파일 크기 합계별 P95 또는 상위 리퍼러를 봐요.
  • $1000가 넘는 쇼핑 카트 값에 대해 숫자로 최고 지연 시간 서비스를 계산.
  • 연속 값 필터링. 예를 들어 비디오 스트림의 각 페이로드 청크의 바이트 크기.

유형 (Types)

측정값은 동일한 기능을 위해 (long) 정수 또는 double 값을 가져요.

단위 (Units)

측정값은 쿼리 시점과 표시 시점에 차수를 처리하기 위해 단위(초 단위 시간 또는 바이트 단위 크기)를 지원해요. 단위는 필드가 아니라 측정값 자체의 속성이에요. 예를 들어 나노초 단위의 duration 측정값을 생각해 봐요: service:A의 스팬 태그가 있어 duration:1000은 1000 밀리초를, 다른 service:B의 스팬 태그가 있어 duration:500은 500 마이크로초를 나타낸다고 가정해요. 산술 프로세서로 들어오는 모든 스팬 태그의 duration을 나노초로 조정해요. service:A의 스팬 태그에는 *1000000 배수를, service:B의 스팬 태그에는 *1000 배수를 사용해요. duration:>20ms를 사용해(참고용으로 검색 구문 참조) 두 서비스의 스팬 태그를 한 번에 일관되게 쿼리하고 최대 1분의 집계 결과를 봐요.

패싯 만들기 (Create a facet)

속성을 패싯으로 사용하거나 검색에서 사용하려면 속성을 클릭하고 패싯으로 추가해요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/create_facet.2344bf7f583d73a3bce951bbadd90a8a.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/create_facet.2344bf7f583d73a3bce951bbadd90a8a.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Create Facet" /%}

새 패싯을 만들면 필터링과 기본 분석을 위해 패싯 패널에서 사용할 수 있어요.

패싯 패널 (Facet panel)

패싯을 사용해 트레이스를 필터링해요. 검색창과 URL은 선택 사항을 자동으로 반영해요.

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/search/facet_panel.c5f952480dff9aa8f33cae97464a84a2.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/search/facet_panel.c5f952480dff9aa8f33cae97464a84a2.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Facet panel" /%}

시각화 (Visualizations)

Analytic 선택기를 사용해 분석 시각화 유형을 선택해요:

  • Timeseries
  • Top List
  • Table

타임시리즈 (Timeseries)

선택한 시간 범위 동안 Duration 메트릭(또는 패싯의 고유 값 수)의 변화를 시각화하고 (선택적으로) 사용 가능한 패싯별로 분할해요.

다음 타임시리즈 분석은 각 Service에 대해 5min 단위의 pc99 duration의 변화를 보여줘요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/analytics/timeserie_example.e812c68d9fee37dcb848ba2868636215.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/analytics/timeserie_example.e812c68d9fee37dcb848ba2868636215.png?auto=format&fit=max&w=850&dpr=2 2x" alt="timeserie example" /%}

상위 목록 (Top list)

Duration(또는 패싯의 고유 값 수)에 따라 패싯의 상위 값을 시각화해요.

다음 상위 목록 분석은 Service의 상위 pc99 duration을 보여줘요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/analytics/top_list_example.8d09398f38dd3092e4bf8e07bbb1524c.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/analytics/top_list_example.8d09398f38dd3092e4bf8e07bbb1524c.png?auto=format&fit=max&w=850&dpr=2 2x" alt="top list example" /%}

테이블 (Table)

선택한 측정값(measure)(목록에서 선택한 첫 번째 측정값)에 따라 패싯의 상위 값을 시각화하고, 이 상위 목록에 나타나는 요소에 대한 추가 측정값의 값을 표시해요. 검색 쿼리를 업데이트하거나 두 차원 중 하나에 해당하는 로그를 조사해요.

  • 차원이 여러 개일 때 상위 값은 첫 번째 차원에 따라 결정되고, 그다음 첫 번째 차원의 상위 값 내에서 두 번째 차원에 따라, 그다음 두 번째 차원의 상위 값 내에서 세 번째 차원에 따라 결정돼요.
  • 측정값이 여러 개일 때 상위 또는 하위 목록은 첫 번째 측정값에 따라 결정돼요.
  • 부분합은 상위(또는 하위)의 일부만 표시되므로 그룹의 실제 값 합과 다를 수 있어요. 이 차원에 대해 null 또는 빈 값이 있는 이벤트는 하위 그룹으로 표시되지 않아요.

참고: 하나의 측정값과 하나의 차원에 사용되는 테이블 시각화는 toplist와 같으며, 표시만 다를 뿐이에요.

다음 Table Log Analytics는 지난 15분 동안 Throughput에 따른 top Status Codes의 변화와 고유 Client IPs 수를 보여줘요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/analytics/trace_table_example.45953a58640b8dee57c629f9cd358c4a.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/analytics/trace_table_example.45953a58640b8dee57c629f9cd358c4a.png?auto=format&fit=max&w=850&dpr=2 2x" alt="top list example" /%}

그래프의 섹션을 선택하거나 클릭해 그래프를 확대하거나 선택에 해당하는 트레이스 목록을 봐요:

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/analytics/view_traces.b3d503c05e9a05b905f33dbf8670407c.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/analytics/view_traces.b3d503c05e9a05b905f33dbf8670407c.png?auto=format&fit=max&w=850&dpr=2 2x" alt="view Traces" /%}

내보내기 (Export)

{% image source="https://docs.dd-static.net/images/tracing/app_analytics/analytics/export_button.c4bf15516694f9ed3c71e92abf6a6577.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/app_analytics/analytics/export_button.c4bf15516694f9ed3c71e92abf6a6577.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Export your analytics button" /%}

쿼리를 내보내요:

쿼리에 대한 새 메트릭을 생성할 수도 있어요.

참고: 대시보드와 노트북의 APM 쿼리는 모든 인덱싱된 스팬 (indexed span)을 기반으로 해요. 모니터의 APM 쿼리는 커스텀 보존 필터 (custom retention filters)로 인덱싱된 스팬만 기반으로 해요.

더 알아보기 (Learn more)

도움이 되는 추가 문서, 링크, 아티클이에요: