Elasticsearch 데이터 소스 구성

Elasticsearch 데이터 소스 구성 (Configure)

Grafana에는 Elasticsearch 데이터 소스가 기본 설치되어 있어요. Elasticsearch에 저장된 로그나 지표를 시각화하는 다양한 쿼리를 만들고, Elasticsearch에 저장된 로그 이벤트로 그래프에 어노테이션을 표시할 수 있어요. 독립 플러그인 업데이트에 대한 자세한 내용은 플러그인 업데이트를 참고하세요.

출처: Configure the Elasticsearch data source

본문

Grafana에 데이터 소스를 추가하는 방법은 관리 문서를 참고하세요. 관리자는 Grafana 프로비저닝 시스템으로 YAML을 통해 데이터 소스를 구성할 수도 있어요.

시작하기 전에

Elasticsearch 데이터 소스를 구성하려면 다음이 필요해요.

• Grafana 관리자 권한: 조직 administrator 역할이 있는 사용자만 데이터 소스를 추가할 수 있어요.
• 지원되는 Elasticsearch 버전: v7.17 이상, v8.x, v9.x 또는 Elastic Cloud Serverless.
• Elasticsearch 서버 URL: Elasticsearch 인스턴스의 HTTP 또는 HTTPS 엔드포인트(포트 포함, 기본값: 9200).
• 인증 자격 증명: Elasticsearch 보안 구성에 따라 다음 중 하나가 필요해요.
  • 기본 인증용 사용자 이름과 비밀번호
  • API 키
  • 자격 증명 없음(Elasticsearch 보안이 비활성화된 경우)
• 네트워크 접근: Grafana가 Elasticsearch 서버에 도달할 수 있어야 해요. Grafana Cloud에서 Elasticsearch 인스턴스가 프라이빗 네트워크에 있다면 Private data source connect (PDC)를 고려하세요.

Elasticsearch 권한

Elasticsearch 보안 기능이 활성화되면 Grafana가 연결에 사용하는 사용자 또는 API 키에 다음 클러스터 권한을 구성해야 해요.

• monitor - 연결 상태 확인에 필요. _cluster/health 엔드포인트에 대한 접근을 부여하고 연결된 Elasticsearch 인스턴스의 버전 정보를 가져와요.
• view_index_metadata - 인덱스의 매핑 정의에 접근하는 데 필요.
• read - 인덱스에 대한 검색·검색 작업을 수행할 수 있는 능력을 부여. 클러스터에서 데이터를 질의·추출하는 데 필수적.

데이터 소스 추가

Elasticsearch 데이터 소스를 추가하려면:

1. 왼쪽 메뉴에서 Connections를 클릭해요.
2. Connections에서 Add new connection을 클릭해요.
3. 검색창에 Elasticsearch를 입력해요.
4. Data source 섹션에서 Elasticsearch를 클릭해요.
5. 오른쪽 위에서 Add new data source를 클릭해요.

Elasticsearch 구성을 설정하는 Settings 탭으로 이동해요.

구성 옵션

Elasticsearch 데이터 소스의 다음 기본 설정을 구성해요.

• Name - 데이터 소스 이름. 패널과 쿼리에서 데이터 소스를 참조하는 이름이에요. 예: elastic-1, elasticsearch_metrics
• Default - 토글을 켜서 기본 데이터 소스로 만들어요. 새 패널과 Explore 쿼리는 기본 데이터 소스를 사용해요.

연결 (Connection)

Grafana가 Elasticsearch 클러스터에 도달하는 HTTP 엔드포인트를 설정해요.

• URL - 포트를 포함한 Elasticsearch 서버의 URL. 예: http://localhost:9200, http://elasticsearch.example.com:9200

인증 (Authentication)

Grafana가 Elasticsearch에 인증하는 방법을 선택해요. 드롭다운 메뉴에서 인증 방법을 선택해요.

• Basic authentication - Elasticsearch 사용자의 사용자 이름과 비밀번호를 입력해요.
• Forward OAuth identity - 데이터 소스를 질의하는 사용자의 OAuth 액세스 토큰(사용 가능하면 OIDC ID 토큰)을 전달해요.
• No authentication - 자격 증명 없이 연결해요. Elasticsearch 인스턴스가 인증을 요구하지 않는 경우에만 사용해요.
• Serverless API Key - Elastic serverless 인스턴스에 연결할 API 키를 입력해요. API 키를 찾거나 생성하는 방법은 Elastic Cloud API keys를 참고해요.

