chart 명령

chart 명령

chart 명령은 통계 집계 함수를 적용하고 선택적으로 하나 또는 두 개의 필드로 데이터를 그룹화하여 검색 결과를 변환해요. 두 필드로 그룹화하면 결과가 2차원 차트 시각화에 적합하며, 두 번째 그룹 키의 고유 값이 열 이름으로 피벗돼요.

출처: 문서

본문

구문(Syntax)

chart 명령은 다음과 같은 구문을 가져요.

chart [limit=(top|bottom) <number>] [useother=<boolean>] [usenull=<boolean>] [nullstr=<string>] [otherstr=<string>] <aggregation_function> [ by <row_split> <column_split> ] | [over <row_split> ] [ by <column_split>]

매개변수(Parameters)

chart 명령은 다음 매개변수를 지원해요.

Parameter Required/Optional Description Default
<aggregation_function> Required 데이터에 적용할 집계 함수. 단일 집계 함수만 지원돼요. 사용 가능한 함수는 stats 명령이 지원하는 집계 함수예요. N/A
<by> Optional 하나의 필드(행 분할) 또는 두 개의 필드(행 분할 및 열 분할)로 결과를 그룹화해요. limit, useother, usenull 매개변수는 열 분할에 적용돼요. 결과는 각 조합에 대해 개별 행으로 반환돼요. 모든 문서에 대해 집계
over [] by [] Optional 여러 필드로 그룹화하는 대체 구문. over <row_split> by <column_split>은 두 필드 모두로 결과를 그룹화해요. over를 한 필드에 단독으로 사용하는 것은 by <row_split>과 동일해요. N/A
limit Optional 열 분할을 사용할 때 표시할 카테고리 수. limit=N 또는 limit=topN은 상위 N개 카테고리를 반환해요. limit=bottomN은 하위 N개 카테고리를 반환해요. 한도를 초과하면 나머지 카테고리는 OTHER 카테고리로 그룹화돼요(useother=false가 아닌 경우). 0으로 설정하면 한도 없이 모든 카테고리를 표시해요. 순위는 각 열 카테고리의 집계 값 합을 기준으로 해요. 예를 들어 limit=top3는 총 값이 가장 높은 세 카테고리를 유지해요. 두 필드로 그룹화할 때만 적용돼요. top10
useother Optional limit를 초과하는 카테고리에 대해 OTHER 카테고리를 만들지 제어해요. false로 설정하면 OTHER 카테고리 없이 상위 또는 하위 N개 카테고리만 표시돼요(limit 기준). true로 설정하면 limit를 초과하는 카테고리가 OTHER 카테고리로 그룹화돼요. 이 매개변수는 열 분할을 사용하고 limit보다 많은 카테고리가 있을 때만 적용돼요. true
usenull Optional 열 분할 필드에 null 값이 있는 문서를 별도의 NULL 카테고리로 그룹화할지 제어해요. 이 매개변수는 열 분할에만 적용돼요. 행 분할 필드에 null 값이 있는 문서는 무시되며, 행 분할 필드에 null이 아닌 값이 있는 문서만 결과에 포함돼요. usenull=false일 때 열 분할 필드에 null 값이 있는 문서는 결과에서 제외돼요. usenull=true일 때 열 분할 필드에 null 값이 있는 문서는 별도의 NULL 카테고리로 그룹화돼요. true
nullstr Optional 열 분할 필드에 null 값이 있는 문서의 카테고리 이름을 지정해요. 이 매개변수는 usenull이 true일 때만 적용돼요. "NULL"
otherstr Optional OTHER 카테고리의 카테고리 이름을 지정해요. 이 매개변수는 useother가 true이고 limit를 초과하는 값이 있을 때만 적용돼요. OTHER

참고 사항(Notes)

chart 명령을 사용할 때 다음 사항이 적용돼요.

  • 열 분할로 생성된 필드는 문자열로 변환돼요. 이는 nullstr 및 otherstr과의 호환성을 보장하고 피벗 후 필드를 열 이름으로 사용할 수 있게 해줘요.
  • 집계 함수가 사용하는 필드에 null 값이 있는 문서는 집계에서 제외돼요. 예를 들어 chart avg(balance) over deptno, group에서 balance가 null인 문서는 평균 계산에서 제외돼요.
  • 집계 메트릭은 결과의 마지막 열로 나타나요. 결과 열은 다음과 같이 정렬돼요: [행 분할] [열 분할] [집계 메트릭].

