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

Top N queries

원문 보기 위키 갱신

출처: 문서

본문

Top N 쿼리

query insights를 사용해 Top N 쿼리를 모니터링하면 지정된 기간(예: 지난 1시간) 동안 지연 시간이 가장 길거나 리소스 소비가 가장 큰 쿼리를 실시간으로 파악할 수 있어요.

Top N 쿼리 모니터링 구성하기

다음 메트릭 타입별로 Top N 쿼리 모니터링을 구성할 수 있어요:

  • latency
  • cpu
  • memory

각 메트릭에는 그에 대응하는 설정들이 있어요:

예를 들어 CPU 사용량 기준으로 Top N 쿼리 모니터링을 활성화하려면 search.insights.top_queries.cpu.enabled를 true로 설정해요. 동적 설정을 지정하는 방법에 대한 자세한 내용은 Dynamic settings를 참조하세요.

세분화된 API 접근 제어가 필요한 프로덕션 배포(예: 네트워크 세그멘테이션이 적용된 대시보드 노드)에서는 이 페이지에 나오는 Cluster Settings API 대신 Query Insights Settings API를 사용하세요. Query Insights Settings API는 향상된 보안과 간소화된 구조로 동일한 기능을 제공해요. {: .tip}

이 기능은 시스템 리소스를 소비할 수 있으니 활성화할 때 주의해야 해요. {: .important}

Top N 쿼리 모니터링 활성화하기

query-insights 플러그인을 설치하면 Top N 쿼리 모니터링이 기본적으로 활성화돼요. Top N 쿼리 모니터링을 비활성화하려면 원하는 메트릭 타입의 동적 클러스터 설정을 업데이트하세요. 예를 들어 지연 시간 기준 Top N 쿼리 모니터링을 비활성화하려면 search.insights.top_queries.latency.enabled 설정을 업데이트하세요:

PUT _cluster/settings
{
  "persistent" : {
    "search.insights.top_queries.latency.enabled" : false
  }
}

{% include copy-curl.html %}

윈도우 크기 구성하기

모니터링 윈도우 크기를 구성하려면 원하는 메트릭 타입의 window_size 설정을 업데이트하세요. 기본 window_size는 5m이에요. 예를 들어 60분 윈도우로 지연 시간 기준 Top N 쿼리를 수집하려면 search.insights.top_queries.latency.window_size 설정을 업데이트하세요:

PUT _cluster/settings
{
  "persistent" : {
    "search.insights.top_queries.latency.window_size" : "60m"
  }
}

{% include copy-curl.html %}

N 값 구성하기

N 값을 구성하려면 원하는 메트릭 타입의 top_n_size 설정을 업데이트하세요. 기본 top_n_size는 10이에요. 예를 들어 지연 시간 기준 상위 20개 쿼리를 수집하려면 insights.top_queries.latency.top_n_size 설정을 업데이트하세요:

PUT _cluster/settings
{
  "persistent" : {
    "search.insights.top_queries.latency.top_n_size" : 20
  }
}

{% include copy-curl.html %}

소스 잘라내기 구성하기

스토리지 사용량을 최적화하기 위해 Top N 쿼리 레코드에 저장되는 쿼리 소스의 최대 길이(문자 수)를 구성할 수 있어요. 기본 max_source_length는 524288자(1 MB)예요. 예를 들어 소스 길이를 1000자로 제한하려면 search.insights.top_queries.max_source_length 설정을 업데이트하세요:

PUT _cluster/settings
{
  "persistent" : {
    "search.insights.top_queries.max_source_length" : 1000
  }
}

{% include copy-curl.html %}

이 값을 0으로 설정하면 소스가 완전히 잘려서 쿼리 소스 정보가 저장되지 않아요. 소스가 최대 길이를 초과하면 정확히 문자 제한 지점에서 잘리고, 응답의 source_truncated 필드가 true로 설정돼요. {: .note}

현재 Top N 쿼리 모니터링하기

Insights API 엔드포인트를 사용하면 현재 시간 윈도우의 Top N 쿼리를 조회할 수 있어요. 이 API는 기본적으로 latency 기준 Top N 결과를 반환해요.

GET /_insights/top_queries