API 키 인증

Elasticsearch API 키로 인증하려면 No authentication을 선택하고 HTTP 헤더로 API 키를 구성해요.

1. HTTP headers 섹션에서 + Add header를 클릭해요.
2. Header를 Authorization으로 설정해요.
3. Value를 ApiKey <your-api-key>로 설정하고 <your-api-key>를 base64로 인코딩된 Elasticsearch API 키로 바꿔요.

API 키 생성에 대한 정보는 Elasticsearch API keys 문서를 참고하세요.

Amazon OpenSearch Service 및 SigV4

Amazon OpenSearch Service는 Amazon Elasticsearch Service의 후속작이에요. Amazon OpenSearch Service에는 이 Elasticsearch 데이터 소스 대신 OpenSearch 데이터 소스를 사용하세요.

AWS Signature Version 4(AWS SigV4)를 요구하는 도메인(예: 레거시 Amazon Elasticsearch Service 도메인 또는 다른 SigV4 보호 OpenSearch 호환 엔드포인트)에 Grafana Elasticsearch 데이터 소스를 연결한다면 모든 요청에 SigV4로 서명해야 해요.

AWS SigV4에 대한 자세한 내용은 AWS 문서를 참고하세요. 요청에 서명하려면 Grafana 구성에서 SigV4를 활성화해요. SigV4가 활성화된 후 Elasticsearch 데이터 소스 구성 페이지에서 구성해요. AWS 인증 옵션에 대한 자세한 내용은 AWS authentication을 참고하세요.

TLS 설정

참고: Elasticsearch와 작업할 때 TLS(Transport Layer Security)를 사용해 보안 계층을 추가하세요. Elasticsearch로 TLS 암호화를 설정하는 방법은 Configure TLS를 참고하세요. Grafana에서 이러한 옵션을 설정하기 전에 Elasticsearch 구성 파일에 TLS 설정을 추가해야 해요.

• Add self-signed certificate - CA 인증서로 인증하려면 체크해요. CA(Certificate Authority) 지침에 따라 인증서 파일을 다운로드해요. 자체 서명 TLS 인증서 검증에 필요.
• TLS client authentication - 서버가 클라이언트를 인증하는 TLS 클라이언트로 인증하려면 체크해요. Server name, Client certificate, Client key를 추가해요. ServerName은 반환된 인증서의 호스트 이름 검증에 사용돼요. Client certificate는 CA에서 생성되거나 자체 서명일 수 있어요. Client key도 CA에서 생성되거나 자체 서명일 수 있어요. 클라이언트 키는 클라이언트와 서버 사이의 데이터를 암호화해요.
• Skip TLS certificate validation - TLS 인증서 검증을 건너뛰려면 체크해요. 반드시 필요할 때나 테스트 목적 외에는 TLS 인증서 검증을 건너뛰는 것을 권장하지 않아요.

HTTP 헤더

+ Add header를 클릭해 HTTP 헤더를 하나 이상 추가해요. HTTP 헤더는 요청/응답에 대한 추가 컨텍스트와 메타데이터를 전달해요.

• Header - 커스텀 헤더를 추가해요. Elasticsearch 인스턴스의 요구에 따라 커스텀 헤더를 전달할 수 있게 해요.
• Value - 헤더의 값.

추가 설정

추가 설정은 데이터 소스를 더 세밀하게 제어하기 위해 구성할 수 있는 선택 설정이에요.

고급 HTTP 설정

• Allowed cookies - 데이터 소스로 전달해야 하는 쿠키를 이름으로 지정해요. Grafana 프록시는 기본적으로 모든 전달 쿠키를 삭제해요.
• Timeout - HTTP 요청 타임아웃. 초 단위여야 해요. 기본값이 없으므로 직접 설정해요.

Elasticsearch 세부 설정

다음 설정은 Elasticsearch 데이터 소스에 특화된 설정이에요.

