InfluxDB 데이터 소스 구성

InfluxDB 데이터 소스 구성 (Configure)

이 문서는 InfluxDB 데이터 소스를 구성하는 방법과 사용 가능한 구성 옵션을 설명해요. Grafana는 InfluxDB에 SQL, InfluxQL, Flux의 세 가지 쿼리 언어 중 하나를 사용해 연결할 수 있어요.

출처: Configure the InfluxDB data source

본문

핵심 개념

InfluxDB가 처음이라면 구성 전체에서 사용되는 다음 용어를 알아두세요.

용어	설명
Bucket	InfluxDB 2.x와 3.x에서 시계열 데이터가 저장되는 이름 있는 위치. 1.x의 database와 동일
Organization	사용자, 버킷, 대시보드를 그룹화하는 InfluxDB 2.x 워크스페이스
DBRP mapping	InfluxQL 쿼리가 InfluxDB 2.x 버킷에 대해 동작하게 하는 Database and Retention Policy 매핑
Measurement	관계형 데이터베이스의 테이블과 유사한 InfluxDB의 필드·태그·타임스탬프 논리적 그룹화
Retention policy	자동 삭제 전 데이터가 유지되는 기간을 정의하는 InfluxDB 1.x 설정
Token	2.x와 3.x에서 InfluxDB API에 접근하는 데 사용되는 인증 자격 증명

시작하기 전에

InfluxDB 데이터 소스를 구성하려면 Administrator 역할이 있어야 해요.

Grafana와 Grafana Cloud는 호스팅된 InfluxDB 서비스를 제공하지 않아요. 데이터 소스는 직접 운영·관리하는 InfluxDB 인스턴스나 InfluxData의 클라우드 제품 중 하나에 연결돼요. 데이터 소스를 구성하기 전에 실행 중인 InfluxDB 인스턴스가 있어야 해요.

InfluxData는 세 가지 쿼리 언어를 제공해요.

SQL - InfluxDB 3.x 및 최신 클라우드 제품(Cloud Serverless, Cloud Dedicated, Clustered)용 표준 SQL 쿼리 언어. InfluxData는 새 배포에 SQL을 권장해요. JOIN, 서브쿼리, 표준 SQL 함수를 지원해요. 지원되는 전체 명령문·연산자·함수 목록은 InfluxDB SQL reference 참고.
InfluxQL - InfluxData가 개발한 SQL 유사 쿼리 언어. 모든 InfluxDB 버전에서 사용 가능. InfluxQL은 JOIN 같은 고급 함수를 지원하지 않아요. 자세한 내용은 InfluxQL reference 참고.
Flux - InfluxDB 2.x용 함수형 데이터 스크립팅 언어. InfluxDB 3.x에서는 Flux가 지원되지 않아요. 기본 가이드는 Query InfluxDB with Flux 참고.

참고: InfluxDB 1.x 또는 2.x에서 3.x로 마이그레이션한다면 InfluxData는 쿼리 언어로 SQL 채택을 권장해요. 데이터와 쿼리 전환은 InfluxData의 마이그레이션 가이드를 참고하세요.

어떤 InfluxDB 제품을 사용 중인지 확실하지 않다면 InfluxData의 InfluxDB 제품 감지 도구를 참고하세요.

InfluxDB 데이터 소스 추가

새 InfluxDB 데이터 소스를 설정하려면:

왼쪽 메뉴에서 Connections를 클릭해요.
Add new connection을 클릭해요.
검색창에 InfluxDB를 입력해요.
InfluxDB 데이터 소스를 선택해요.
오른쪽 위에서 Add new data source를 클릭해요.

참고: 데이터 소스 이름을 바꾸기 전에 필수 연결 설정을 완료하고 Save & test를 클릭하세요. 새 데이터 소스를 저장하기 전에 이름을 바꾸면 URL 필드가 아직 비어 있어 Grafana가 전체 구성을 검증하고 오류를 반환해요.

Grafana가 데이터 소스를 구성하는 Settings 탭을 열어요. 왼쪽 사이드바는 각 구성 섹션으로의 탐색 링크를 표시해요.

URL 및 인증
데이터베이스 설정
Private data source connect(선택, Grafana Cloud 전용)
Save & test

