에이전트의 사용자 정의 측정항목

이 가이드에서는 Monitoring 에이전트가 애플리케이션 측정항목을 인식하고 Cloud Monitoring으로 내보내도록 구성하는 방법을 설명합니다.

Monitoring 에이전트는 collectd 데몬입니다. 에이전트는 Cloud Monitoring에 많은 사전 정의된 시스템 및 서드 파티 측정항목을 내보낼 뿐만 아니라 collectd 애플리케이션 측정항목을 사용자 정의 측정항목으로 Monitoring에 내보낼 수도 있습니다. collectd 플러그인은 Monitoring으로 내보낼 수도 있습니다.

애플리케이션 측정항목을 Monitoring으로 내보내는 또 다른 방법은 StatsD를 사용하는 것입니다. Cloud Monitoring은 StatsD 측정항목을 사용자 정의 측정항목에 매핑하는 기본 구성을 제공합니다. 매핑이 만족스러운 경우 아래 설명된 맞춤설정 단계를 수행할 필요가 없습니다. 자세한 내용은 StatsD 플러그인을 참조하세요.

측정항목에 대한 자세한 내용은 다음 문서를 참조하세요.

이 기능은 Linux에서 실행되는 에이전트에만 사용할 수 있습니다. Windows에서는 사용할 수 없습니다.

시작하기 전에

VM 인스턴스에 최신 Monitoring 에이전트를 설치하고 제대로 작동하는지 확인합니다. 에이전트를 업데이트하려면 에이전트 업데이트하기를 참조하세요.
애플리케이션에서 모니터링 데이터를 가져오도록 collectd를 구성합니다. Collectd는 읽기 플러그인을 통해 다양한 애플리케이션 프레임워크와 표준 모니터링 엔드포인트를 지원합니다. 적절한 읽기 플러그인을 찾으세요.
(선택사항) 편의를 위해 MANPATH 변수를 업데이트하고 mandb를 실행하여 시스템의 man 페이지에 에이전트의 collectd 참조 문서를 추가합니다.
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
설명 페이지는 stackdriver-collectd용입니다.

중요 파일 및 디렉터리

에이전트를 설치하면 생성되는 다음 파일과 디렉토리는 Monitoring 에이전트(collectd) 사용과 관련이 있습니다.

/etc/stackdriver/collectd.conf: 에이전트에서 사용하는 collectd 구성 파일. 일반 구성을 변경하려면 이 파일을 수정합니다.

