에이전트의 커스텀 측정항목

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

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

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

Stackdriver의 커스텀 측정항목에 대해 잘 모르는 경우 측정항목, 시계열, 리소스, 측정항목 유형의 구조, 커스텀 측정항목 사용을 참조하세요.

시작하기 전에

  • VM 인스턴스에 최신 Monitoring 에이전트를 설치하고 제대로 작동하는지 확인합니다. 에이전트를 업데이트하려면 에이전트 업데이트하기를 참조하세요.

  • 애플리케이션에서 모니터링 데이터를 가져오도록 collectd를 구성합니다. Collectd는 읽기 플러그인을 통해 다양한 애플리케이션 프레임워크와 표준 모니터링 엔드포인트를 지원합니다. 적절한 읽기 플러그인을 찾으세요.

  • (선택사항) 편의를 위해 MANPATH 변수를 업데이트하고 mandb를 실행하여 시스템의 man 페이지에 에이전트의 collectd 참조 문서를 추가합니다.

    export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
    sudo mandb
    

    man 페이지는 stackdriver-collectd용입니다.

중요 파일 및 디렉토리

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

/etc/stackdriver/collectd.conf

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

/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_amy_service_b의 활성 Nginx 연결을 모니터링합니다. 커스텀 측정항목을 사용하여 Monitoring에 이들 연결을 전송합니다. 다음 단계를 수행합니다.

  1. 각 Nginx 서비스의 collectd 측정항목을 식별합니다.

  2. Monitoring 측정항목 설명자를 정의합니다.

  3. Monitoring 에이전트의 요건을 충족하기 위해 collectd 측정항목에 메타데이터를 추가하도록 collectd 필터 체인을 구성합니다.

수신 collectd 측정항목

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

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

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

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

참고:
1 이 예시에서 이 값은 애플리케이션(Nginx)과 연결된 서비스 이름을 모두 인코딩합니다.
2 이 값은 대개 타임스탬프와 배정밀도 숫자입니다. 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 name:
      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 custom metrics. The rule returns to
  # the default "PreCache" chain. The default processing
  # will write all metrics to Stackdriver Monitoring,
  # which will drop any unrecognized metrics: ones that are not
  # in the list of curated metrics and do not have
  # the custom metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

새 구성 로드

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

sudo service stackdriver-agent restart

커스텀 측정항목 정보가 Monitoring으로 전송되기 시작합니다.

참조 및 권장사항

측정항목 설명자 및 시계열

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

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

  • 이름 형식(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
    

    커스텀 측정항목 이름은 custom.googleapis.com/으로 시작해야 합니다. 사람들이 더 쉽게 측정항목을 추적할 수 있도록 계층적 이름을 사용하는 것이 좋습니다. 측정항목 이름은 하이픈을 포함할 수 없습니다. 정확한 명명 규칙은 측정항목 및 라벨 이름 규칙을 참조하세요.

  • 측정항목 데이터에 주석을 다는 데 사용되는 최대 10개의 라벨(예: device_name, fault_type, response_code). 라벨 값은 측정항목 설명자에 지정되지 않습니다.

  • 데이터 포인트의 종류와 유형(예: double 유형의 게이지 값). 자세한 내용은 MetricKindValueType을 참조하세요.

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

  • 연결된 측정항목 설명자의 이름

  • 모든 측정항목 설명자의 라벨 값

  • 측정항목 설명자의 유형 및 종류와 일치하는 타임스탬프가 적용된 값

  • 데이터를 가져온 모니터링 리소스(대개 VM 인스턴스). 리소스가 빌드되는 공간이므로 설명자에 이에 대한 별도의 라벨이 필요하지 않습니다.

측정항목 설명자 만들기

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

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

  • 측정항목과 해당 라벨에 대한 몇 가지 유용한 서류를 포함할 수 있습니다.

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

  • STRING 이외의 라벨 유형을 지정할 수 있습니다.

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

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

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

비용 및 제한

Stackdriver는 수신되는 측정항목 데이터 볼륨을 기준으로 사용자 정의 및 에이전트 측정항목을 모두 포함하는 collectd 측정항목 비용을 청구합니다. 자세한 내용은 Stackdriver 가격을 참조하세요.

가격과 별개로, Stackdriver는 각 GCP 프로젝트에 있는 측정항목 시계열 수 및 사용자 정의된 측정항목 설명자 수가 제한됩니다. 자세한 내용은 할당량 및 한도를 참조하세요.

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

문제해결

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

write_log 사용 설정하기

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

  1. 루트 권한으로 다음 구성 파일을 수정합니다.

    /etc/stackdriver/collectd.conf
    
  2. LoadPlugin write_gcm 바로 뒤에 다음을 추가합니다.

    LoadPlugin write_log
    
  3. <Plugin "write_gcm">…</Plugin> 바로 뒤에 다음을 추가합니다.

    <Plugin "write_log">
      Format JSON
    </Plugin>
    
  4. <Target "write">…</Target>을 검색하고 모든 Plugin "write_gcm" 뒤에 다음을 추가합니다.

    Plugin "write_log"
    
  5. 변경사항을 저장하고 에이전트를 다시 시작합니다.

    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"}]
이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

Stackdriver Monitoring
도움이 필요하시나요? 지원 페이지를 방문하세요.