구성 옵션

다음 섹션은 사용 가능한 구성 옵션을 설명해요.

첫 번째로 연결 이름을 구성해요.

Name - 패널과 쿼리에서 데이터 소스를 참조할 때 쓰는 이름. 예: InfluxDB-InfluxQL, InfluxDB_SQL
Default - 기본 데이터 소스로 설정하려면 토글.

URL 및 인증

이 설정으로 데이터 소스가 연결할 InfluxDB 인스턴스를 지정해요.

URL - InfluxDB API의 HTTP 프로토콜, IP 주소, 포트. InfluxDB 기본 API 포트는 8086. URL을 입력하면 Grafana가 URL 패턴을 기반으로 InfluxDB 제품을 자동 감지하려 해요. 자세한 내용은 InfluxDB detection 참고.
Product - 연결할 InfluxDB 제품을 선택해요. 사용 가능한 쿼리 언어는 제품 선택에 따라 달라져요.
Query language - InfluxDB 인스턴스의 쿼리 언어를 선택해요. 이는 Database settings에 필요한 연결 세부 정보를 결정해요. 사용 가능한 옵션:
- Flux - 데이터를 질의·분석·조치할 수 있게 하는 InfluxData의 데이터 스크립팅 언어. Flux 사용 가이드는 Get started with Flux 참고.
- InfluxQL - SQL 사용자에게 익숙한 SELECT, FROM, WHERE, GROUP BY 문이 있는 SQL 유사 쿼리 언어.
- SQL - InfluxDB v3.0부터 시작되는 네이티브 SQL 언어. 지원되는 명령문·연산자·함수 목록은 InfluxData의 SQL reference documentation 참고.

다음 표는 각 InfluxDB 제품에 대해 사용 가능한 쿼리 언어를 보여줘요.

제품	지원 쿼리 언어
InfluxDB Cloud Dedicated	SQL, InfluxQL
InfluxDB Cloud Serverless	SQL, InfluxQL, Flux
InfluxDB Clustered	SQL, InfluxQL
InfluxDB Enterprise 1.x	InfluxQL, Flux
InfluxDB Enterprise 3.x	SQL, InfluxQL
InfluxDB Cloud (TSM)	InfluxQL, Flux
InfluxDB Cloud 1	InfluxQL
InfluxDB OSS 1.x	InfluxQL, Flux
InfluxDB OSS 2.x	InfluxQL, Flux
InfluxDB OSS 3.x	SQL, InfluxQL

참고: InfluxQL 전용. Database + Retention Policy (DBRP) Mapping은 다음 제품에서 데이터를 질의하기 전에 구성해야 해요: InfluxDB OSS 1.x, InfluxDB OSS 2.x, InfluxDB Enterprise 1.x, InfluxDB Cloud (TSM), InfluxDB Cloud Serverless. CLI나 API로 설정하는 방법은 Manage DBRP Mappings 참고.

고급 HTTP 설정

Advanced HTTP Settings를 토글해 데이터 소스를 더 세밀하게 제어하는 옵션을 펼쳐요.

Allowed cookies - 데이터 소스로 전달할 쿠키를 정의해요. 다른 모든 쿠키는 기본적으로 삭제돼요.
Timeout - HTTP 요청 타임아웃을 초 단위로 설정해요. 값을 설정하지 않으면 Grafana는 구성 파일의 dataproxy 섹션에 있는 timeout 설정(기본 30초)을 사용해요. 복잡한 쿼리나 큰 결과 집합이 context deadline exceeded 같은 타임아웃 오류로 실패하면 이 값을 늘려요. 알림 규칙 평가도 같은 타임아웃을 사용하므로, 늘리면 알림 쿼리에도 더 많은 시간이 주어져요.

Custom HTTP headers

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

Header - 커스텀 HTTP 헤더를 추가해요. 드롭다운에서 옵션을 선택해요. InfluxDB 인스턴스의 요구에 따라 커스텀 헤더를 전달할 수 있어요.
Value - 헤더의 값.

인증 및 TLS/SSL 설정

Auth and TLS/SSL Settings를 토글해 인증과 보안 옵션을 펼쳐요.