{% include copy-curl.html %}

쿼리 파라미터

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
type String Top N 쿼리 데이터를 조회할 메트릭 타입이에요. 결과는 이 메트릭 기준으로 내림차순 정렬돼요. 유효한 값은 latency, cpu, memory이며 기본값은 latency예요.
from String 과거 Top N 쿼리를 가져올 시간 범위의 시작 시점이에요. 자세한 내용은 과거 Top N 쿼리 모니터링하기를 참조하세요.
to String 과거 Top N 쿼리를 가져올 시간 범위의 종료 시점이에요. 자세한 내용은 과거 Top N 쿼리 모니터링하기를 참조하세요.
id String 조회하려는 특정 Top 쿼리 레코드의 ID예요.
verbose Boolean 상세 출력을 반환할지 여부를 나타내요. 기본값은 true예요.

응답 예시

응답 {: .text-delta} 
{
  "top_queries" : [
    {
      "timestamp" : 1745021834451,
      "id" : "36506bd2-7bca-4a0a-a6b8-f3e7db2b0745",
      "wlm_group_id" : "DEFAULT_WORKLOAD_GROUP",
      "group_by" : "NONE",
      "indices" : [
        "my-index-0"
      ],
      "source" : """{"size":20,"query":{"bool":{"must":[{"match_phrase":{"message":{"query":"document","slop":0,"zero_terms_query":"NONE","boost":1.0}}},{"match":{"user.id":{"query":"userId","operator":"OR","prefix_length":0,"max_expansions":50,"fuzzy_transpositions":true,"lenient":false,"zero_terms_query":"NONE","auto_generate_synonyms_phrase_query":true,"boost":1.0}}}],"adjust_pure_negative":true,"boost":1.0}}}""",
      "task_resource_usages" : [
        {
          "action" : "indices:data/read/search[phase/query]",
          "taskId" : 28,
          "parentTaskId" : 27,
          "nodeId" : "BBgWzu8QR0qDkR0G45aw8w",
          "taskResourceUsage" : {
            "cpu_time_in_nanos" : 22664000,
            "memory_in_bytes" : 6604536
          }
        },
        {
          "action" : "indices:data/read/search",
          "taskId" : 27,
          "parentTaskId" : -1,
          "nodeId" : "BBgWzu8QR0qDkR0G45aw8w",
          "taskResourceUsage" : {
            "cpu_time_in_nanos" : 119000,
            "memory_in_bytes" : 3920
          }
        }
      ],
      "username" : "admin",
      "failed": false,
      "node_id" : "BBgWzu8QR0qDkR0G45aw8w",
      "phase_latency_map" : {
        "expand" : 0,
        "query" : 23,
        "fetch" : 0
      },
      "labels" : {
        "X-Opaque-Id" : "query-label-1"
      },
      "search_type" : "query_then_fetch",
      "source_truncated" : false,
      "total_shards" : 1,
      "user_roles" : [
        "all_access"
      ],
      "measurements" : {
        "memory" : {
          "number" : 6608456,
          "count" : 1,
          "aggregationType" : "NONE"
        },
        "latency" : {
          "number" : 24,
          "count" : 1,
          "aggregationType" : "NONE"
        },
        "cpu" : {
          "number" : 22783000,
          "count" : 1,
          "aggregationType" : "NONE"
        }
      }
    },
    {
      "timestamp" : 1745021826937,
      "id" : "86e161d0-e982-48c2-b8da-e3a3763f2e36",
      "wlm_group_id" : "DEFAULT_WORKLOAD_GROUP",
      "group_by" : "NONE",
      "indices" : [
        "my-index-*"
      ],
      "source" : """{"size":20,"query":{"term":{"user.id":{"value":"userId","boost":1.0}}}}""",
      "task_resource_usages" : [
        {
          "action" : "indices:data/read/search[phase/query]",
          "taskId" : 26,
          "parentTaskId" : 25,
          "nodeId" : "BBgWzu8QR0qDkR0G45aw8w",
          "taskResourceUsage" : {
            "cpu_time_in_nanos" : 11020000,
            "memory_in_bytes" : 4292272
          }
        },
        {
          "action" : "indices:data/read/search",
          "taskId" : 25,
          "parentTaskId" : -1,
          "nodeId" : "BBgWzu8QR0qDkR0G45aw8w",
          "taskResourceUsage" : {
            "cpu_time_in_nanos" : 1032000,
            "memory_in_bytes" : 115816
          }
        }
      ],
      "username" : "admin",
      "failed": false,
      "node_id" : "BBgWzu8QR0qDkR0G45aw8w",
      "phase_latency_map" : {
        "expand" : 0,
        "query" : 15,
        "fetch" : 1
      },
      "labels" : { },
      "search_type" : "query_then_fetch",
      "source_truncated" : false,
      "total_shards" : 1,
      "user_roles" : [
        "all_access"
      ],
      "measurements" : {
        "memory" : {
          "number" : 4408088,
          "count" : 1,
          "aggregationType" : "NONE"
        },
        "latency" : {
          "number" : 23,
          "count" : 1,
          "aggregationType" : "NONE"
        },
        "cpu" : {
          "number" : 12052000,
          "count" : 1,
          "aggregationType" : "NONE"
        }
      }
    }
  ]
}

