작업 에이전트 구성

이 문서에서는 작업 에이전트의 기본 구성과 커스텀 구성에 관한 세부정보를 제공합니다. 다음에 해당되는 사항이 있으면 이 문서가 도움이 될 것입니다.

  • 다음 목표를 달성하기 위해 작업 에이전트의 구성을 변경하고자 하는 경우:

    • 기본 탑재되는 로깅 또는 측정항목 수집에 대한 사용을 중지합니다.

    • 에이전트가 로그를 수집하는 로그 파일의 파일 경로를 맞춤설정하려면 로깅 받는 사람을 참조하세요.

    • JSON을 파싱하거나 정규 표현식을 사용하여 에이전트가 로그 항목을 처리하는 데 사용하는 구조화된 로그 형식을 맞춤설정하려면 로깅 프로세서를 참조하세요.

    • 측정항목의 샘플링 레이트를 변경하려면 측정항목 받는 사람을 참조하세요.

    • 사용할 측정항목의 하나 또는 복수의 그룹을 맞춤설정합니다. 에이전트는 기본적으로 cpumemory와 같은 모든 시스템 측정항목을 수집합니다. 측정항목 프로세서를 참조하세요.

  • 작업 에이전트 구성의 기술적인 세부정보를 알고 싶은 경우

작업 에이전트는 또한 지원되는 타사 애플리케이션에서 측정항목 및 로그를 수집하기 위한 구성 안내를 제공합니다. 지원되는 애플리케이션 목록은 타사 애플리케이션 모니터링을 참조하세요.

구성 모델

작업 에이전트는 기본 탑재된 기본 구성을 사용하며, 이 기본 탑재 구성을 직접 수정할 수는 없습니다. 대신 사용자는 에이전트를 다시 시작할 때 기본 탑재 구성과 병합된 재정의 파일을 만들게 됩니다.

구성의 구성 요소는 다음과 같습니다.

  • receivers: 이 요소는 에이전트에서 수집되는 내용을 설명합니다.
  • processors: 이 요소는 수집된 정보를 에이전트가 수정할 수 있는 정도를 설명합니다.
  • service: 이 요소는 수신자와 프로세서를 하나로 연결하여 파이프라인이라는 데이터 흐름을 만듭니다. service 요소에는 여러 파이프라인을 포함할 수 있는 pipelines 요소가 포함됩니다.

기본 탑재 구성은 이러한 요소로 구성되며, 사용자는 동일한 요소를 사용하여 기본 탑재 구성을 재정의합니다.

기본 탑재 구성

작업 에이전트의 기본 탑재 구성은 로그 및 측정항목의 기본 컬렉션을 정의합니다. 다음은 Linux 및 Windows의 기본 탑재 구성을 보여줍니다.

Linux

기본적으로 작업 에이전트는 파일 기반 syslog 로그 및 호스트 측정항목을 수집합니다.

수집되는 측정항목에 대한 상세 설명은 수신자 유형별로 수집한 측정항목을 참조하세요.

logging:
  receivers:
    syslog:
      type: files
      include_paths:
      - /var/log/messages
      - /var/log/syslog
  service:
    pipelines:
      default_pipeline:
        receivers: [syslog]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics]
        processors: [metrics_filter]

Windows

기본적으로 작업 에이전트는 호스트 측정항목, IIS 측정항목, SQL Server 측정항목은 물론 System, Application, Security 채널에서 Windows 이벤트 로그를 수집합니다.

수집되는 측정항목에 대한 상세 설명은 수신자 유형별로 수집한 측정항목을 참조하세요.

logging:
  receivers:
    windows_event_log:
      type: windows_event_log
      channels: [System, Application, Security]
  service:
    pipelines:
      default_pipeline:
        receivers: [windows_event_log]
metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 60s
    iis:
      type: iis
      collection_interval: 60s
    mssql:
      type: mssql
      collection_interval: 60s
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern: []
  service:
    pipelines:
      default_pipeline:
        receivers: [hostmetrics, iis, mssql]
        processors: [metrics_filter]

이러한 구성은 로깅 구성측정항목 구성에서 자세히 설명합니다.

사용자 지정 구성

기본 제공되는 구성을 재정의하려면 새로운 구성 요소를 사용자 구성 파일에 추가합니다. 작업 에이전트 구성을 다음 파일에 입력합니다.

  • Linux: /etc/google-cloud-ops-agent/config.yaml

  • Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml.

에이전트가 다시 시작될 때 사용자가 지정한 모든 구성이 기본 탑재 구성과 병합됩니다.

기본 탑재 수신자, 프로세서 또는 파이프라인을 재정의하려면 config.yaml 파일에서 동일한 식별자로 선언하여 다시 정의합니다.

예를 들어 측정항목의 기본 탑재 구성에는 60초 수집 간격을 지정하는 hostmetrics 수신자가 포함되어 있습니다. 호스트 측정항목의 수집 간격을 30초로 변경하려면 다음과 같이 collection_interval 값을 30초로 설정하는 config.yaml 파일에 hostmetrics라는 측정항목 수신자를 포함합니다. 예를 들면 다음과 같습니다.

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 30s