No Authentication - 인증 없이 데이터 소스를 사용 가능하게 해요. Grafana는 일부 인증 방법을 사용할 것을 권장해요.
Basic auth - 가장 일반적인 인증 방법. InfluxDB 인스턴스의 사용자 이름과 비밀번호로 인증해요.
Forward OAuth identity - 데이터 소스를 질의하는 사용자의 OAuth 액세스 토큰(사용 가능하면 OIDC ID 토큰도)을 전달해요.
With credentials - 쿠키나 인증 헤더 같은 자격 증명을 크로스 사이트 요청과 함께 보낼 수 있게 토글.

TLS/SSL 인증서는 암호화되어 Grafana 데이터베이스에 저장돼요.

TLS client auth - 활성화하면 Server name, Client cert, Client key를 추가해요. 클라이언트는 서버가 검증해 클라이언트의 신뢰된 신원을 확인하는 인증서를 제공해요. 클라이언트 키는 클라이언트와 서버 사이의 데이터를 암호화해요.
- Server name - 서버 이름. 예: server1.domain.com
- Client cert - 클라이언트 인증서를 추가해요.
- Client key - 클라이언트 키를 추가해요.
CA cert - CA 인증서로 인증해요. 활성화하면 CA(Certificate Authority) 지침에 따라 인증서 파일을 다운로드해요.
Skip TLS verify - TLS 인증서 검증을 건너뛰려면 토글.

데이터베이스 설정

참고: 이 데이터 소스에 데이터베이스를 설정한다고 다른 데이터베이스에 대한 접근을 거부하지는 않아요. InfluxDB 쿼리 문법은 쿼리에서 데이터베이스를 전환할 수 있게 해요. 예: SHOW MEASUREMENTS ON _internal 또는 SELECT * FROM "_internal".."database" LIMIT 10. 데이터 격리와 보안을 지원하려면 InfluxDB에서 적절한 권한을 구성하세요.

이 설정으로 데이터 소스가 연결할 InfluxDB 데이터베이스를 지정해요. 필요한 필드는 URL and authentication에서 선택한 쿼리 언어에 따라 달라져요.

다음 표는 각 쿼리 언어에 필요한 필드를 보여줘요.

설정	Flux	InfluxQL	SQL
Organization	✓
Default Bucket	✓
Database		✓	✓
User		✓
Password		✓
Token	✓		✓

Organization - Flux 쿼리에 사용되는 InfluxDB organization. v.organization 쿼리 매크로에도 사용돼요.
Default Bucket - Flux 쿼리의 v.defaultBucket 매크로에 사용되는 InfluxDB bucket.
Database - 질의할 데이터베이스 이름을 설정해요. 사용 가능한 버킷 목록과 해당 ID를 찾는 방법은 InfluxData 문서의 View buckets 참고.
User - InfluxDB에 로그인하는 데 사용되는 사용자 이름.
Password - 지정된 사용자의 비밀번호. InfluxQL 쿼리와 함께 사용.
Token - InfluxDB를 질의하는 데 사용되는 인증 토큰. InfluxDB UI의 Tokens page에서 가져와요.

SQL용

Database 필드는 InfluxDB 3.x 데이터베이스(버킷과 동일)에 매핑돼요.
대상 데이터베이스에 대한 읽기 권한이 있는 database token을 사용해요. InfluxDB Cloud Serverless와 Cloud Dedicated의 경우 InfluxDB 관리 콘솔이나 CLI에서 토큰을 생성해요.
SQL 쿼리는 FlightSQL(gRPC) 프로토콜을 사용해요. InfluxDB 인스턴스가 TLS를 사용하지 않는다면 Advanced Database Settings에서 Insecure Connection을 활성화해요.

Flux용

InfluxDB 2.x 제품에서는 InfluxDB 인증 토큰을 사용해요.
InfluxDB 1.8에서는 토큰이 username:password예요.

고급 데이터베이스 설정

Advanced Database Settings를 토글해 쿼리 환경을 더 제어하는 옵션을 펼쳐요.

Max series - Grafana가 처리하는 시리즈 또는 테이블의 최대 수를 제한해요. 시스템 과부하를 방지하려면 더 낮은 한도를 설정하거나, 많고 작은 시계열이 있고 더 많이 표시해야 한다면 늘려요. 기본값은 1000.