참고: 시스템 기본 collectd 구성인 /etc/collectd.conf는 Monitoring 에이전트에서 사용되지 않습니다.
/etc/stackdriver/collectd.d/: 사용자가 추가한 구성 파일의 디렉터리. 에이전트에서 사용자 정의 측정항목을 전송하려면 아래 설명된 필수 구성 파일을 이 디렉터리에 넣습니다. 에이전트는 이전 버전과의 호환성을 위해 /opt/stackdriver/collectd/etc/collectd.d/에서도 파일을 찾습니다.
/opt/stackdriver/collectd/share/man/*: 에이전트의 collectd 버전에 관한 문서. 이 페이지를 시스템의 man 페이지 세트에 추가할 수 있습니다. 자세한 내용은 시작하기 전에를 참조하세요.
/etc/init.d/stackdriver-agent: 에이전트의 init 스크립트

Monitoring에서 collectd 측정항목을 처리하는 방법

Monitoring 에이전트는 백그라운드에서 collectd 측정항목을 처리하고 Monitoring으로 전송합니다. 이때 각 측정항목을 다음 카테고리 중 하나의 구성원으로 처리합니다.

사용자 정의 측정항목. 메타데이터 키 stackdriver_metric_type과 단일 데이터 소스가 있는 collectd 측정항목은 사용자 정의 측정항목으로 처리되고 Monitoring API의 projects.timeSeries.create 메서드를 사용하여 Monitoring으로 전송됩니다.
선별된 측정항목. 다른 모든 collectd 측정항목은 내부 API를 사용하여 Monitoring으로 전송됩니다. 선별된 측정항목 목록의 측정항목만 수락되고 처리됩니다.
삭제된 측정항목. 선별된 측정항목 목록에 없으며 사용자 정의 측정항목이 아닌 collectd 측정항목은 Monitoring에서 자동으로 삭제됩니다. 에이전트 자체는 어느 측정항목이 수락되거나 삭제되는지 인식하지 못합니다.

에이전트로 사용자 정의 측정항목 작성

Monitoring에 측정항목 데이터 포인트를 전송하도록 에이전트를 구성합니다. 각 포인트를 측정항목 설명으로 정의하는 사용자 정의 측정항목과 연결해야 합니다. 이에 대한 개념은 측정항목, 시계열, 리소스를 참조하세요. 자세한 내용은 시계열의 구조 및 사용자 정의 측정항목 개요에서 확인할 수 있습니다.

측정항목에 적절한 메타데이터를 추가하여 collectd 측정항목이 사용자 정의 측정항목으로 처리되게 할 수 있습니다.

stackdriver_metric_type : (필수) 내보낸 측정항목의 이름입니다. 예를 들면 custom.googleapis.com/my_custom_metric입니다.
label:[LABEL] : (선택사항) 내보낸 측정항목의 추가 라벨입니다. 예를 들어 이름이 color인 Monitoring STRING 라벨이 필요한 경우 메타데이터 키는 label:color이고 키 값은 "blue"일 수 있습니다. 측정항목 유형별로 최대 10개의 라벨을 사용할 수 있습니다.

Collectd 필터 체인을 사용하여 측정항목의 메타데이터를 수정합니다. 필터 체인은 데이터 소스 목록을 수정할 수 없고 사용자 정의 측정항목은 단일 데이터 소스만 지원하기 때문에 이 기능과 함께 사용하려는 collectd 측정항목에는 단일 데이터 소스가 있어야 합니다.

예

이 예시에서는 2개의 Nginx 서비스인 my_service_a와 my_service_b의 활성 Nginx 연결을 모니터링합니다. 사용자 정의 측정항목을 사용하여 Monitoring에 이를 전송합니다. 다음 단계를 수행합니다.

각 Nginx 서비스의 collectd 측정항목을 식별합니다.
Monitoring 측정항목 설명자를 정의합니다.
Monitoring 에이전트의 요건을 충족하기 위해 collectd 측정항목에 메타데이터를 추가하도록 collectd 필터 체인을 구성합니다.

수신 collectd 측정항목

Collectd는 다음 구성요소로 이루어진 측정항목을 필요로 합니다. 처음 5개 구성요소가 측정항목의 collectd 식별자를 구성합니다.

    Host, Plugin, Plugin-instance, Type, Type-instance, [value]

이 예시에서 사용자 정의 측정항목으로 전송하려는 측정항목의 값은 다음과 같습니다.

구성요소	필요한 값
호스트	모두
플러그인	`curl_json`
플러그인 인스턴스	`nginx_my_service_a` 또는 `nginx_my_service_b`¹
유형	`gauge`
유형 인스턴스	`active-connections`
`[value]`	모든 값²

메모:
¹ 예시에서 이 값은 애플리케이션(Nginx)과 연결된 서비스 이름을 모두 인코딩합니다.
² 이 값은 대개 타임스탬프와 배정밀도 숫자입니다. Monitoring은 다양한 종류의 값 해석을 세부적으로 처리합니다. 복합 값은 Monitoring 에이전트에서 지원되지 않습니다.

Monitoring 측정항목 설명자 및 시계열 모니터링

Monitoring 측에서 사용자 정의 측정항목의 측정항목 설명을 설계합니다. 다음 설명은 이 예시의 데이터에 적합한 선택사항입니다.

이름: custom.googleapis.com/nginx/active_connections
라벨:
- service_name(STRING): Nginx에 연결된 서비스의 이름입니다.
종류: GAUGE
유형: DOUBLE

측정항목 설명을 설계했으면 projects.metricDescriptors.create를 사용하여 만들거나 아래 설명된 시계열 메타데이터에서 생성되도록 할 수 있습니다. 자세한 내용은 이 페이지의 측정항목 설명 만들기를 참조하세요.

측정항목 설명의 정의 방식 때문에 이 측정항목 설명의 시계열 데이터에 다음 정보가 포함되어야 합니다.

측정항목 유형: custom.googleapis.com/nginx/active_connections
측정항목 라벨 값:
- service_name: "my_service_a" 또는 "my_service_b"

연결된 모니터링 리소스(데이터를 전송하는 VM 인스턴스)와 측정항목의 데이터 포인트를 포함한 기타 시계열 정보는 모든 측정항목의 에이전트가 자동으로 가져옵니다. 따라서 사용자는 별도의 조치를 취하지 않아도 됩니다.

필터 체인

다음 코드를 포함하는 /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf라는 파일을 만듭니다.

LoadPlugin match_regex
LoadPlugin target_set
LoadPlugin target_replace

# Insert a new rule in the default "PreCache" chain, to divert your metrics.
PreCacheChain "PreCache"
<Chain "PreCache">
  <Rule "jump_to_custom_metrics_from_curl_json">
    # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
    <Match regex>
      Plugin "^curl_json$"
      PluginInstance "^nginx_"
    </Match>
    <Target "jump">
      # Go execute the following chain; then come back.
      Chain "PreCache_curl_json"
    </Target>
  </Rule>
  # Continue processing metrics in the default "PreCache" chain.
</Chain>

# Following is a NEW filter chain, just for your metric.
# It is only executed if the default chain "jumps" here.
<Chain "PreCache_curl_json">

  # The following rule does all the work for your metric:
  <Rule "rewrite_curl_json_my_special_metric">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^curl_json$"                   # Match on plugin.
      PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
      Type "^gauge$"                         # Match on type.
      TypeInstance "^active-connections$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
      # Specify a value for the "service_name" label; clean it up in the next Target:
      MetaData "label:service_name" "%{plugin_instance}"
    </Target>

    <Target "replace">
      # Remove the "nginx_" prefix in the service_name to get the real service name:
      MetaData "label:service_name" "nginx_" ""
    </Target>
  </Rule>

  # The following rule is run after rewriting your metric, or
  # if the metric wasn't one of your user-defined metrics. The rule returns
  # to the default "PreCache" chain. The default processing
  # will write all metrics to Cloud Monitoring,
  # which will drop any unrecognized metrics: ones that aren't
  # in the list of curated metrics and don't have
  # the user-defined metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

새 구성 로드

VM 인스턴스에서 다음 명령어로 에이전트를 다시 시작하여 새 구성을 가져옵니다.

sudo service stackdriver-agent restart

사용자 정의 측정항목 정보가 Monitoring으로 전송되기 시작합니다.

참조 및 권장사항

측정항목 설명 및 시계열

Cloud Monitoring 측정항목에 관한 소개는 측정항목, 시계열, 리소스를 참조하세요. 자세한 내용은 사용자 정의 측정항목 개요 및 시계열의 구조에서 확인할 수 있습니다.

측정항목 설명. 측정항목 설명에는 다음과 같은 중요 요소가 있습니다.

custom.googleapis.com/[NAME1]/.../[NAME0] 형식의 유형입니다. 예를 들면 다음과 같습니다.
```
custom.googleapis.com/my_measurement
custom.googleapis.com/instance/network/received_packets_count
custom.googleapis.com/instance/network/sent_packets_count
```
사람들이 더 쉽게 측정항목을 추적할 수 있도록 계층적 이름을 사용하는 것이 좋습니다. 측정항목 유형은 하이픈을 포함할 수 없습니다. 정확한 이름 지정 규칙은 측정항목 유형 및 라벨 이름 지정을 참조하세요.
측정항목 데이터에 주석을 다는 데 최대 10개의 라벨(device_name, fault_type, response_code 등)이 있습니다. 라벨 값은 측정항목 설명에 지정되지 않습니다.
데이터 포인트의 종류와 값 유형(예: double 유형의 게이지 값). 자세한 내용은 MetricKind 및 ValueType를 참조하세요.

시계열. 측정항목 데이터 포인트에는 다음과 같은 중요 요소가 있습니다.

연결된 측정항목 설명의 유형
모든 측정항목 설명자의 라벨 값
측정항목 설명의 값 유형 및 종류와 일치하는 타임스탬프가 적용된 값
데이터를 가져온 모니터링 리소스(대개 VM 인스턴스). 리소스가 빌드되는 공간이므로 설명자에 이에 대한 별도의 라벨이 필요하지 않습니다.

측정항목 설명자 만들기

측정항목 설명자를 미리 만들 필요가 없습니다. 데이터 포인트가 Monitoring에 도착하면 포인트의 측정항목 유형, 라벨, 포인트의 값을 사용하여 게이지나 누적 측정항목 설명이 자동으로 생성될 수 있습니다. 자세한 내용은 측정항목 설명 자동 생성을 참조하세요.

그러나 측정항목 설명자를 직접 만들면 다음과 같은 장점이 있습니다.

측정항목과 해당 라벨에 대한 몇 가지 유용한 서류를 포함할 수 있습니다.
측정항목의 종류와 유형을 추가로 지정할 수 있습니다. 에이전트에서 지원하는 (종류, 유형) 조합은 (GAUGE, DOUBLE)과 (CUMULATIVE, INT64)뿐입니다. 자세한 내용은 측정항목 종류 및 값 유형을 참조하세요.
STRING 이외의 라벨 유형을 지정할 수 있습니다.

정의되지 않은 측정항목 유형을 사용하는 데이터 포인트를 Monitoring에 작성하면 해당 데이터 포인트용으로 새로운 측정항목 설명이 생성됩니다. 이 동작은 측정항목 데이터를 작성하는 코드를 디버깅할 때 문제가 될 수 있습니다. 측정항목 유형을 잘못 쓰면 가짜 측정항목 설명이 생성됩니다.

측정항목 설명자를 만들거나 측정항목 설명자가 생성된 후에는 이를 변경할 수 없습니다. 예를 들어, 라벨을 추가하거나 삭제할 수 없습니다. 먼저 측정항목 설명자만 삭제하고(해당 데이터가 모두 삭제됨) 원하는 방식으로 설명자를 다시 만들 수 있습니다.

측정항목 설명 만들기에 대한 자세한 내용은 측정항목 만들기를 참조하세요.

가격 책정

일반적으로 Cloud Monitoring 시스템 측정항목은 무료이고 외부 시스템, 에이전트, 애플리케이션의 측정항목은 무료가 아닙니다. 청구 가능한 측정항목은 수집된 바이트 수 또는 샘플 수에 따라 청구됩니다.

Cloud Monitoring 가격 책정에 대한 자세한 내용은 다음 문서를 참조하세요.

한도

Cloud Monitoring에는 각 프로젝트의 측정항목 시계열 수와 사용자 정의 측정항목 설명 수에 대한 제한이 있습니다. 자세한 내용은 할당량 및 한도를 참조하세요.

생성한 측정항목 설명자가 더 이상 필요하지 않으면 Monitoring API를 사용하여 설명자를 찾아 삭제할 수 있습니다. 자세한 내용은 projects.metricDescriptors을 참조하세요.

문제 해결

이 섹션에서는 메타데이터를 포함한 전체 측정항목 지점을 없애도록 Monitoring 에이전트의 write_log 플러그인을 구성하는 방법을 설명합니다. 이를 통해 변환해야 할 포인트를 결정하고 변환이 예상대로 이루어지는지 확인할 수 있습니다.

write_log 사용 설정하기

write_log 플러그인은 stackdriver-agent 패키지에 포함되어 있습니다. 플러그인을 사용 설정하려면 다음 안내를 따르세요.

루트 권한으로 다음 구성 파일을 수정합니다.
```
/etc/stackdriver/collectd.conf
```
LoadPlugin write_gcm 직후 다음을 추가합니다.
```
LoadPlugin write_log
```
<Plugin "write_gcm">…</Plugin> 직후 다음을 추가합니다.
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
<Target "write">…</Target>를 검색하고 Plugin "write_gcm"마다 다음을 추가합니다.
```
Plugin "write_log"
```
변경사항을 저장하고 에이전트를 다시 시작합니다.
```
sudo service stackdriver-agent restart
```

보고된 측정항목 값당 하나의 로그 줄(전체 collectd 식별자, 메타데이터 항목, 값 포함)이 출력됩니다.

write_log의 출력

이전 단계에서 성공했다면 시스템 로그에 write_log 출력이 표시됩니다.

Debian 기반 Linux: /var/log/syslog
Red Hat 기반 Linux: /var/log/messages

아래 샘플의 줄 형식은 이 문서에서 쉽게 읽을 수 있도록 지정되었습니다.

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[0], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]