운영 에이전트 구성

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

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

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

    • 로깅 수집을 중지하려면 예시 로깅 service 구성을 참조하세요.

    • 호스트 측정항목 수집을 중지하려면 예시 측정항목 service 구성을 참조하세요.

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

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

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

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

  • 에이전트의 로그 순환 방식을 맞춤설정합니다. 로그 로테이션 구성을 참조하세요.

  • 지원되는 서드 파티 애플리케이션에서 측정항목 및 로그를 수집합니다. 지원되는 애플리케이션 목록은 서드 파티 애플리케이션 모니터링을 참조하세요.

  • Prometheus 수신자를 사용하여 커스텀 측정항목을 수집합니다.

  • OpenTelemetry 프로토콜(OTLP) 수신자를 사용하여 커스텀 측정항목 및 trace를 수집합니다.

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

구성 모델

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

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

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

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

기본 탑재 구성

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

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]

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 파일에서 동일한 식별자로 선언하여 다시 정의합니다. 운영 에이전트 버전 2.31.0부터 에이전트의 로그 로테이션 기능을 구성할 수도 있습니다. 자세한 내용은 운영 에이전트에서 로그 순환 구성을 참조하세요.

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

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

기본 탑재 구성을 변경하는 다른 예시는 로깅 구성 및 측정항목 구성을 참조하세요. 또한 로깅 또는 측정항목 데이터 컬렉션을 해제할 수 있습니다. 이러한 변경사항에 대해서는 예시 로깅 service 구성 및 측정항목 service 구성에서 설명합니다.

이 파일을 사용하여 에이전트가 자체 로그를 수집하고 해당 로그를 Cloud Logging으로 보내지 못하게 할 수 있습니다. 자세한 내용은 자체 로그 수집을 참조하세요.

이 파일을 사용하여 에이전트의 로그 로테이션 기능을 구성합니다. 자세한 내용은 운영 에이전트에서 로그 순환 구성을 참조하세요.

운영 에이전트가 Cloud Logging 및 Cloud Monitoring 이외의 서비스로 로그 또는 측정항목을 내보내도록 구성할 수 없습니다.

로깅 구성

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

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

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

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

운영 에이전트는 Cloud Logging으로 로그를 전송합니다. 다른 서비스로 로그를 내보내도록 구성할 수 없습니다. 하지만 Cloud Logging에서 로그를 내보내도록 구성할 수 있습니다. 자세한 내용은 지원되는 대상으로 로그 라우팅을 참조하세요.

로깅 수신자

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

로깅 수신자 구조

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

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

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 수신자(Linux에만 해당):

  • transport_protocol: 지원되는 값: tcp, udp

  • listen_host: 리슨할 IP 주소입니다.

  • listen_port: 리슨할 포트입니다.

• tcp 수신자:

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

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

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

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

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

  • receiver_version: (선택사항) 사용할 Windows Event Log API를 제어합니다. 지원되는 값은 1 및 2입니다. 기본값은 1입니다.

  • render_as_xml: (선택사항) true로 설정되면 jsonPayload.Message 및 jsonPayload.StringInserts를 제외한 모든 이벤트 로그 필드가 jsonPayload.raw_xml이라는 문자열 필드에 XML 문서로 렌더링됩니다. 기본값은 false입니다. receiver_version이 1이면 true로 설정할 수 없습니다.

로깅 수신자 예시

샘플 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 수신자(Linux만 해당):

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]

버전 2를 사용하도록 기본 제공 수신자를 재정의하는 샘플 windows_event_log 수신자:

receivers:
  windows_event_log:
    type: windows_event_log

    channels: [System,Application,Security]
    receiver_version: 2

샘플 systemd_journald 수신자:

receivers:
  RECEIVER_ID:
    type: systemd_journald

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

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

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

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

{
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS,
}

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

일반 Linux 로그 파일

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

기본 수집 라벨

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

로깅 프로세서

선택적인 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 프로세서는 LogEntry의 jsonPayload 필드로 입력 JSON을 파싱합니다. LogEntry의 다른 부분은 특정 특수 최상위 필드를 설정하여 파싱할 수 있습니다.

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

  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로 연결합니다.
    • python: 일반적인 Python 예외를 하나의 LogEntry로 연결합니다.
    • go: 일반적인 Go 예외를 하나의 LogEntry로 연결합니다.

구성 예시

logging:
  receivers:
    custom_file1:
      type: files
      include_paths:
      - /tmp/test-multiline28
  processors:
    parse_java_multiline:
      type: parse_multiline
      match_any:
      - type: language_exceptions
        language: java
    extract_structure:
      type: parse_regex
      field: message
      regex: "^(?<time>[\d-]*T[\d:.Z]*) (?<severity>[^ ]*) (?<file>[^ :]*):(?<line>[\d]*) - (?<message>(.|\\n)*)$"
      time_key: time
      time_format: "%Y-%m-%dT%H:%M:%S.%L"
    move_severity:
      type: modify_fields
      fields:
        severity:
          move_from: jsonPayload.severity
  service:
    pipelines:
      pipeline1:
        receivers: [custom_file1]
        processors: [parse_java_multiline, extract_structure, move_severity]

이전 구성을 사용하고 로그 파일에 다음 콘텐츠가 포함된 경우:

2022-10-17T22:00:00.187512963Z ERROR HelloWorld:16 - javax.servlet.ServletException: Something bad happened
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)
    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)
Caused by: com.example.myproject.MyProjectServletException
    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)
    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)
    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)
    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)
    ... 27 common frames omitted

에이전트가 다음 형식으로 Cloud Logging에 로그를 삽입합니다.