Flux 및 InfluxQL용

Min time interval - 자동 group-by의 최소 시간 간격을 설정해요. Grafana는 이를 데이터 쓰기 빈도와 일치시키는 것을 권장해요. 예를 들어 데이터가 매분 쓰인다면 간격을 1분으로 설정해 각 그룹이 각 새 쓰기의 데이터를 포함하게 해요. 기본값은 10s. 형식 예시는 Min time interval 참고.

InfluxQL용

HTTP method - 데이터 소스를 질의하는 데 사용되는 HTTP 메서드를 설정해요. POST 메서드는 GET 메서드를 사용하면 오류를 반환하는 더 큰 쿼리를 허용해요. 기본 메서드는 POST.
Autocomplete range - 태그 필터 쿼리의 실행 시간을 줄이기 위한 쿼리 편집기 자동 완성의 시간 범위 제한을 설정해요. 정의된 시간 범위 내에 없는 태그는 필터링돼요. 예를 들어 12h로 설정하면 지난 12시간의 태그 키와 값만 포함해요. 이 기능은 큰 성능 개선이 관찰되는 매우 큰 데이터베이스에 권장돼요.

SQL용

Insecure Connection - gRPC TLS 보안을 비활성화하려면 토글.

Private data source connect

Grafana Cloud 전용. Private data source connect(PDC)는 Grafana Cloud 인스턴스와 프라이빗 네트워크 내에 보안된 데이터 소스 사이에 프라이빗하고 보안된 연결을 구축할 수 있게 해줘요. 자세한 내용은 Private data source connect (PDC) 참고.

Manage private data source connect를 클릭해 PDC 구성 세부 정보가 있는 PDC 연결 페이지로 이동해요.

주의: PDC를 사용할 때 InfluxDB URL을 127.0.0.1이나 localhost로 설정하지 마세요. PDC는 SOCKS 프록시를 통해 트래픽을 터널링하는데, 이 프록시는 루프백 주소를 확인할 수 없어요. PDC 에이전트가 실행되는 네트워크에서 확인 가능한 머신의 LAN IP 주소나 호스트 이름을 사용하세요. 자세한 내용은 PDC connection fails with "no such host" 참고.

PDC 에이전트 배포, 프록시 구성, 네트워크·토큰 관리는 여기서 다루지 않고 PDC 문서에서 다뤄요. 설정은 Configure PDC를, 에이전트 오류·로그 해석·장애 모드는 Troubleshoot PDC issues를 참고하세요.

저장 및 테스트

연결 설정을 구성한 뒤 Save & test를 클릭해 데이터 소스 연결을 검증해요. 성공적인 테스트는 쿼리 언어에 따라 다음 메시지 중 하나를 반환해요.

쿼리 언어	성공 메시지
Flux	`datasource is working. X buckets found`
InfluxQL	`datasource is working. X measurements found`
SQL	`OK`

테스트가 실패하면 InfluxDB 데이터 소스 문제 해결을 참고해 일반적인 연결·인증 오류를 해결하세요.

Min time interval

Min time interval 설정은 자동 group-by 시간 간격의 하한을 정의해요. 이 값 반드시 숫자 다음에 유효한 시간 식별자가 오는 형식이어야 해요.

식별자	설명
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

이 설정은 대시보드 패널의 데이터 소스 옵션에서도 재정의할 수 있어요.

InfluxDB 데이터 소스 프로비저닝

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

참고: database 필드는 비권장됐어요. Grafana는 jsonData의 dbName 필드 사용을 권장해요. 기존 프로비저닝 설정을 변경할 필요는 없어요.

프로비저닝 예시

프로비저닝은 쿼리 언어에 따라 달라져요.

InfluxDB 1.x 예시:

apiVersion: 1

datasources:
  - name: InfluxDB_v1
    type: influxdb
    access: proxy
    user: grafana
    url: http://localhost:8086
    jsonData:
      dbName: site
      httpMode: GET
    secureJsonData:
      password: grafana

InfluxDB 2.x Flux용 예시:

apiVersion: 1