• Index name - Elasticsearch 인덱스 이름. 다음 형식을 사용할 수 있어요.
  • 와일드카드 패턴 - *를 사용해 여러 인덱스를 매칭해요. 예: logs-*, metrics-*, filebeat-*
  • 시간 패턴 - 시간 기반 인덱스에 날짜 자리 표시자를 사용해요. 고정 부분을 대괄호로 감싸요. 예: [logstash-]YYYY.MM.DD, [metrics-]YYYY.MM
  • 특정 인덱스 - 정확한 인덱스 이름을 입력해요. 예: application-logs
  • 크로스 클러스터 검색 - Elasticsearch에 구성된 원격 클러스터를 질의하려면 cluster:index 패턴을 사용해요. 예: logs-cluster:logs-*. 크로스 클러스터 검색은 항상 사용 가능해요. 기능 토글이 필요 없어요.
• Pattern - 인덱스 이름에 시간 패턴을 사용한다면 일치 패턴을 선택해요. 옵션:
  • no pattern
  • hourly
  • daily
  • weekly
  • monthly
  • yearly

Index name 필드에 시간 패턴을 지정한 경우에만 패턴 옵션을 선택해요.

• Time field name - 시간 필드의 이름. 기본값은 @timestamp. 다른 이름을 입력할 수 있어요.
• Max concurrent shard requests - 동시에 질의되는 샤드 수를 설정해요. 기본값은 5. 샤드에 대한 자세한 내용은 Elasticsearch 문서 참고.
• Min time interval - 자동 group-by 시간 간격의 하한을 정의해요. 이 값은 반드시 숫자 다음에 유효한 시간 식별자가 오는 형식이어야 해요.

Identifier	Description
y	year
M	month
w	week
d	day
h	hour
m	minute
s	second
ms	millisecond

이 값을 Elasticsearch 쓰기 빈도와 일치시키는 것을 권장해요. 예를 들어 Elasticsearch가 매분 데이터를 쓰면 1m으로 설정해요. 이 설정은 대시보드 패널의 데이터 소스 옵션에서도 재정의할 수 있어요. 기본값은 10s예요.

• X-Pack enabled - X-Pack 특정 기능과 옵션을 활성화하려면 토글해요. 쿼리 편집기에 Rate, Top Metrics 같은 추가 집계를 제공해요.
• Include frozen indices - X-Pack enabled 설정이 활성화되어 있을 때 켜요. 검색에 frozen 인덱스를 포함해요. 검색 요청을 수행할 때 Grafana가 frozen 인덱스를 포함하도록 구성할 수 있어요.

참고: Frozen 인덱스는 v7.14부터 Elasticsearch에서 비권장(deprecated)됐어요.

로그 (Logs)

데이터 소스가 로그 메시지와 로그 레벨에 사용하는 필드를 구성해요.

• Message field name - 로그 메시지 내용을 담은 필드.
• Level field name - 로그 레벨 또는 심각도 정보를 담은 필드. 지정하면 Grafana가 이 필드로 로그 레벨을 결정하고 각 로그 라인에 색상을 지정해요. 로그에 레벨 필드가 없으면 Grafana는 내용을 지원 표현식과 매칭해 보려 해요. 로그 레벨을 결정할 수 없으면 unknown으로 표시해요.

데이터 링크 (Data links)

데이터 링크는 Explore 로그 보기에서 접근할 수 있는 지정 필드에서 링크를 만들어요. + Add를 클릭해 데이터 링크를 여러 개 추가할 수 있어요.

각 데이터 링크 구성은 다음으로 이루어져요.

• Field - 데이터 링크가 사용하는 필드 이름.
• URL/query - 링크가 외부라면 전체 링크 URL을 설정해요. 내부 링크라면 이 입력은 대상 데이터 소스에 대한 쿼리 역할을 해요. 두 경우 모두 ${__value.raw} 매크로로 필드 값을 보간할 수 있어요.
• URL Label (선택) - 링크의 커스텀 표시 라벨을 설정해요. 링크 라벨은 기본적으로 전체 외부 URL 또는 연결된 내부 데이터 소스 이름이며 이 설정으로 재정의돼요.
• Internal link - 내부 링크로 설정하려면 켜요. 내부 링크의 경우 데이터 소스 선택기로 대상 데이터 소스를 선택할 수 있어요. 추적(tracing) 데이터 소스만 지원돼요.

Private data source connect (PDC) 및 Elasticsearch

PDC를 사용해 보안 네트워크 내 데이터에 Grafana Cloud의 인바운드 트래픽으로 그 네트워크를 열지 않고 연결·질의할 수 있어요. PDC 작동 방식은 Private data source connect를, PDC 연결 설정 단계는 Configure Grafana private data source connect (PDC)를 참고하세요.

