기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # PostgreSQL 데이터 소스에 연결 PostgreSQL 데이터 소스를 사용하여 Amazon Aurora PostgreSQL 데이터베이스의 데이터를 쿼리하고 시각화할 수 있습니다. **중요** *Grafana 버전 8*에서는 Postgres, MySQL 및 Microsoft SQL Server 데이터 소스의 데이터 프레임에 대한 기본 데이터 구조를 변경합니다. 따라서 시계열 쿼리 결과가 와이드 형식으로 반환됩니다. 자세한 내용은 Grafana 데이터 프레임 설명서의 [Wide format](https://grafana.com/developers/plugin-tools/introduction/data-frames#wide-format)을 참조하세요. 시각화가 버전 8 이전과 같이 작동하려면 몇 가지 수동 마이그레이션을 수행해야 할 수 있습니다. Github([Postgres/MySQL/MSSQL: Breaking change in v8.0 related to time series queries and ordering of data column](https://github.com/grafana/grafana/issues/35534))에서 한 가지 솔루션이 문서화되어 있습니다. *Grafana 버전 9*에서 PostgreSQL 데이터 소스는 이전 버전과 다르게 데이터베이스에 연결하기 위한 루트 인증서를 설정합니다. 워크스페이스를 버전 8에서 9로 업데이트하는 경우 연결 방법을 변경해야 할 수 있습니다. 자세한 정보는 [업데이트된 워크스페이스 관련 문제 해결](AMG-workspace-version-update-troubleshoot.md)을 참조하세요. ## 데이터 소스 추가 1. 상단 헤더에서 Grafana 아이콘을 선택하여 사이드 메뉴를 여세요. 1. 사이드 메뉴에서 **구성** 아이콘 아래에 **데이터 소스** 링크가 있습니다. 1. 상단 헤더에서 **\+ 데이터 소스 추가** 버튼을 선택하세요. 1. **유형** 드롭다운 목록에서 **PostgreSQL**을 선택하세요. ### 데이터 소스 옵션 | 이름 | 설명 | | --- | --- | | Name | 데이터 소스 이름. 패널 및 쿼리에서 데이터 소스를 보는 방법입니다. | | Default | 기본 데이터 소스는 새 패널에 대해 미리 선택됨을 의미합니다. | | Host | PostgreSQL 인스턴스의 IP 주소/호스트 이름 및 선택적 포트. 데이터베이스 이름은 포함하지 마세요. Postgres에 연결하기 위한 연결 문자열이 올바르지 않아 오류가 발생합니다. | | Database | PostgreSQL 데이터베이스의 이름. | | User | 데이터베이스 사용자의 로그인/사용자 이름. | | Password | 데이터베이스 사용자의 암호 | | SSL Mode | 이 옵션은 보안 SSL TCP/IP 연결을 서버와 협상할지 여부 또는 해당 우선순위를 결정합니다. | | Max open | 데이터베이스에 대한 최대 열린 연결 수, 기본값 unlimited(Grafana v5.4 이상). | | Max idle | 유휴 연결 풀의 최대 연결 수, 기본값: 2(Grafana v5.4 이상). | | Max lifetime | 연결을 재사용할 수 있는 최대 시간(초 단위, 기본값 14400/4시간)(Grafana v5.4 이상). | | Version | 이 옵션은 쿼리 빌더에서 사용할 수 있는 함수를 결정합니다(Gafana 5.3 이상에서만 사용 가능). | | TimescaleDB | TimescaleDB는 PostgreSQL 확장으로 빌드된 시계열 데이터베이스입니다. 활성화된 경우 Grafana는 $\_\_timeGroup 매크로에서 time\_bucket을 사용하고 쿼리 빌더에서 TimescaleDB 특정 집계 함수를 표시합니다(Gafana 5.3 이상에서만 사용 가능). | ### 최소 시간 간격 `$_interval` `$_interval_ms` 변수의 하한. 데이터가 1분마다 기록되는 경우 `1m`과 같이 쓰기 빈도로 설정하는 것이 좋습니다. 이 옵션은 대시보드 패널의 데이터 소스 옵션에서 재정의/구성할 수도 있습니다. 이 값은 숫자 및 유효한 시간 식별자의 순서로 형식이 지정되어야 **합니다**(예: `1m`(1분) 또는 `30s`(30초)). 다음 시간 식별자가 지원됩니다. | 식별자 | 설명 | | --- | --- | | y | 연도 | | M | 월 | | w | 주 | | d | 일 | | h | 시간 | | m | 분 | | s | 초 | | ms | 밀리초 | ### 데이터베이스 사용자 권한 **중요** 데이터 소스를 추가할 때 지정하는 데이터베이스 사용자에게는 쿼리하려는 지정된 데이터베이스 및 테이블에 대한 SELECT 권한만 부여해야 합니다. Grafana에서는 쿼리가 안전한지 검증하지 않습니다. 쿼리에는 모든 SQL 문이 포함될 수 있습니다. 예를 들어 `DELETE FROM user;` 및 `DROP TABLE user;`와 같은 명령문이 실행됩니다. 이를 방지하려면 제한된 권한의 특정 PostgreSQL 사용자를 생성하는 것이 좋습니다. 다음 코드 예제에서는 제한된 권한의 특정 PostgreSQL 사용자를 생성하는 방법을 보여줍니다. ``` CREATE USER grafanareader WITH PASSWORD 'password'; GRANT USAGE ON SCHEMA schema TO grafanareader; GRANT SELECT ON schema.table TO grafanareader; ``` 사용자가 퍼블릭 역할에서 원치 않는 권한을 얻지 않도록 해야 합니다. ## 쿼리 편집기 PostgreSQL 쿼리 편집기는 Graph 또는 Singlestat 패널의 편집 모드일 때 지표 탭에서 찾을 수 있습니다. 패널 제목, 편집을 차례로 선택하여 편집 모드로 전환합니다. 쿼리 편집기에는 패널 편집 모드에서 쿼리가 실행된 후 표시되는 **생성된 SQL** 링크가 있습니다. 이를 선택하면 실행된 원시 보간 SQL 문자열이 확장되고 표시됩니다. ### 테이블, 시간 열 및 지표 열 선택(FROM) 처음 편집 모드로 전환하거나 새 쿼리를 추가하면 Grafana는 타임스탬프 열과 숫자 열이 있는 첫 번째 테이블로 쿼리 빌더를 미리 채우려고 시도합니다. FROM 필드에서 Grafana는 데이터베이스 사용자의 `search_path`에 있는 테이블을 제안합니다. `search_path`에 없는 테이블 또는 보기를 선택하려면 `public.metrics`와 같은 정규화된 이름(schema.table)을 수동으로 입력할 수 있습니다. 시간 열 필드는 시간 값을 포함하는 열의 이름을 나타냅니다. 지표 열 필드의 값 선택은 선택 사항입니다. 값을 선택하면 지표 열 필드가 시리즈 이름으로 사용됩니다. 지표 열 제안에는 텍스트 데이터 유형(char,varchar,text)이 있는 열만 포함됩니다. 데이터 유형이 서로 다른 열을 지표 열로 사용하려면 캐스트(`ip::text`)와 함께 열 이름을 입력할 수 있습니다. `hostname || ' ' || container_name`과 같은 텍스트 데이터 유형으로 평가하는 지표 열 필드에 임의의 SQL 표현식을 입력할 수도 있습니다. ### 열, 기간 및 집계 함수(SELECT) `SELECT` 행에서 사용할 열과 함수를 지정할 수 있습니다. 열 필드에서 `column1 * column2 / column3`과 같은 열 이름 대신 임의의 표현식을 작성할 수 있습니다. 쿼리 편집기에서 사용 가능한 함수는 데이터 소스를 구성할 때 선택한 PostgreSQL 버전에 따라 달라집니다. 집계 함수를 사용하는 경우 결과 세트를 그룹화해야 합니다. 집계 함수를 추가하면 편집기가 자동으로 `GROUP BY time`을 추가합니다. 편집기는 쿼리의 이 부분을 단순화하고 통합하려고 합니다. 더하기 버튼을 선택하고 메뉴에서 **열**을 선택하여 값 열을 더 추가할 수 있습니다. 그래프 패널에 다중 값 열이 별도의 시리즈로 작성됩니다. ### 데이터 필터링(WHERE) 필터를 추가하려면 `WHERE` 조건 오른쪽에 있는 더하기 아이콘을 선택합니다. 필터를 선택하고 **제거**를 선택하여 필터를 제거할 수 있습니다. 현재 선택한 시간 범위에 대한 필터가 새 쿼리에 자동으로 추가됩니다. ### 그룹화 기준 시간 또는 다른 열을 기준으로 그룹화하려면 GROUP BY 행 끝에 있는 더하기 아이콘을 선택합니다. 제안 드롭다운 목록에는 현재 선택한 테이블의 텍스트 열만 표시되지만 열을 수동으로 입력할 수 있습니다. 항목을 선택하고 **제거**를 선택하여 그룹을 제거할 수 있습니다. 그룹을 추가하는 경우 선택한 모든 열에 집계 함수가 적용되어야 합니다. 쿼리 빌더는 그룹화를 추가할 때 집계 함수 없이 모든 열에 집계 함수를 자동으로 추가합니다. #### 갭 채우기 Amazon Managed Grafana에서 시간별로 그룹화할 때 누락된 값을 채울 수 있습니다. 시간 함수는 두 개의 인수를 허용합니다. 첫 번째 인수는 그룹화 기준으로 사용하려는 기간이고 두 번째 인수는 Grafana에서 누락된 항목을 채우려는 값입니다. ### 텍스트 편집기 모드(RAW) 햄버거 아이콘을 선택하고 **편집기 모드 전환**을 선택하거나 쿼리 아래에서 **SQL 편집**을 선택하여 원시 쿼리 편집기 모드로 전환할 수 있습니다. **참고** 원시 쿼리 편집기를 사용하는 경우 쿼리에 최소한 `ORDER BY time` 및 필터가 반환된 시간 범위에 있는지 확인합니다. ## 매크로 쿼리 내에서 매크로를 사용하여 구문을 단순화하고 동적 부분을 허용할 수 있습니다. | 매크로 예제 | 설명 | | --- | --- | | $\_\_time(dateColumn) | UNIX 타임스탬프로 변환하고 열 이름을 time\_sec으로 바꾸는 표현식으로 대체됩니다. 예: UNIX\_TIMESTAMP(dateColumn) as time\_sec. | | $\_\_timeEpoch(dateColumn) | UNIX 타임스탬프로 변환하고 열 이름을 time\_sec으로 바꾸는 표현식으로 대체됩니다. 예: UNIX\_TIMESTAMP(dateColumn) as time\_sec. | | $\_\_timeFilter(dateColumn) | 지정된 열 이름을 사용하여 시간 범위 필터로 대체됩니다. 예: dateColumn BETWEEN FROM\_UNIXTIME(1494410783) AND FROM\_UNIXTIME(1494410983). | | $\_\_timeFrom() | 현재 활성 시간 선택의 시작으로 대체됩니다. 예: FROM\_UNIXTIME(1494410783). | | $\_\_timeTo() | 현재 활성 시간 선택의 끝으로 대체됩니다. 예: FROM\_UNIXTIME(1494410983). | | $\_\_timeGroup(dateColumn,'5m') | GROUP BY 절에서 사용할 수 있는 표현식으로 대체됩니다. 예: cast(cast(UNIX\_TIMESTAMP(dateColumn)/(300) as signed)300 as signed),\* | | $\_\_timeGroup(dateColumn,'5m', 0) | 이전 행과 동일하지만 채우기 파라미터가 있는 경우 해당 시리즈의 누락된 포인트가 Grafana에 의해 추가되고 0이 값으로 사용됩니다. | | $\_\_timeGroup(dateColumn,'5m', NULL) | 위와 동일하지만 NULL이 누락 포인트의 값으로 사용됩니다. | | $\_\_timeGroup(dateColumn,'5m', previous) | 위와 동일하지만 해당 시리즈의 이전 값이 채우기 값으로 사용됩니다. 아직 값이 보이지 않으면 NULL이 사용됩니다(Grafana 5.3 이상에서만 사용 가능). | | $\_\_timeGroupAlias(dateColumn,'5m') | $\_\_timeGroup과 동일하지만 추가된 열 별칭으로 대체됩니다. | | $\_\_unixEpochFilter(dateColumn) | 지정된 열 이름을 사용하여 시간 범위 필터(Unix 타임스탬프로 시간이 표시됨)로 대체됩니다. 예: \*dateColumn > 1494410783 AND dateColumn < 1494497183\* | | $\_\_unixEpochFrom()` | \| 현재 활성 시간 선택의 시작(Unix 타임스탬프 형식)으로 대체됩니다. 예: \*1494410783\* | | $\_\_unixEpochTo() | 현재 활성 시간 선택의 끝(Unix 타임스탬프 형식)으로 대체됩니다. 예: \*1494497183\* | | $\_\_unixEpochNanoFilter(dateColumn) | 지정된 열 이름을 사용하여 시간 범위 필터(나노초 타임스탬프로 시간이 표시됨)로 대체됩니다. 예: \*dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872\* | | $\_\_unixEpochNanoFrom() | 현재 활성 시간 선택의 시작(나노초 타임스탬프 형식)으로 대체됩니다. 예: \*1494410783152415214\* | | $\_\_unixEpochNanoTo() | 현재 활성 시간 선택의 끝(나노초 타임스탬프 형식)으로 대체됩니다. 예: \*1494497183142514872\* | | $\_\_unixEpochGroup(dateColumn,"5m", [fillmode]) | $\_\_timeGroup과 동일하지만 Unix 타임스탬프로 시간이 저장됩니다. | ## 테이블 쿼리 쿼리 옵션이 **형식: 테이블**로 설정된 경우 기본적으로 모든 유형의 SQL 쿼리를 수행할 수 있습니다. 테이블 패널에는 쿼리에서 반환하는 열 및 행의 결과가 자동으로 표시됩니다. 일반 `as` SQL 열 선택 구문을 사용하여 테이블 패널 열의 이름을 제어할 수 있습니다. ## 시계열 쿼리 예를 들어 그래프 패널에서 사용할 **형식**을 `Time series`로 설정한 경우 쿼리는 SQL datetime 또는 Unix 에포크를 나타내는 숫자 데이터 유형을 반환하는 `time`이라는 열을 반환해야 합니다. `time` 및 `metric`을 제외한 모든 열은 값 열로 처리됩니다. 값 열의 지표 이름으로 사용되는 `metric` 열을 반환할 수 있습니다. 다중 값 열과 `metric` 열을 반환하면 이 열이 시리즈 이름의 접두사로 사용됩니다. 시계열 쿼리의 결과 세트는 시간별로 정렬해야 합니다. 다음 코드 예제에서는 `metric` 열을 보여줍니다. ``` SELECT $__timeGroup("time_date_time",'5m'), min("value_double"), 'min' as metric FROM test_data WHERE $__timeFilter("time_date_time") GROUP BY time ORDER BY time ``` 아래 코드 예제에서는 $\_\_timeGroup 매크로의 채우기 파라미터를 사용하여 대신 null 값을 0으로 변환하는 방법을 보여줍니다. ``` SELECT $__timeGroup("createdAt",'5m',0), sum(value) as value, measurement FROM test_data WHERE $__timeFilter("createdAt") GROUP BY time, measurement ORDER BY time ``` 다음 코드 예제에서는 여러 열을 보여줍니다. ``` SELECT $__timeGroup("time_date_time",'5m'), min("value_double") as "min_value", max("value_double") as "max_value" FROM test_data WHERE $__timeFilter("time_date_time") GROUP BY time ORDER BY time ``` ## 템플릿 지정 지표 쿼리에서 서버, 애플리케이션 및 센서 이름과 같은 사물을 하드코딩하는 대신 해당 위치에서 변수를 사용할 수 있습니다. 변수는 대시보드 상단에서 드롭다운 선택 상자로 표시됩니다. 이러한 드롭다운 상자를 사용하여 대시보드에 표시되는 데이터를 변경할 수 있습니다. 템플릿 지정 및 템플릿 변수에 대한 자세한 내용은 [템플릿](templates-and-variables.md#templates) 섹션을 참조하세요. ### 쿼리 변수 `Query` 유형의 템플릿 변수를 추가하는 경우 드롭다운 선택 상자로 표시되는 측정 이름, 키 이름 또는 키 값과 같은 항목을 반환할 수 있는 PostgreSQL 쿼리를 작성할 수 있습니다. 예를 들어 템플릿 지정 변수 **쿼리 설정에서 이와 같은 쿼리를 지정하여 `hostname` 열의 모든 값을 포함하는 변수를 가질 수 있습니다. ``` SELECT hostname FROM host ``` 쿼리는 여러 열을 반환할 수 있으며 Grafana는 이 열에서 목록을 자동으로 생성합니다. 예를 들어 다음 쿼리는 `hostname` 및 `hostname2`의 값이 포함된 목록을 반환합니다. ``` SELECT host.hostname, other_host.hostname2 FROM host JOIN other_host ON host.city = other_host.city ``` 쿼리에서 `$__timeFilter(column)`와 같은 시간 범위 종속 매크로를 사용하려면 템플릿 변수의 새로 고침 모드를 *시간 범위 변경 시*로 설정해야 합니다. ``` SELECT event_name FROM event_log WHERE $__timeFilter(time_column) ``` 또 다른 옵션으로 키/값 변수를 생성할 수 있는 쿼리가 있습니다. 쿼리에서 `__text` 및 `__value`라는 두 개의 열을 반환해야 합니다. `__text` 열 값은 고유해야 합니다(고유하지 않은 경우 첫 번째 값이 사용됨). 드롭다운 목록의 옵션은 텍스트 및 값을 포함하며, 여기에서는 친숙한 이름(텍스트) 및 ID(값)를 지정할 수 있습니다. `hostname`을 텍스트로, `id`를 값으로 사용하는 쿼리 예제: ``` SELECT hostname AS __text, id AS __value FROM host ``` 중첩 변수를 생성할 수도 있습니다. `region` 변수를 사용하면 호스트 변수에서 현재 선택한 리전의 호스트만 표시할 수 있습니다. 다음 코드 예제에서는 다음과 같은 쿼리를 보여줍니다(`region`이 다중 값 변수인 경우 다중 값과 일치하려는 경우 `=` 대신 `IN` 비교 연산자 사용). ``` SELECT hostname FROM host WHERE region IN($region) ``` #### `__searchFilter`를 사용하여 쿼리 변수에서 결과 필터링 쿼리 필드에서 `__searchFilter`를 사용하면 드롭다운 선택 상자에 입력한 내용을 기반으로 쿼리 결과를 필터링합니다. 사용자가 아무 것도 입력하지 않은 경우 `__searchFilter`의 기본값은 `%`입니다. **참고** Grafana에서는 이를 자동으로 수행하지 않으므로 `__searchFilter` 표현식을 따옴표로 묶는 것이 중요합니다. 다음 예제에서는 사용자가 드롭다운 선택 상자에 텍스트를 입력하는 동안 `__searchFilter`를 쿼리 필드의 일부로 사용하여 `hostname` 검색을 활성화하는 방법을 보여줍니다. ``` SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter' ``` ### 쿼리에서 변수 사용 템플릿 변수 값은 템플릿 변수가 `multi-value`인 경우에만 따옴표로 묶습니다. 변수가 다중 값 변수인 경우 여러 값과 일치시키는 `=`보다 `IN` 비교 연산자를 사용합니다. 두 가지 구문이 있습니다. `$`: 템플릿 변수 이름이 `hostname`인 예제: ``` SELECT atimestamp as time, aint as value FROM table WHERE $__timeFilter(atimestamp) and hostname in($hostname) ORDER BY atimestamp ASC ``` `[[varname]]`: 템플릿 변수 이름이 `hostname`인 예제: ``` SELECT atimestamp as time, aint as value FROM table WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) ORDER BY atimestamp ASC ``` #### 다중 값 변수에 대한 따옴표 기능 끄기 Amazon Managed Grafana에서는 다중 값 변수에 대해 따옴표로 묶고 쉼표로 구분된 문자열을 자동으로 생성합니다. 예를 들어, `server01` 및 `server02`를 선택하면 `'server01', 'server02'` 형식으로 지정됩니다. 이 기능을 끄려면 변수에 csv 형식 지정 옵션을 사용합니다. `${servers:csv}` 변수 형식 지정 옵션에 대한 자세한 내용은 [템플릿 및 변수](templates-and-variables.md) 섹션을 참조하세요. ## Annotations 주석을 사용하여 그래프 위에 풍부한 이벤트 정보를 오버레이합니다. 대시보드 메뉴/주석 보기를 통해 주석 쿼리를 추가합니다. 자세한 내용은 [Annotations](dashboard-annotations.md) 단원을 참조하십시오. 다음 코드 예제에서는 에포크 값이 있는 시간 열을 사용하는 쿼리를 보여줍니다. ``` SELECT epoch_time as time, metric1 as text, concat_ws(', ', metric1::text, metric2::text) as tags FROM public.test_data WHERE $__unixEpochFilter(epoch_time) ``` 다음 코드 예제에서는 에포크 값을 포함하는 time 및 timeend 열을 사용하는 리전 쿼리를 보여줍니다. **참고** Grafana v6.6 이상에서만 사용할 수 있습니다. ``` SELECT epoch_time as time, epoch_time_end as timeend, metric1 as text, concat_ws(', ', metric1::text, metric2::text) as tags FROM public.test_data WHERE $__unixEpochFilter(epoch_time) ``` 다음 코드 예제에서는 기본 SQL 날짜/시간 데이터 유형의 시간 열을 사용하는 쿼리를 보여줍니다. ``` SELECT native_date_time as time, metric1 as text, concat_ws(', ', metric1::text, metric2::text) as tags FROM public.test_data WHERE $__timeFilter(native_date_time) ``` | 이름 | 설명 | | --- | --- | | time | 날짜/시간 필드의 이름. 기본 SQL 날짜/시간 데이터 유형 또는 에포크 값을 포함하는 열일 수 있습니다. | | timeend | 종료 날짜/시간 필드의 선택적 이름. 기본 SQL 날짜/시간 데이터 유형 또는 에포크 값을 포함하는 열일 수 있습니다(Grafana v6.6 이상). | | text | 이벤트 설명 필드. | | tags | 이벤트 태그에 대해 쉼표로 구분된 문자열로 사용할 선택적 필드 이름. | ## 알림 시계열 쿼리는 알림 조건에서 작동해야 합니다. 테이블 형식의 쿼리는 알림 규칙 조건에서 아직 지원되지 않습니다.