datasources:
  - name: InfluxDB_v2_Flux
    type: influxdb
    access: proxy
    url: http://localhost:8086
    jsonData:
      version: Flux
      organization: organization
      defaultBucket: bucket
      tlsSkipVerify: true
    secureJsonData:
      token: token

InfluxDB 2.x InfluxQL용 예시:

apiVersion: 1

datasources:
  - name: InfluxDB_v2_InfluxQL
    type: influxdb
    access: proxy
    url: http://localhost:8086
    jsonData:
      dbName: site
      httpHeaderName1: 'Authorization'
    secureJsonData:
      httpHeaderValue1: 'Token <token>'

InfluxDB 3.x SQL용 예시:

apiVersion: 1

datasources:
  - name: InfluxDB_v3_SQL
    type: influxdb
    access: proxy
    url: http://localhost:8086
    jsonData:
      version: SQL
      dbName: site
      httpMode: POST
      insecureGrpc: false
    secureJsonData:
      token: '<api-token>'

Terraform으로 데이터 소스 구성

Grafana Terraform provider로 InfluxDB 데이터 소스를 구성할 수 있어요.

Terraform 전제 조건

시작하기 전에 다음이 필요해요.

Terraform 설치
적절한 자격 증명으로 구성된 Grafana Terraform provider
Grafana Cloud용: 데이터 소스 권한이 있는 Cloud Access Policy token

프로바이더 구성

Grafana 프로바이더를 구성해 Grafana 인스턴스에 연결해요.

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.0.0"
    }
  }
}

# For Grafana Cloud
provider "grafana" {
  url  = "<YOUR_GRAFANA_CLOUD_STACK_URL>"
  auth = "<YOUR_SERVICE_ACCOUNT_TOKEN>"
}

# For self-hosted Grafana
# provider "grafana" {
#   url  = "http://localhost:3000"
#   auth = "<API_KEY_OR_SERVICE_ACCOUNT_TOKEN>"
# }

Terraform 예시

다음 예시는 각 쿼리 언어에 대한 InfluxDB 데이터 소스 구성 방법을 보여줘요.

InfluxDB 2.x with Flux:

resource "grafana_data_source" "influxdb_flux" {
  type = "influxdb"
  name = "InfluxDB_Flux"
  url  = "http://localhost:8086"

  json_data_encoded = jsonencode({
    version       = "Flux"
    organization  = "<ORGANIZATION>"
    defaultBucket = "<DEFAULT_BUCKET>"
    tlsSkipVerify = false
  })

  secure_json_data_encoded = jsonencode({
    token = "<API_TOKEN>"
  })
}

InfluxDB 1.x with InfluxQL:

resource "grafana_data_source" "influxdb_influxql" {
  type = "influxdb"
  name = "InfluxDB_InfluxQL"
  url  = "http://localhost:8086"

  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  json_data_encoded = jsonencode({
    dbName   = "<DATABASE>"
    httpMode = "POST"
  })

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
  })
}

InfluxDB 2.x with InfluxQL (token auth):

resource "grafana_data_source" "influxdb_v2_influxql" {
  type = "influxdb"
  name = "InfluxDB_v2_InfluxQL"
  url  = "http://localhost:8086"

  json_data_encoded = jsonencode({
    dbName          = "<DATABASE>"
    httpHeaderName1 = "Authorization"
  })

  secure_json_data_encoded = jsonencode({
    httpHeaderValue1 = "Token <API_TOKEN>"
  })
}

InfluxDB 3.x with SQL:

resource "grafana_data_source" "influxdb_sql" {
  type = "influxdb"
  name = "InfluxDB_SQL"
  url  = "http://localhost:8086"

  json_data_encoded = jsonencode({
    version      = "SQL"
    dbName       = "<DATABASE>"
    httpMode     = "POST"
    insecureGrpc = false
  })

  secure_json_data_encoded = jsonencode({
    token = "<API_TOKEN>"
  })
}

Grafana Terraform provider에 대한 자세한 내용은 Terraform provider documentation을 참고하세요.

더 알아보기 (Learn more)

InfluxDB query editor - 쿼리 편집기
InfluxDB data source overview - 데이터 소스 개요
InfluxDB SQL reference - SQL 레퍼런스
InfluxQL reference - InfluxQL 레퍼런스
Configure the InfluxDB data source - 원문 문서