예시 1: 그룹화 없는 기본 집계

이 예시는 로그 항목의 총 개수를 계산해요.

source=otellogs
| chart count() as total_logs

이 쿼리는 다음과 같은 결과를 반환해요.

total_logs
20

예시 2: 단일 필드로 그룹화

이 예시는 심각도 수준별 로그 수를 계산하며, 심각도 분포 파이 차트에 유용해요.

source=otellogs
| chart count() by severityText

이 쿼리는 다음과 같은 결과를 반환해요.

severityText count()
DEBUG 3
ERROR 7
INFO 6
WARN 4

예시 3: over [] by []를 사용해 여러 필드로 그룹화

다음 쿼리는 심각도 수준과 서비스별 로그 수를 보여주는 2차원 차트를 만들어요. 히트맵 시각화에 이상적이에요.

source=otellogs
| chart limit=2 count() over severityText by `resource.attributes.service.name`

이 쿼리는 다음과 같은 결과를 반환해요. 상위 2개를 초과하는 서비스는 OTHER로 그룹화돼요.

severityText resource.attributes.service.name count()
DEBUG OTHER 2
DEBUG product-catalog 1
ERROR OTHER 6
ERROR product-catalog 1
INFO OTHER 2
INFO frontend 4
WARN OTHER 2
WARN product-catalog 2

예시 4: 사용자 정의 other 레이블과 limit 사용

다음 쿼리는 심각도 수준별 상위 1개 서비스로 제한하고 나머지를 other_services로 레이블을 붙여요.

source=otellogs
| chart limit=top1 useother=true otherstr='other_services' count() over severityText by `resource.attributes.service.name`

이 쿼리는 다음과 같은 결과를 반환해요.

severityText resource.attributes.service.name count()
DEBUG other_services 3
ERROR other_services 7
INFO frontend 4
INFO other_services 2
WARN other_services 4

예시 5: null 매개변수 사용

다음 쿼리는 네임스페이스별 서비스 로그 수를 보여주며, 네임스페이스가 없는 서비스를 no namespace로 레이블을 붙여요.

source=otellogs
| chart usenull=true nullstr='not instrumented' count() over `resource.attributes.service.name` by instrumentationScope.name

이 쿼리는 다음과 같은 결과를 반환해요.

resource.attributes.service.name instrumentationScope.name count()
cart Microsoft.Extensions.Hosting 1
cart not instrumented 2
checkout not instrumented 3
frontend @opentelemetry/instrumentation-http 1
frontend not instrumented 3
frontend-proxy not instrumented 3
payment @opentelemetry/instrumentation-http 1
payment not instrumented 1
product-catalog go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc 1
product-catalog not instrumented 3
recommendation not instrumented 1

예시 6: span 사용

다음 쿼리는 심각도 범위와 호스트별 최대 심각도를 차트로 표시하며, 가장 중요한 이슈를 겪는 호스트를 식별하는 데 유용해요.

source=otellogs
| chart max(severityNumber) by severityNumber span=10, `resource.attributes.host.name`

이 쿼리는 다음과 같은 결과를 반환해요.

severityNumber resource.attributes.host.name max(severityNumber)
0 cart-5d8f7b-mk29s 9
0 checkout-8b4c2d-jp5r7 9
0 frontend-6b7b4c9f-x2kl9 9
0 productcatalog-7c9d-zn4p2 5
10 checkout-8b4c2d-jp5r7 17
10 frontendproxy-envoy-7d4b8c-xk2q9 17
10 payment-6f8d4b-ht7q3 17
10 productcatalog-7c9d-zn4p2 17
10 recommendation-5f7c-bn3k8 17

제한 사항(Limitations)

chart 명령에는 다음과 같은 제한 사항이 있어요.

  • chart 명령당 단일 집계 함수만 지원돼요.

더 알아보기 (Learn more)