{
  "insertId": "...",
  "jsonPayload": {
    "line": "16",
    "message": "javax.servlet.ServletException: Something bad happened\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:60)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.ExceptionHandlerFilter.doFilter(ExceptionHandlerFilter.java:28)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1157)\n    at com.example.myproject.OutputBufferFilter.doFilter(OutputBufferFilter.java:33)\nCaused by: com.example.myproject.MyProjectServletException\n    at com.example.myproject.MyServlet.doPost(MyServlet.java:169)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:727)\n    at javax.servlet.http.HttpServlet.service(HttpServlet.java:820)\n    at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:511)\n    at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1166)\n    at com.example.myproject.OpenSessionInViewFilter.doFilter(OpenSessionInViewFilter.java:30)\n    ... 27 common frames omitted\n",
    "file": "HelloWorld"
  },
  "resource": {
    "type": "gce_instance",
    "labels": {
      "instance_id": "...",
      "project_id": "...",
      "zone": "..."
    }
  },
  "timestamp": "2022-10-17T22:00:00.187512963Z",
  "severity": "ERROR",
  "labels": {
    "compute.googleapis.com/resource_name": "..."
  },
  "logName": "projects/.../logs/custom_file",
  "receiveTimestamp": "2022-10-18T03:12:38.430364391Z"
}

parse_regex 프로세서

구성 구조

processors:
  PROCESSOR_ID:
    type: parse_regex

    regex: <regular expression>

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

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

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

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

• regex: (필수사항) 필드를 파싱하는 정규 표현식입니다. 표현식에는 일치하는 하위 표현식의 키 이름이 포함되어야 합니다(예: "^(?<time>[^ ]*) (?<severity>[^ ]*) (?<msg>.*)$").

  이름이 지정된 캡처 그룹과 일치하는 텍스트는 LogEntry의 jsonPayload 필드에 있는 필드에 배치됩니다. 로그에 구조를 더 추가하려면 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
  • trace
  • spanId

  다음 규칙 예시

  severity =~ "(DEBUG|INFO)"
  

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

  규칙은 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_from과 copy_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 = "-"
  service:
    pipelines:
      pipeline:
        receivers: [in]
        processors: [parse_json, set_http_request]

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

Logging 서비스

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

• log_level
• pipelines

로그 세부정보 수준

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

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

logging:
  service:
    log_level: debug

파이프라인 로깅

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: [...]

에이전트가 /var/log/message 또는 /var/log/syslog 항목을 수집하고 전송하지 않도록 하려면 빈 receivers 목록을 사용하고 프로세서 없이 기본 파이프라인을 다시 정의합니다. 에이전트가 모니터링 하위 구성요소의 로그를 수집할 수 있어야 하기 때문에 이 구성은 에이전트의 로깅 하위 구성요소를 중지하지 않습니다. 빈 전체 로깅 구성은 다음과 같습니다.

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

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

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

측정항목 구성

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

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

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

운영 에이전트는 Cloud Monitoring으로 측정항목을 전송합니다. 측정항목을 다른 서비스로 내보내도록 구성할 수 없습니다.

측정항목 수신자

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

측정항목 수신자 구조

각 수신자에 식별자 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 iis 및 mssql 측정항목 수신자의 수집 간격을 재정의할 수도 있습니다.

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

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

hostmetrics 수신자

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

iis 수신자(Windows만 해당)

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

mssql 수신자(Windows만 해당)

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

측정항목 프로세서

processor 요소에는 프로세서 정의 집합이 포함됩니다. 프로세서는 제외할 수신자 유형의 측정항목을 설명합니다. 유일한 지원되는 유형은 metrics_pattern 옵션을 사용하는 exclude_metrics입니다. 값은 수신자에서 수집된 그룹에서 제외하려는 운영 에이전트 측정항목 유형과 일치하는 glob 목록입니다. 예를 들면 다음과 같습니다.

• 모든 에이전트 CPU 측정항목을 제외하려면 agent.googleapis.com/cpu/*를 지정합니다.
• 에이전트 CPU 사용률 측정항목을 제외하려면 agent.googleapis.com/cpu/utilization을 지정합니다.
• Apache Cassandra 타사 통합으로 수집된 측정항목에서 클라이언트 측 요청 수 측정항목을 제외하려면 workloads.googleapis.com/cassandra.client.request.count를 지정합니다.
• Apache Cassandra 타사 통합으로 수집된 측정항목에서 모든 클라이언트 측 측정항목을 제외하려면 workloads.googleapis.com/cassandra.client.*를 지정합니다.

샘플 측정항목 프로세서

다음 예시는 기본 제공 구성에 제공된 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_level 및 pipelines의 두 가지 요소가 있습니다.

측정항목 세부정보 수준

운영 에이전트 버전 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

자체 로그 수집

기본적으로 운영 에이전트의 Fluent Bit 자체 로그는 Cloud Logging으로 전송됩니다. 이러한 로그에는 많은 정보가 포함될 수 있으며, 추가 볼륨으로 인해 Cloud Logging 사용 비용이 증가할 수 있습니다.

운영 에이전트 버전 2.44.0부터 default_self_log_file_collection 옵션을 사용하여 이러한 자체 로그 수집을 중지할 수 있습니다.

자체 로그 수집을 사용 중지하려면 사용자 지정된 구성 파일에 global 섹션을 추가하고 default_self_log_file_collection 옵션을 false 값으로 설정합니다.

logging:  ...
metrics:  ...
global:
  default_self_log_file_collection: false

로그 로테이션 구성

운영 에이전트 버전 2.31.0부터 구성 파일을 사용하여 에이전트의 로그 로테이션 기능을 설정할 수도 있습니다. 자세한 내용은 운영 에이전트에서 로그 순환 구성을 참조하세요.