기본 탑재 구성을 변경하는 다른 예시는 로깅 구성측정항목 구성을 참조하세요.

또한 로깅 또는 측정항목 데이터 컬렉션을 해제할 수 있습니다. 이러한 변경사항에 대해서는 예시 로깅 service 구성측정항목 service 구성에서 설명합니다.

로깅 구성

logging 구성에는 이전에 설명된 구성 모델이 사용됩니다.

  • receivers: 이 요소는 로그 파일에서 수집할 데이터를 설명하며, 데이터는 <timestamp, record> 모델에 매핑됩니다.
  • processors: 이 선택적인 요소는 에이전트가 수집된 정보를 수정할 수 있는 정도를 설명합니다.
  • service: 이 요소는 수신자와 프로세서를 하나로 연결하여 파이프라인이라는 데이터 흐름을 만듭니다. service 요소에는 여러 파이프라인 정의를 포함할 수 있는 pipelines 요소가 포함됩니다.

각 수신자 및 각 프로세서를 여러 파이프라인에서 사용할 수 있습니다.

다음 섹션에서는 이러한 각 요소에 대해 설명합니다.

로깅 수신자

receivers 요소에는 각각 RECEIVER_ID로 식별되는 수신자 집합이 포함되어 있습니다. 수신자는 로그 검색 방법을 설명합니다. 예를 들어 파일을 테일링하거나, TCP 포트를 사용하거나, Windows 이벤트 로그를 사용할 수 있습니다.

로깅 수신자 구조

각 수신자에 식별자 RECEIVER_ID가 있고 type 요소가 포함되어야 합니다. 유효한 유형은 다음과 같습니다.

  • files: 디스크의 파일을 테일링하여 로그를 수집합니다.
  • fluent_forward(Ops Agent 버전 2.12.0 이상에서 사용 가능): TCP를 통해 Fluent Forward 프로토콜로 전송된 로그를 수집합니다.
  • syslog: TCP 또는 UDP를 통해 syslog를 수집합니다.
  • tcp(작업 에이전트 버전 2.3.0 이상에서 사용 가능): TCP 포트를 리슨하여 JSON 형식 로그를 수집합니다.
  • windows_event_log(Windows만 해당): Windows 이벤트 로그를 수집합니다.
  • systemd_journald(Linux의 작업 에이전트 버전 2.4.0 이상에서 사용 가능): systemd-journald 서비스에서 로그를 수집합니다.
  • 타사 애플리케이션 로그 수신자

receivers 구조는 다음과 같습니다.

receivers:
  RECEIVER_ID:
    type: files
    ...
  RECEIVER_ID_2:
    type: syslog
    ...

