MonitoringPlugin ko KR

MonitoringPlugin

MonitoringPlugin 은 공식 ASF 플러그인 으로, Prometheus 시계열(time-series) 데이터베이스를 통해 ASF 프로세스를 모니터링할 수 있게 해줍니다.

---

스크린샷

보기

---

요구사항

기술적 제약 으로 인해, 이 플러그인은 ASF의 generic 버전을 필요로 합니다.

---

플러그인 활성화하기

ASF는 기본적으로 MonitoringPlugin 을 함께 제공하지 않지만 , 모든 ASF 릴리스에 선택적 추가 요소로 포함되어 있습니다. 사용 중인 ASF 버전과 일치하는 공식 릴리스 에서 플러그인을 다운로드한 다음, 해당 플러그인을 위한 전용 plugins/ArchiSteamFarm.OfficialPlugins.Monitoring 디렉터리를 생성하고, 마지막으로 그곳에 압축 파일을 풀면 됩니다.

다음 ASF 실행 시, 표준 ASF 로깅 메커니즘을 통해 로그에서 플러그인이 성공적으로 로드되었음을 확인할 수 있습니다. IPC 인터페이스에서 /Api/metrics URL로 이동하여 이를 확인할 수도 있습니다. IPC 비밀번호를 사용 중이라면 적절한 인증이 필요하며, 예를 들어 /Api/metrics URL에 ?password=<YourIPCPassword> 을 추가하면 됩니다. 표시되는 내용은 아래와 유사한 형태여야 합니다:

# TYPE asf_build_info gauge
# HELP asf_build_info Build information about ASF in form of label values
asf_build_info{variant="source",version="6.0.2.5"} 1 1713715703686

# TYPE asf_runtime_info gauge
# HELP asf_runtime_info Runtime information about ASF in form of label values
asf_runtime_info{framework=".NET 8.0.4",operating_system="Debian GNU/Linux trixie/sid",runtime="linux-x64"} 1 1713715703686
(...)

ASF 및 봇과 관련된 지표(metrics)는 이름에 전용 접두사(prefix) asf_ 를 가지고 있습니다. .NET 런타임이나 ASF의 HttpClient 와 관련된 그 외의 지표들은 범용 .NET 프로세스 규칙에 따라 자동 생성되며, 이러한 접두사를 갖지 않습니다.

---

Prometheus 설정

플러그인이 정상적으로 작동하는 것을 확인했다면, Prometheus 인스턴스에 다음과 같이 scrape 설정을 추가할 수 있습니다:

scrape_configs:
  - job_name: ArchiSteamFarm
    metric_name_escaping_scheme: underscores # Remove if using Prometheus V2.x - read more below
    metrics_path: /Api/metrics
    params:
      password:
        - YourIPCPassword
    static_configs:
      - targets:
          - 127.0.0.1:1242

당연히, 호스팅 중인 Prometheus 인스턴스가 ASF의 IPC 인터페이스에 접근할 수 있도록 해야 하며, password와 targets는 사용 환경에 맞게 조정해야 합니다. IPC 비밀번호를 설정하지 않은 경우(권장하지 않음), params 섹션 추가는 생략할 수 있습니다. 서로 다른 IPC 비밀번호를 사용하는 여러 ASF 인스턴스를 운영 중인 경우, 쿼리 매개변수는 target별로 설정할 수 없으므로 인스턴스마다 하나씩 추가적인 scrape 설정을 추가하면 됩니다. 그렇지 않다면, 동일한 비밀번호를 공유하는 경우 여러 targets 를 함께 선언할 수 있습니다.

---

Grafana 대시보드

Prometheus가 지표(metrics)를 수집하고 나면, Grafana 를 사용하여 시각화할 수 있습니다. 이 플러그인은 표준 IPC 메커니즘을 통해 제공되는 /grafana-dashboard.json 파일을 함께 제공하므로, 기본 설정으로 ASF 인스턴스를 실행 중이라면 여기 에서 다운로드할 수 있습니다. 또는, 저희 저장소(repository) 에서도 JSON 파일을 받으실 수 있습니다.

---

Prometheus, Grafana 대시보드 및 메트릭 이스케이핑 방식

ASF는 V6.3.8.4부터 다양한 메트릭 이스케이핑 방식을 지원하며, V6.3.9.4부터는 통합된 완전한 솔루션을 제공합니다 (#3607 의 일환).

다만 이로 인해 Grafana 대시보드에 약간의 문제가 발생하는데, 이는 정상 작동을 위해 Prometheus가 파싱하는 정확한 메트릭 이름이 필요하기 때문이며, 해당 소프트웨어는 V2.x와 V3.x 버전에 따라 기본 동작 방식이 서로 다릅니다. 자세한 내용은 UTF-8 Prometheus 문서 를 참고하세요.

Prometheus V3.x가 널리 보급될 때까지 (현재는 debian stable을 기준으로 함), 저희는 기존(legacy) 방식을 사용할 것을 권장합니다. 즉:

• 저희 Grafana 대시보드는 기본적으로 Prometheus V2.x가 인식하는 밑줄(underscore) 이름 방식으로 제공됩니다
• Prometheus V3.x를 사용하는 경우, 위 예시와 같이 ASF 스크래핑 설정에 metric_name_escaping_scheme: underscores를 추가하세요

이는 Prometheus V3.x는 기존(legacy) 방식을 사용하도록 쉽게 설정할 수 있는 반면, Prometheus V2.x는 새로운 방식을 강제로 사용하게 할 수 있는 작업별(job-specific) 옵션이 없기 때문입니다.

향후 저희는 Grafana 대시보드를 새로 권장되는 기본값에 맞게 리팩터링할 예정이며, 이 경우 해당 설정은 더 이상 필요하지 않게 됩니다. 지금 그렇게 변경하면 기존 Prometheus 사용자들에게 문제가 발생할 수 있어 아직은 적절하지 않습니다.

물론 ASF 자체의 플러그인은 다양한 포맷 옵션을 모두 지원하므로, 원하시는 방식을 자유롭게 선택하여 Grafana 대시보드를 직접 맞춰 사용하실 수도 있습니다 - 저희는 그저 간단한 한 줄짜리 설정 변경 권장 사항으로 이를 좀 더 쉽게 만들어드리는 것뿐입니다.