PDC를 SigV4(AWS Signature Version 4 Authentication)와 함께 사용한다면 PDC 에이전트가 sts.<region>.amazonaws.com:443로의 인터넷 이그레스를 허용해야 해요.

• Private data source connect - 상자에 클릭해 드롭다운에서 기본 PDC 연결을 설정하거나 새 연결을 만들어요.

Elasticsearch 데이터 소스 옵션을 구성한 뒤 Save & test를 클릭해 연결을 테스트해요. 성공적인 연결은 다음 메시지를 표시해요.

Elasticsearch data source is healthy.

데이터 소스 프로비저닝

Grafana 프로비저닝 시스템의 일부로 YAML 파일에서 데이터 소스를 정의·구성할 수 있어요. 프로비저닝과 사용 가능한 구성 옵션에 대한 자세한 내용은 Provisioning Grafana를 참고하세요.

참고: 이전에 사용하던 database 필드는 이제 비권장됐어요. 인덱스 이름을 저장하려면 jsonData의 index 필드를 사용하세요. 아래 예시를 참고하세요.

기본 프로비저닝

apiVersion: 1

datasources:
  - name: Elastic
    type: elasticsearch
    access: proxy
    url: http://localhost:9200
    jsonData:
      index: '[metrics-]YYYY.MM.DD'
      interval: Daily
      timeField: '@timestamp'

로그용 프로비저닝

apiVersion: 1

datasources:
  - name: elasticsearch-v7-filebeat
    type: elasticsearch
    access: proxy
    url: http://localhost:9200
    jsonData:
      index: '[filebeat-]YYYY.MM.DD'
      interval: Daily
      timeField: '@timestamp'
      logMessageField: message
      logLevelField: fields.level
      dataLinks:
        - datasourceUid: my_jaeger_uid # Target UID needs to be known
          field: traceID
          url: '$${__value.raw}' # Careful about the double "$$" because of env var expansion

Terraform으로 데이터 소스 프로비저닝

Terraform과 Grafana Terraform provider로 Elasticsearch 데이터 소스를 프로비저닝할 수 있어요. Terraform으로 리소스를 프로비저닝하는 방법은 Grafana as code using Terraform 문서를 참고하세요.

기본 Terraform 예시

다음 예시는 메트릭용 기본 Elasticsearch 데이터 소스를 만들어요.

resource "grafana_data_source" "elasticsearch" {
  name = "Elasticsearch"
  type = "elasticsearch"
  url  = "http://localhost:9200"

  json_data_encoded = jsonencode({
    index     = "[metrics-]YYYY.MM.DD"
    interval  = "Daily"
    timeField = "@timestamp"
  })
}

로그용 Terraform 예시

다음 예시는 Jaeger에 대한 데이터 링크가 있는 로그용 Elasticsearch 데이터 소스를 만들어요.

resource "grafana_data_source" "elasticsearch_logs" {
  name = "Elasticsearch Logs"
  type = "elasticsearch"
  url  = "http://localhost:9200"

  json_data_encoded = jsonencode({
    index           = "[filebeat-]YYYY.MM.DD"
    interval        = "Daily"
    timeField       = "@timestamp"
    logMessageField = "message"
    logLevelField   = "fields.level"
    dataLinks = [
      {
        datasourceUid = grafana_data_source.jaeger.uid
        field         = "traceID"
        url           = "$${__value.raw}"
      }
    ]
  })
}

기본 인증이 있는 Terraform 예시

다음 예시는 기본 인증을 포함해요.

resource "grafana_data_source" "elasticsearch_auth" {
  name = "Elasticsearch"
  type = "elasticsearch"
  url  = "http://localhost:9200"

  basic_auth_enabled  = true
  basic_auth_username = "elastic_user"

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = var.elasticsearch_password
  })

  json_data_encoded = jsonencode({
    index     = "[metrics-]YYYY.MM.DD"
    interval  = "Daily"
    timeField = "@timestamp"
  })
}

사용 가능한 모든 구성 옵션은 Grafana provider data source resource documentation을 참고하세요.

더 알아보기 (Learn more)

• Elasticsearch query editor - 쿼리 편집기
• Elasticsearch data source overview - 데이터 소스 개요
• Provisioning Grafana - 프로비저닝
• Configure TLS - TLS 설정
• Configure the Elasticsearch data source - 원문 문서