type 요소의 값에 따라 다음과 같은 다른 구성 옵션이 있을 수 있습니다.

  • files 수신자:

    • include_paths: 필수. 각 파일을 테일링하여 읽을 파일 시스템 경로의 목록입니다. 경로에 와일드 카드(*)를 사용할 수 있습니다(예: /var/log/*.log(Linux) 또는 C:\logs\*.log(Windows)).

      일반적인 Linux 애플리케이션 로그 파일 목록은 일반 Linux 로그 파일을 참조하세요.

    • exclude_paths: 선택사항. include_paths 중에서 일치하는 집합에서 제외할 파일 시스템 경로 패턴의 목록입니다.

    • record_log_file_path: 선택사항. true로 설정된 경우 로그 레코드를 가져온 특정 파일의 경로가 출력 로그 항목에 agent.googleapis.com/log_file_path 라벨 값으로 표시됩니다. 와일드 카드를 사용할 경우 레코드를 가져온 파일의 경로만 기록됩니다.

    • wildcard_refresh_interval: 선택사항. include_paths의 와일드 카드 파일 경로가 새로 고쳐지는 간격입니다. 기간(예: 30s, 2m)으로 지정됩니다. 이 속성은 로그 파일이 기본 간격보다 빠르게 순환되는 높은 로깅 처리량에서 유용할 수 있습니다. 지정하지 않으면 기본 간격은 60초입니다.

  • fluent_forward 수신자:

    • listen_host: 선택사항. 리슨할 IP 주소입니다. 기본값은 127.0.0.1입니다.

    • listen_port: 선택사항. 리슨할 포트입니다. 기본값은 24224입니다.

  • syslog 수신자:

    • transport_protocol: (선택사항) 지원되는 값은 tcp, udp입니다. 기본값은 tcp입니다.

      다음과 같은 추가 옵션을 사용할 수 있습니다.

      • listen_host: 선택사항. 리슨할 IP 주소입니다. 기본값은 0.0.0.0입니다.

      • listen_port: 선택사항. 리슨할 포트입니다. 기본값은 5140입니다.

  • tcp 수신자:

    • format: 필수. 로그 형식입니다. 지원되는 값은 json입니다.

    • listen_host: 선택사항. 리슨할 IP 주소입니다. 기본값은 127.0.0.1입니다.

    • listen_port: 선택사항. 리슨할 포트입니다. 기본값은 5170입니다.

  • windows_event_log 수신자(Windows에만 해당):

    • channels: 필수. 로그를 읽어올 Windows 이벤트 로그 채널 목록입니다.

로깅 수신자 예시

샘플 files 수신자:

receivers:
  RECEIVER_ID:
    type: files

    include_paths: [/var/log/*.log]
    exclude_paths: [/var/log/not-this-one.log]
    record_log_file_path: true

샘플 fluent_forward 수신자:

receivers:
  RECEIVER_ID:
    type: fluent_forward

    listen_host: 127.0.0.1
    listen_port: 24224

샘플 syslog 수신자:

receivers:
  RECEIVER_ID:
    type: syslog

    transport_protocol: tcp
    listen_host: 0.0.0.0
    listen_port: 5140

샘플 tcp 수신자:

receivers:
  RECEIVER_ID:
    type: tcp

    format: json
    listen_host: 127.0.0.1
    listen_port: 5170

샘플 windows_event_log 수신자(Windows만 해당):

receivers:
  RECEIVER_ID:
    type: windows_event_log

    channels: [System,Application,Security]

샘플 systemd_journald 수신자:

receivers:
  RECEIVER_ID:
    type: systemd_journald

구조화된 페이로드의 특수 필드

구조화된 데이터를 수집할 수 있는 프로세서 및 수신자(fluent_forwardtcp 수신자와 parse_json 프로세서)의 경우 에이전트가 Logging API에 쓰는 LogEntry 객체의 특정 필드에 매핑될 특수 필드를 입력에 설정할 수 있습니다.

작업 에이전트가 외부 구조화된 로그 데이터를 수신하면 최상위 필드가 LogEntryjsonPayload 필드에 배치됩니다(필드 이름이 다음 표에 나열되지 않는 경우).

레코드 필드 LogEntry 필드

옵션 1



"timestamp": {
  "seconds": CURRENT_SECONDS,
  "nanos": CURRENT_NANOS,
}

옵션 2



{
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS,
}
timestamp
receiver_id(레코드 필드 아님) logName
logging.googleapis.com/httpRequest([문자열](/logging/docs/reference/v2/rest/v2/LogEntry#httprequest)) httpRequest
logging.googleapis.com/severity([문자열](/logging/docs/reference/v2/rest/v2/LogEntry#logentrysourcelocation)) severity
logging.googleapis.com/labels(문자열 구조체:문자열) labels
logging.googleapis.com/operation([구조체](/logging/docs/reference/v2/rest/v2/LogEntry#logentryoperation)) operation
logging.googleapis.com/sourceLocation([구조체](/logging/docs/reference/v2/rest/v2/LogEntry#logentrysourcelocation)) sourceLocation

나머지 구조화된 레코드 필드는 jsonPayload 구조의 일부로 남습니다.

일반 Linux 로그 파일

다음 표에는 자주 사용되는 Linux 애플리케이션의 일반 로그 파일이 나와 있습니다.

애플리케이션 일반 로그 파일
apache Apache 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Apache 웹 서버를 참조하세요.
Cassandra Cassandra 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Cassandra를 참조하세요.
chef /var/log/chef-server/bookshelf/current
/var/log/chef-server/chef-expander/current
/var/log/chef-server/chef-pedant/http-traffic.log
/var/log/chef-server/chef-server-webui/current
/var/log/chef-server/chef-solr/current
/var/log/chef-server/erchef/current
/var/log/chef-server/erchef/erchef.log.1
/var/log/chef-server/nginx/access.log
/var/log/chef-server/nginx/error.log
/var/log/chef-server/nginx/rewrite-port-80.log
/var/log/chef-server/postgresql/current
gitlab /home/git/gitlab/log/application.log
/home/git/gitlab/log/githost.log
/home/git/gitlab/log/production.log
/home/git/gitlab/log/satellites.log
/home/git/gitlab/log/sidekiq.log
/home/git/gitlab/log/unicorn.stderr.log
/home/git/gitlab/log/unicorn.stdout.log
/home/git/gitlab-shell/gitlab-shell.log
jenkins /var/log/jenkins/jenkins.log
jetty /var/log/jetty/out.log
/var/log/jetty/*.request.log
/var/log/jetty/*.stderrout.log
joomla /var/www/joomla/logs/*.log
magento /var/www/magento/var/log/exception.log
/var/www/magento/var/log/system.log
/var/www/magento/var/report/*
mediawiki /var/log/mediawiki/*.log
memcached Memcached 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Memcached를 참조하세요.
mongodb MongoDB 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: MongoDB를 참조하세요.
mysql MySQL 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: MySQL을 참조하세요.
nginx nginx 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: nginx를 참조하세요.
postgres PostgreSQL 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: PostgreSQL을 참조하세요.
puppet /var/log/puppet/http.log
/var/log/puppet/masterhttp.log
puppet-enterprise /var/log/pe-activemq/activemq.log
/var/log/pe-activemq/wrapper.log
/var/log/pe-console-auth/auth.log
/var/log/pe-console-auth/cas_client.log
/var/log/pe-console-auth/cas.log
/var/log/pe-httpd/access.log
/var/log/pe-httpd/error.log
/var/log/pe-httpd/other_vhosts_access.log
/var/log/pe-httpd/puppetdashboard.access.log
/var/log/pe-httpd/puppetdashboard.error.log
/var/log/pe-httpd/puppetmasteraccess.log
/var/log/pe-mcollective/mcollective_audit.log
/var/log/pe-mcollective/mcollective.log
/var/log/pe-puppet-dashboard/certificate_manager.log
/var/log/pe-puppet-dashboard/event-inspector.log
/var/log/pe-puppet-dashboard/failed_reports.log
/var/log/pe-puppet-dashboard/live-management.log
/var/log/pe-puppet-dashboard/mcollective_client.log
/var/log/pe-puppet-dashboard/production.log
/var/log/pe-puppetdb/pe-puppetdb.log
/var/log/pe-puppet/masterhttp.log
/var/log/pe-puppet/rails.log
rabbitmq RabbitMQ 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: RabbitMQ를 참조하세요.
redis Redis 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Redis를 참조하세요.
redmine /var/log/redmine/*.log
salt /var/log/salt/key
/var/log/salt/master
/var/log/salt/minion
/var/log/salt/syndic.loc
solr Apache Solr 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Apache Solr을 참조하세요.
sugarcrm /var/www/*/sugarcrm.log
syslog /var/log/syslog/var/log/messages
tomcat Apache Tomcat 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Apache Tomcat을 참조하세요.
zookeeper Apache ZooKeeper 로그 파일에 대한 자세한 내용은 타사 애플리케이션 모니터링: Apache ZooKeeper를 참조하세요.

수집된 기본 라벨

로그는 기본적으로 LogEntry에 다음 라벨을 포함할 수 있습니다.

필드 샘플 값 설명
labels."compute.googleapis.com/resource_name" test_vm 이 로그가 시작된 가상 머신의 이름입니다. 모든 로그에서 작성됩니다.
labels."logging.googleapis.com/instrumentation_source" agent.googleapis.com/apache_access 이 로그가 시작된 수신자 type의 값이며 agent.googleapis.com/ 프리픽스가 붙습니다. 타사 통합의 수신자만 작성합니다.

로깅 프로세서

선택적인 processors 요소에는 각각 PROCESSOR_ID로 식별되는 처리 지시어 집합이 포함됩니다. 프로세서는 수신자에서 수집되는 정보를 조작하는 방법을 기술합니다.

각 프로세서는 고유 식별자와 type 요소를 포함해야 합니다. 유효한 유형은 다음과 같습니다.

  • parse_json: JSON 형식의 구조화된 로그를 파싱합니다.
  • parse_multiline: 여러 줄 로그를 파싱합니다 (Linux만 해당).
  • parse_regex: 정규식 패턴을 통해 텍스트 형식의 로그를 파싱하여 JSON 형식의 구조화된 로그로 변환합니다.
  • exclude_logs: 지정된 규칙과 일치하는 로그를 제외합니다(2.9.0부터).
  • modify_fields: 로그 항목의 필드를 설정/변환합니다(2.14.0부터).

processors 구조는 다음과 같습니다.

processors:
  PROCESSOR_ID:
    type: parse_json
    ...
  PROCESSOR_ID_2:
    type: parse_regex
    ...

type 요소의 값에 따라 다음과 같은 다른 구성 옵션이 사용됩니다.

parse_json 프로세서

구성 구조

processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    <field name within jsonPayload>
    time_format: <strptime format string>

parse_json 프로세서는 LogEntryjsonPayload 필드로 입력 JSON을 파싱합니다. LogEntry의 다른 부분은 특정 특수 최상위 필드를 설정하여 파싱할 수 있습니다.

  • time_key: 선택사항. 로그 항목이 타임스탬프와 함께 필드를 제공하는 경우 이 옵션은 해당 필드의 이름을 지정합니다. 추출된 값은 결과 LogEntrytimestamp 필드를 설정하는 데 사용되고 페이로드에서 삭제됩니다.

    time_key 옵션이 지정된 경우 다음 사항도 지정해야 합니다.

    • time_format: time_key가 사용된 경우 필수입니다. 이 옵션은 제대로 인식되고 분석될 수 있도록 time_key 필드의 형식을 지정합니다. 형식에 대한 자세한 내용은 strptime(3) 가이드를 참조하세요.
구성 예시
processors:
  PROCESSOR_ID:
    type: parse_json

    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

parse_multiline 프로세서

구성 구조

processors:
  PROCESSOR_ID:
    type: parse_multiline

    match_any:
    - type: <type of the exceptions>
      language: <language name>
  • match_any: 필수. 하나 이상의 규칙 목록입니다.

    • type: 필수. 단일 값만 지원됩니다.

      • language_exceptions: 프로세서가 language 옵션의 값에 따라 예외를 하나의 LogEntry로 연결할 수 있습니다.
    • language: 필수. 단일 값만 지원됩니다.

      • java: 일반적인 자바 예외를 하나의 LogEntry로 연결합니다.
구성 예시
processors:
  PROCESSOR_ID:
    type: parse_multiline

    match_any:
    - type: language_exceptions
      language: java

parse_regex 프로세서

구성 구조

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex: <regular expression>

    time_key:    <field name within jsonPayload>
    time_format: <format string>
  • time_key: 선택사항. 로그 항목이 타임스탬프와 함께 필드를 제공하는 경우 이 옵션은 해당 필드의 이름을 지정합니다. 추출된 값은 결과 LogEntrytimestamp 필드를 설정하는 데 사용되고 페이로드에서 삭제됩니다.

    time_key 옵션이 지정된 경우 다음 사항도 지정해야 합니다.

    • time_format: time_key가 사용된 경우 필수입니다. 이 옵션은 제대로 인식되고 분석될 수 있도록 time_key 필드의 형식을 지정합니다. 형식에 대한 자세한 내용은 strptime(3) 가이드를 참조하세요.
  • regex: 필수. 필드를 파싱하는 정규 표현식입니다. 표현식에는 일치하는 하위 표현식의 키 이름이 포함되어야 합니다(예: "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$").

    이름이 지정된 캡처 그룹과 일치하는 텍스트는 LogEntryjsonPayload 필드에 있는 필드에 배치됩니다. 로그에 구조를 더 추가하려면 modify_fields 프로세서를 사용합니다.

    일반적인 Linux 애플리케이션 로그 파일에서 정보를 추출하는 정규 표현식 집합은 일반 Linux 로그 파일을 참조하세요.

구성 예시
processors:
  PROCESSOR_ID:
    type: parse_regex

    regex:       "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$"
    time_key:    time
    time_format: "%Y-%m-%dT%H:%M:%S.%L%Z"

exclude_logs 프로세서

구성 구조:

type: exclude_logs
match_any:
  - <filter>
  - <filter>

이 프로세서의 최상위 구성에는 필터 규칙 목록이 포함된 match_any라는 단일 필드가 포함됩니다.

  • match_any: 필수. 하나 이상의 규칙 목록입니다. 로그 항목이 규칙과 일치할 경우 작업 에이전트는 해당 항목을 수집하지 않습니다.

    작업 에이전트가 수집하는 로그는 LogEntry 구조를 따릅니다. 필드 이름은 대소문자를 구분합니다. 다음 필드와 하위 필드를 기반으로만 규칙을 지정할 수 있습니다.

    • httpRequest
    • jsonPayload
    • labels
    • operation
    • severity
    • sourceLocation

    다음 규칙 예시

    severity =~ "(DEBUG|INFO)"
    

    정규 표현식을 사용하여 모든 DEBUGINFO 수준 로그를 제외합니다.

    규칙은 Cloud Logging 쿼리 언어 구문을 따르지만 Logging 쿼리 언어가 지원하는 기능의 하위 집합만 지원합니다.

    • 비교 연산자: =, !=, :, =~, !~. 문자열 비교만 지원됩니다.
    • 탐색 연산자: . 예를 들면 jsonPayload.message입니다.
    • 부울 연산자: AND, OR, NOT.
    • ( )로 표현식 그룹화

구성 예시

processors:
  PROCESSOR_ID:
    type: exclude_logs
    match_any:
    - '(jsonPayload.message =~ "log spam 1" OR jsonPayload.message =~ "log spam 2") AND severity = "ERROR"'
    - 'jsonPayload.application = "foo" AND severity = "INFO"'

modify_fields 프로세서

modify_fields 프로세서를 사용하면 로그 항목의 구조와 콘텐츠를 맞춤설정할 수 있습니다.

구성 구조

type: modify_fields
fields:
  <destination field>:
    # Source
    move_from: <source field>
    copy_from: <source field>
    static_value: <string>

    # Mutation
    default_value: <string>
    map_values:
      <old value>: <new value>
    type: {integer|float}
    omit_if: <filter>

이 프로세서의 최상위 구성에는 단일 필드인 fields가 포함되며, 이 필드에는 출력 필드 이름과 해당 변환의 매핑이 포함됩니다. 각 출력 필드에는 선택적 소스와 0개 이상의 변형 작업이 적용됩니다.

모든 필드 이름은 Cloud Logging 쿼리 언어의 점으로 구분된 구문을 사용합니다. 필터는 Cloud Logging 쿼리 언어를 사용합니다.

모든 변환은 병렬로 적용됩니다. 즉, 소스 및 필터는 원래 입력 로그 항목에서 작동하므로 동일한 프로세서에 의해 수정되는 다른 필드의 새 값을 참조할 수 없습니다.

소스 옵션: 최대 1개의 지정된 소스가 허용됩니다.

  • 지정된 소스가 없습니다.

    소스 값이 지정되지 않은 경우 대상 필드의 기존 값이 수정됩니다.

  • move_from: <source field>

    <source field>의 값이 대상 필드의 소스로 사용됩니다. 또한 <source field>가 로그 항목에서 삭제됩니다. move_fromcopy_from 모두 소스 필드를 참조하는 경우에도 소스 필드는 삭제됩니다.

  • copy_from: <source field>

    <source field>의 값이 대상 필드의 소스로 사용됩니다. <source field>move_from 작업에서도 참조되거나 달리 수정되지 않는 한 로그 항목에서 삭제되지 않습니다.

  • static_value: <string>

    <string> 정적 문자열이 대상 필드의 소스로 사용됩니다.

변형 옵션: 단일 필드에 0개 이상의 변형 연산자가 적용될 수 있습니다. 여러 연산자가 제공되면 항상 다음 순서로 적용됩니다.

  1. default_value: <string>

    소스 필드가 없으면 출력 값이 <string>으로 설정됩니다. 소스 필드가 이미 있는 경우(빈 문자열이 포함되었더라도) 원래 값은 수정되지 않습니다.

  2. map_values: <map>

    입력 값이 <map>의 키 중 하나와 일치하면 출력 값이 맵의 해당 값으로 바뀝니다.

  3. map_values_exclusive: {true|false}

    <source field> 값이 map_values 쌍에서 지정된 키와 일치하지 않은 경우 대상 필드는 map_values_exclusive가 true이면 강제로 설정 해제되거나 map_values_exclusive가 false이면 그대로 유지됩니다.

  4. type: {integer|float}

    입력 값은 정수 또는 부동 소수점으로 변환됩니다. 문자열을 숫자로 변환할 수 없으면 출력 값이 설정되지 않습니다. 문자열에 부동 소수점 수가 있지만 유형이 integer로 지정되면 숫자가 정수로 잘립니다.

    Cloud Logging API는 JSON을 사용하므로 전체 64비트 정수를 지원하지 않습니다. 64비트 이상의 정수가 필요한 경우 로그 항목에 문자열로 저장해야 합니다.

  5. omit_if: <filter>

    필터가 입력 로그 레코드와 일치하면 출력 필드가 설정 해제됩니다. 다음과 같이 자리표시자 값을 삭제하는 데 사용할 수 있습니다.

    httpRequest.referer:
      move_from: jsonPayload.referer
      omit_if: httpRequest.referer = "-"
    

샘플 구성

parse_json 프로세서는 다음을 포함하는 JSON 파일을 변환합니다.

{
  "http_status": "400",
  "path": "/index.html",
  "referer": "-"
}

다음과 같은 LogEntry 구조로 변환합니다.

{
  "jsonPayload": {
    "http_status": "400",
    "path": "/index.html",
    "referer": "-"
  }
}

그 다음 modify_fields를 사용하여 이 LogEntry로 변환할 수 있습니다.

{
  "httpRequest": {
    "status": 400,
    "requestUrl": "/index.html",
  }
}

또한 작업 에이전트 구성을 사용합니다.

logging:
  receivers:
    in:
      type: files
      include_paths:
      - /var/log/http.json
  processors:
    parse_json:
      type: parse_json
    set_http_request:
      type: modify_fields
      fields:
        httpRequest.status:
          move_from: jsonPayload.http_status
          type: integer
        httpRequest.requestUrl:
          move_from: jsonPayload.path
        httpRequest.referer:
          move_from: jsonPayload.referer
          omit_if: jsonPayload.referer = "-"
  pipelines:
    pipeline:
      receivers: [in]
      processors: [parse_json, set_http_request]

이 구성은 /var/log/http.json에서 JSON 형식의 로그를 읽고 로그의 필드에서 httpRequest 구조의 일부를 채웁니다.

Logging 서비스

Logging 서비스는 작업 에이전트의 자체 로그의 세부정보 수준을 맞춤설정하고 로깅 수신기 및 처리기를 함께 파이프라인에 연결합니다. service 섹션에는 log_levelpipelines의 두 가지 요소가 있습니다.

로그 세부정보 수준

작업 에이전트 버전 2.6.0 이상에서 사용 가능한 log_level은 작업 에이전트 로깅 하위 모듈의 자체 로그에 대한 세부정보 수준을 맞춤설정합니다. 기본값은 info입니다. 사용 가능한 옵션은 error, warn, info, debug, trace입니다.

파이프라인 로깅

pipelines는 여러 파이프라인 ID 및 정의를 포함할 수 있습니다. 각 pipeline 정의는 다음 요소로 구성됩니다.

  • receivers: 새 파이프라인에 필요합니다. 로깅 수신자에 설명된 대로 수신자 ID 목록입니다. 목록에서 수신자 ID 순서는 중요하지 않습니다. 파이프라인은 나열된 모든 수신자에서 데이터를 수집합니다.

  • processors: 선택사항. 로깅 프로세서에 설명된 대로 프로세서 ID의 목록입니다. 목록에 있는 프로세서 ID의 순서가 중요합니다. 각 레코드는 나열된 순서로 프로세서를 통해 실행됩니다.

로깅 service 구성 예시

service 구성의 구조는 다음과 같습니다.

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

기본 제공되는 로깅 수집을 해제하려면 빈 receivers 목록을 사용하고 프로세서 없이 기본 파이프라인을 다시 정의합니다. 전체 로깅 구성은 다음과 같습니다.

logging:
  service:
    pipelines:
      default_pipeline:
        receivers: []

다음 service 구성은 ID custom_pipeline인 파이프라인을 정의합니다.

logging:
  service:
    pipelines:
      custom_pipeline:
        receivers:
        - RECEIVER_ID
        processors:
        - PROCESSOR_ID

다음 service 구성은 대신 로깅 하위 모듈의 로그 세부정보 수준을 debug로 맞춤설정합니다.

logging:
  service:
    log_level: debug

측정항목 구성

metrics 구성에는 이전에 설명된 구성 모델이 사용됩니다.

  • receivers: 수신자 정의 목록입니다. receiver는 측정항목의 소스를 설명합니다. 예를 들어 cpu 또는 memory 같은 시스템 측정항목이 있습니다. 이 목록의 수신자는 여러 파이프라인 간에 공유 가능합니다.
  • processors: 프로세서 정의의 목록입니다. processor는 수신자에 의해 수집된 측정항목을 수정하는 방법을 설명합니다.
  • service: pipeline 정의 목록인 pipelines 섹션을 포함합니다. pipelinereceivers 목록과 processors 목록을 연결하여 데이터 흐름을 구성합니다.

다음 섹션에서는 이러한 각 요소에 대해 설명합니다.

측정항목 수신자

receivers 요소에는 수신자 정의 집합이 포함됩니다. 수신자는 cpumemory와 같은 측정항목을 검색할 위치를 설명합니다. 수신자는 여러 파이프라인에서 공유될 수 있습니다.

측정항목 수신자 구조

각 수신자에 식별자 RECEIVER_ID가 있고 type 요소가 포함되어야 합니다. 유효한 유형은 다음과 같습니다.

  • hostmetrics
  • iis(Windows만 해당)
  • mssql(Windows만 해당)

수신자는 작업 collection_interval 옵션을 지정할 수도 있습니다. 값은 기간 형식(예: 30s 또는 2m)으로 표시됩니다. 기본값은 60s입니다.

각 수신자 유형은 측정항목 집합을 수집합니다. 포함된 특정 측정항목에 대한 상세 설명은 수신자 유형에서 수집한 측정항목을 참조하세요.

각 유형에 대해 수신자를 하나만 만들 수 있습니다. 예를 들어 hostmetrics 유형으로 2개의 수신자를 만들 수 없습니다.

측정항목 수신자에서 수집 간격 변경

일부 중요한 워크로드는 빠른 알림이 필요할 수 있습니다. 측정항목의 수집 간격을 줄이면 더 민감한 알림을 구성할 수 있습니다. 알림 평가 방법에 대한 자세한 내용은 메트릭 기반 알림 정책의 동작을 참조하세요.

예를 들어 다음 수신자는 호스트 측정항목의 수집 간격(수신자 ID: hostmetrics)을 기본값인 60초에서 10초로 변경합니다.

metrics:
  receivers:
    hostmetrics:
      type: hostmetrics
      collection_interval: 10s

동일한 기법을 사용하여 Windows iismssql 측정항목 수신자의 수집 간격을 재정의할 수도 있습니다.

수신자에서 수집한 측정항목

작업 에이전트가 수집한 측정항목에는 agent.googleapis.com/GROUP 패턴으로 시작하는 식별자가 있습니다. GROUP 구성요소는 관련된 측정항목 집합을 식별합니다. 여기에는 cpu, network 등의 값이 포함됩니다.

hostmetrics 수신자는 다음 측정항목 그룹을 수집합니다. 자세한 내용은 작업 에이전트 측정항목 페이지에서 각 그룹에 대해 연결된 섹션을 참조하세요.

그룹 측정항목
cpu 1분 간격으로 CPU 로드
5분 간격으로 CPU 로드
15분 간격으로 CPU 로드
CPU 번호 및 CPU 상태의 라벨이 있는 CPU 사용량
CPU 번호 및 CPU 상태의 라벨이 있는 CPU 사용량 비율
disk 기기 라벨이 있는 디스크 바이트 읽기
기기 라벨이 있는 디스크 바이트 쓰기
기기 라벨이 있는 디스크 I/O 시간
기기 라벨이 있는 디스크 가중치가 적용된 I/O 시간
기기 라벨이 있는 디스크 대기 작업
기기 및 방향의 라벨이 있는 디스크 병합 작업
기기 및 방형의 라벨이 있는 디스크 작업
기기 및 방향의 라벨이 있는 디스크 작업 시간
기기 및 상태 라벨이 있는 디스크 사용량
기기 및 상태의 라벨이 있는 디스크 사용률
interface
Linux만 해당
총 네트워크 오류 수
네트워크를 통해 전송된 패킷의 총 개수
네트워크를 통해 전송된 총 바이트 수
memory 상태(버퍼링됨, 캐시됨, 무료, slab, 중고) 라벨이 있는 메모리 사용량
상태(버퍼링됨, 캐시됨, 무료, slab, 중고) 라벨이 있는 메모리 사용량 비율
network 포트 및 TCP 상태에 대한 라벨이 포함된 TCP 연결 개수
swap 방향 라벨이 있는 I/O 작업 바꾸기
기기 및 상태 라벨이 있는 사용된 바이트 바꾸기
기기 및 상태 라벨이 있는 사용된 비율 바꾸기
pagefile
Windows만 해당
상태에서 사용된 페이지 파일의 비율
processes 상태 라벨이 있는 프로세스 수
포크된 프로세스 수
프로세스당 프로세스 이름 및 기타 라벨이 있는 디스크 읽기 I/O
프로세스당 프로세스 이름 및 기타 라벨이 있는 디스크 쓰기 I/O
프로세스당 프로세스 이름 및 기타 라벨이 있는 RSS 사용량
프로세스당 프로세스 이름 및 기타 라벨이 있는 VM 사용량

iis 수신자(Windows만 해당)는 iis 그룹의 측정항목을 수집합니다. 자세한 내용은 에이전트 측정항목 페이지를 참조하세요.

그룹 측정항목
iis
Windows만 해당
현재 IIS에 열려 있는 연결
IIS에서 전송된 네트워크 바이트
IIS에 열려 있는 연결
IIS에 전송된 요청

mssql 수신자(Windows만 해당)는 mssql 그룹의 측정항목을 수집합니다. 자세한 내용은 작업 에이전트 측정항목 페이지를 참조하세요.

그룹 측정항목
mssql
Windows만 해당
현재 SQL 서버에 열려 있는 연결
초당 SQL 서버 총 트랜잭션
초당 SQL Server 쓰기 트랜잭션

측정항목 프로세서

processor 요소에는 프로세서 정의 집합이 포함됩니다. 프로세서는 제외할 수신자 유형의 측정항목을 설명합니다. 유일한 지원되는 유형은 metrics_pattern 옵션을 사용하는 exclude_metrics입니다. 값은 수신자에서 수집된 그룹에서 제외하려는 측정항목 유형과 일치하는 glob 목록입니다. 예를 들면 agent.googleapis.com/cpu/* 또는 agent.googleapis.com/processes/*입니다. 개별 측정항목의 정규화된 이름을 찾으려면 작업 에이전트 측정항목 페이지의 그룹 테이블을 참조하세요.

샘플 측정항목 프로세서

다음 예시는 기본 제공 구성에 제공된 exclude_metrics 프로세서를 보여줍니다. 이 프로세서는 비어 있는 metrics_pattern 값을 제공하므로, 측정항목을 제외하지 않습니다.

processors:
  metrics_filter:
    type: exclude_metrics
    metrics_pattern: []

작업 에이전트의 모든 프로세스 측정항목 수집을 사용 중지하려면 다음을 config.yaml 파일에 추가합니다.

metrics:
  processors:
    metrics_filter:
      type: exclude_metrics
      metrics_pattern:
      - agent.googleapis.com/processes/*

이렇게 하면 metrics 서비스의 기본 파이프라인에 적용되는 metrics_filter 프로세서의 수집에서 프로세스 측정항목이 제외됩니다.

측정항목 서비스

측정항목 서비스는 작업 에이전트 측정항목 모듈의 자체 로그에 대한 세부정보 수준을 맞춤설정하고 측정항목 수신기 및 처리기를 함께 파이프라인에 연결합니다. service 섹션에는 log_levelpipelines의 두 가지 요소가 있습니다.

측정항목 세부정보 수준

작업 에이전트 버전 2.6.0 이상에서 사용 가능한 log_level은 작업 에이전트 측정항목 하위 모듈의 자체 로그에 대한 세부정보 수준을 맞춤설정합니다. 기본값은 info입니다. 사용 가능한 옵션은 error, warn, info, debug입니다.

측정항목 파이프라인

service 섹션에는 여러 파이프라인 ID 및 정의가 포함될 수 있는 단일 요소 pipelines가 있습니다. 각 pipeline 정의는 다음 요소로 구성됩니다.

  • receivers: 새 파이프라인에 필요합니다. 측정항목 수신자에 설명된 대로 수신자 ID 목록입니다. 목록에서 수신자 ID 순서는 중요하지 않습니다. 파이프라인은 나열된 모든 수신자에서 데이터를 수집합니다.

  • processors: 선택사항. 측정항목 프로세서에 설명된 대로 프로세서 ID의 목록입니다. 목록에 있는 프로세서 ID의 순서가 중요합니다. 각 측정항목 포인트는 나열된 순서로 프로세서를 통해 실행됩니다.

측정항목 service 구성 예시

service 구성의 구조는 다음과 같습니다.

service:
  log_level: CUSTOM_LOG_LEVEL
  pipelines:
    PIPELINE_ID:
      receivers:  [...]
      processors: [...]
    PIPELINE_ID_2:
      receivers:  [...]
      processors: [...]

호스트 측정항목의 기본 제공 수집을 해제하려면 빈 receivers 목록을 사용하고 프로세서 없이 기본 파이프라인을 다시 정의합니다. 전체 측정항목 구성은 다음과 같습니다.

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers: []

다음 예시에서는 Windows의 기본 탑재 service 구성을 보여줍니다.

metrics:
  service:
    pipelines:
      default_pipeline:
        receivers:
        - hostmetrics
        - iis
        - mssql
        processors:
        - metrics_filter

다음 service 구성은 대신 측정항목 하위 모듈의 로그 세부정보 수준을 debug로 맞춤설정합니다.

metrics:
  service:
    log_level: debug