쿼리가 결과를 반환하지 않으면 대상 메트릭 타입에 대해 Top N 쿼리 모니터링이 활성화되어 있는지, 그리고 검색 요청이 현재 시간 윈도우 내에서 이루어졌는지 확인하세요. {: .important}

과거 Top N 쿼리 모니터링하기

과거 Top N 결과를 조회하려면 ISO 8601 형식인 YYYY-MM-DD'T'HH:mm:ss.SSSZ로 from과 to 파라미터에 시간 범위를 지정하세요. 예를 들어 2024년 8월 25일 15:00 UTC부터 2024년 8월 30일 17:00 UTC까지의 Top N 쿼리를 조회하려면 다음 요청을 보내세요:

GET /_insights/top_queries?from=2024-08-25T15:00:00.000Z&to=2024-08-30T17:00:00.000Z

{% include copy-curl.html %}

과거 쿼리 데이터를 보려면 exporter 타입이 local_index로 설정되어 있어야 해요. 자세한 내용은 로컬 인덱스 exporter 구성하기를 참조하세요. {: .important}

Top N 쿼리 데이터 내보내기

원하는 exporter를 구성해 Top N 쿼리 데이터를 다양한 싱크로 내보낼 수 있어서 OpenSearch 쿼리를 더 잘 모니터링하고 분석할 수 있어요. 지원되는 exporter는 다음과 같아요:

디버그 exporter 구성하기

디버그 exporter를 사용하려면 exporter 타입을 debug로 설정하세요:

PUT _cluster/settings
{
  "persistent" : {
      "search.insights.top_queries.exporter.type" : "debug"
  }
}

{% include copy-curl.html %}

로컬 인덱스 exporter 구성하기

기본 exporter는 local_index예요. 로컬 인덱스 exporter를 사용하면 Top N 쿼리 데이터를 OpenSearch 도메인에 자동으로 생성되는 인덱스에 저장할 수 있어요. Query Insights는 top_queries-YYYY.MM.dd-hashcode라는 이름 패턴에 따라 이 인덱스들을 생성하는데, 여기서 hashcode는 현재 UTC 날짜를 기반으로 생성된 5자리 숫자예요. 인덱스는 매일 새로 생성돼요. Top Queries API나 Query Insights 대시보드를 사용해 과거 Top N을 조회하려면 로컬 인덱스 exporter를 반드시 활성화해야 해요.

로컬 인덱스 exporter를 사용하려면 exporter 타입을 local_index로 설정하세요:

PUT _cluster/settings
{
  "persistent" : {
    "search.insights.top_queries.exporter.type" : "local_index"
  }
}

{% include copy-curl.html %}

delete_after_days 설정(정수)을 사용하면 로컬 인덱스가 자동으로 삭제되기까지의 일수를 지정할 수 있어요. Query Insights는 매일 00:05 UTC에 작업을 한 번 실행해 지정된 일수보다 오래된 Top N 로컬 인덱스를 삭제해요. delete_after_days의 기본값은 7이고, 유효한 값 범위는 1부터 180까지예요.

예를 들어 10일보다

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.