메트릭 reporter

메트릭 reporter (Metric Reporters)

Flink는 메트릭을 외부 시스템으로 보고하는 것을 허용해요. Flink 메트릭 시스템에 대한 자세한 정보는 메트릭 시스템 문서를 참고해요. 메트릭은 Flink 구성 파일에서 하나 또는 여러 reporter를 구성해 외부 시스템에 노출할 수 있어요. 이 reporter는 각 job과 task manager가 시작될 때 인스턴스화돼요.

출처: 문서

본문

모든 reporter에 일반적으로 적용되는 파라미터 목록은 다음과 같아요. 모든 프로퍼티는 구성에서 metrics.reporter.<reporter_name>.<property>를 설정해 구성돼요. Reporter는 구현 특정 파라미터를 추가로 제공할 수 있으며, 이는 해당 reporter 섹션에 문서화돼 있어요.

키 (Key)	기본값 (Default)	타입 (Type)	설명 (Description)
factory.class	(none)	String	<name>이라는 reporter에 사용할 reporter factory 클래스.
interval	10 s	Duration	<name>이라는 reporter에 사용할 reporter 간격. push 기반 reporter에만 적용돼요.
scope.delimiter	"."	String	<name>이라는 reporter의 메트릭 식별자를 조립하는 데 사용되는 구분자.
scope.variables.additional		Map	<name>이라는 reporter에 포함해야 할 추가 변수 맵. tag 기반 reporter에만 적용돼요.
scope.variables.excludes	"."	String	<name>이라는 reporter에서 제외해야 할 변수 집합. tag 기반 reporter에만 적용돼요.
filter.includes	"::*"	List<String>	<name>이라는 reporter에 포함해야 할 메트릭. 필터는 목록으로 지정되며 각 필터는 다음 형식을 따름: <scope>[:<name>[,<name>][:<type>[,<type>]]]. 메트릭은 scope 패턴과 이름 패턴 중 하나 이상, 타입 중 하나 이상이 일치하면 필터와 일치. scope: 논리 scope 기반 필터. *가 모든 문자 시퀀스와 일치하고 .가 scope 구성 요소를 구분하는 패턴으로 지정. 예: "jobmanager.job"은 JobManager의 모든 작업 관련 메트릭과 일치, ".job"은 모든 작업 관련 메트릭과 일치, ".job."은 job 수준 아래의 모든 메트릭과 일치(예: task/operator 메트릭). name: 메트릭 이름 기반 필터. *가 모든 문자 시퀀스와 일치하는 쉼표로 구분된 패턴 목록으로 지정. 예: "Records,Bytes"는 이름에 "Records" 또는 "Bytes"가 포함된 메트릭과 일치. type: 메트릭 타입 기반 필터. [counter, meter, gauge, histogram] 메트릭 타입의 쉼표로 구분된 목록으로 지정. 예: ":numRecords*"는 numRecordsIn 같은 메트릭과 일치, ".job.task.operator:numRecords"는 operator 수준의 numRecordsIn 같은 메트릭과 일치, ".job.task.operator:numRecords:meter"는 operator 수준의 numRecordsInPerSecond 같은 meter 메트릭과 일치, ":numRecords,numBytes*:counter,meter"는 numRecordsInPerSecond 같은 모든 counter/meter 메트릭과 일치.
filter.excludes		List<String>	<name>이라는 reporter에서 제외해야 할 메트릭. 형식은 filter.includes와 동일.
<parameter>	(none)	String	<name>이라는 reporter의 파라미터 <parameter>를 구성.

모든 reporter 구성은 factory.class 프로퍼티를 포함해야 해요. 일부 reporter(Scheduled라고 함)는 reporting 간격 지정을 허용해요.

여러 reporter를 지정하는 reporter 구성 예:

metrics.reporters: my_jmx_reporter,my_other_reporter

metrics.reporter.my_jmx_reporter.factory.class: org.apache.flink.metrics.jmx.JMXReporterFactory
metrics.reporter.my_jmx_reporter.port: 9020-9040
metrics.reporter.my_jmx_reporter.scope.variables.excludes: job_id;task_attempt_num
metrics.reporter.my_jmx_reporter.scope.variables.additional: cluster_name:my_test_cluster,tag_name:tag_value

metrics.reporter.my_other_reporter.factory.class: org.apache.flink.metrics.graphite.GraphiteReporterFactory
metrics.reporter.my_other_reporter.host: 192.168.1.1
metrics.reporter.my_other_reporter.port: 10000

중요: reporter를 포함하는 jar은 Flink 시작 시 접근 가능해야 해요. Reporter는 플러그인으로 로드돼요. 이 페이지에 문서화된 모든 reporter는 기본적으로 사용 가능해요.

자신만의 Reporter를 작성하려면 org.apache.flink.metrics.reporter.MetricReporter 인터페이스를 구현해요. Reporter가 정기적으로 보고서를 보내야 한다면 Scheduled 인터페이스도 구현해야 해요. report() 메서드가 상당한 시간 동안 차단하지 않아야 하고, 더 많은 시간이 필요한 reporter는 대신 연산을 비동기로 실행해야 한다는 점에 주의해요. 추가로 MetricReporterFactory를 구현하면 reporter를 플러그인으로도 로드할 수 있어요.

식별자 vs. 태그 (Identifiers vs. tags)

일반적으로 reporter가 메트릭을 내보내는 형식은 2가지예요. 식별자 기반 reporter는 모든 scope 정보와 메트릭 이름을 포함한 플랫 문자열을 조립해요. 예는 job.MyJobName.numRestarts일 수 있어요. 반면 tag 기반 reporter는 논리 scope와 메트릭 이름(예: job.numRestarts)으로 구성된 일반 메트릭 클래스를 정의하고, 해당 메트릭의 특정 인스턴스를 키-값 쌍 집합, 소위 "tags" 또는 "variables"(예: "jobName=MyJobName")로 보고해요.

Push vs. Pull

메트릭은 push 또는 pull을 통해 내보내져요. Push 기반 reporter는 보통 Scheduled 인터페이스를 구현하고 현재 메트릭 요약을 주기적으로 외부 시스템으로 보내요. Pull 기반 reporter는 대신 외부 시스템이 조회해요.

Reporter

다음 섹션들은 지원되는 reporter를 나열해요.

JMX

(org.apache.flink.metrics.jmx.JMXReporter)

유형: pull/tags

파라미터:

• port - (선택) JMX가 연결을 수신하는 포트. 한 호스트에서 reporter의 여러 인스턴스를 실행하려면(예: 하나의 TaskManager가 JobManager와 함께 배치될 때) 9250-9260 같은 포트 범위를 사용하는 것이 좋아요. 범위가 지정되면 실제 포트가 관련 job 또는 task manager 로그에 표시돼요. 이 설정이 설정되면 Flink는 주어진 포트/범위에 추가 JMX 커넥터를 시작해요. 메트릭은 항상 기본 로컬 JMX 인터페이스에서 사용할 수 있어요.

구성 예:

metrics.reporter.jmx.factory.class: org.apache.flink.metrics.jmx.JMXReporterFactory
metrics.reporter.jmx.port: 8789

JMX로 노출된 메트릭은 함께 object name을 형성하는 도메인과 키-프로퍼티 목록으로 식별돼요. 도메인은 항상 org.apache.flink로 시작하고 일반화된 메트릭 식별자가 뒤따라요. 일반적인 식별자와 달리 scope-포맷의 영향을 받지 않고, 변수를 포함하지 않으며 작업 전체에 걸쳐 일정해요. 이러한 도메인의 예는 org.apache.flink.job.task.numBytesOut일 수 있어요.

키-프로퍼티 목록은 구성된 scope 포맷과 무관하게 주어진 메트릭과 연관된 모든 변수의 값을 포함해요. 그런 목록의 예는 host=localhost,job_name=MyJob,task_name=MyTask일 수 있어요. 따라서 도메인은 메트릭 클래스를 식별하는 반면 키-프로퍼티 목록은 해당 메트릭의 하나(또는 여러) 인스턴스를 식별해요.

Graphite

(org.apache.flink.metrics.graphite.GraphiteReporter)

유형: push/identifier

파라미터:

• host - Graphite 서버 호스트
• port - Graphite 서버 포트
• protocol - 사용할 프로토콜(TCP/UDP)

구성 예:

metrics.reporter.grph.factory.class: org.apache.flink.metrics.graphite.GraphiteReporterFactory
metrics.reporter.grph.host: localhost
metrics.reporter.grph.port: 2003
metrics.reporter.grph.protocol: TCP
metrics.reporter.grph.interval: 60 SECONDS

InfluxDB

(org.apache.flink.metrics.influxdb.InfluxdbReporter)

유형: push/tags

파라미터:

키 (Key)	기본값 (Default)	타입 (Type)	설명 (Description)
connectTimeout	10 s	Duration	(선택) 메트릭용 InfluxDB 연결 타임아웃
consistency	ONE	Enum	(선택) 메트릭용 InfluxDB consistency 레벨. 가능한 값: "ALL", "ANY", "ONE", "QUORUM"
db	(none)	String	메트릭을 저장할 InfluxDB 데이터베이스
host	(none)	String	InfluxDB 서버 호스트
password	(none)	String	(선택) 인증에 사용되는 InfluxDB 사용자 이름의 비밀번호
port	8086	Integer	InfluxDB 서버 포트
retentionPolicy	(none)	String	(선택) 메트릭용 InfluxDB 보존 정책
scheme	http	Enum	InfluxDB 스키마. 가능한 값: "http", "https"
username	(none)	String	(선택) 인증에 사용되는 InfluxDB 사용자 이름
writeTimeout	10 s	Duration	(선택) 메트릭용 InfluxDB 쓰기 타임아웃

구성 예:

metrics.reporter.influxdb.factory.class: org.apache.flink.metrics.influxdb.InfluxdbReporterFactory
metrics.reporter.influxdb.scheme: http
metrics.reporter.influxdb.host: localhost
metrics.reporter.influxdb.port: 8086
metrics.reporter.influxdb.db: flink
metrics.reporter.influxdb.username: flink-metrics
metrics.reporter.influxdb.password: qwerty
metrics.reporter.influxdb.retentionPolicy: one_hour
metrics.reporter.influxdb.consistency: ANY
metrics.reporter.influxdb.connectTimeout: 60000
metrics.reporter.influxdb.writeTimeout: 60000
metrics.reporter.influxdb.interval: 60 SECONDS

reporter는 지정된 보존 정책(또는 서버에 지정된 기본 정책)을 사용해 http 프로토콜로 InfluxDB 서버에 메트릭을 보내요. 모든 Flink 메트릭 변수(List of all Variables 참고)는 InfluxDB 태그로 내보내져요.

Prometheus

(org.apache.flink.metrics.prometheus.PrometheusReporter)

유형: pull/tags

파라미터:

• port - (선택) Prometheus exporter가 수신하는 포트, 기본값 9249. 한 호스트에서 reporter의 여러 인스턴스를 실행하려면 9250-9260 같은 포트 범위를 사용하는 것이 좋아요.
• filterLabelValueCharacters - (선택) 라벨 값 문자를 필터링할지 지정. 활성화하면 [a-zA-Z0-9:_]와 일치하지 않는 모든 문자가 제거되고, 그렇지 않으면 제거되지 않아요. 이 옵션을 비활성화하기 전에 라벨 값이 Prometheus 요구사항을 충족하는지 확인해주세요.

구성 예:

metrics.reporter.prom.factory.class: org.apache.flink.metrics.prometheus.PrometheusReporterFactory

Flink 메트릭 타입은 다음과 같이 Prometheus 메트릭 타입으로 매핑돼요:

Flink	Prometheus	참고 (Note)
Counter	Gauge	Prometheus 카운터는 감소시킬 수 없어요.
Gauge	Gauge	숫자와 불리언만 지원돼요.
Histogram	Summary	분위수 .5, .75, .95, .98, .99 및 .999
Meter	Gauge	gauge가 meter의 rate를 내보내요.

모든 Flink 메트릭 변수(List of all Variables 참고)는 라벨로 Prometheus에 내보내져요.

PrometheusPushGateway

(org.apache.flink.metrics.prometheus.PrometheusPushGatewayReporter)

유형: push/tags

파라미터:

키 (Key)	기본값 (Default)	타입 (Type)	설명 (Description)
allowList	(none)	String	메트릭 이름의 허용 목록. 기본값은 모든 메트릭 보고
deleteOnShutdown	true	Boolean	종료 시 PushGateway에서 메트릭을 삭제할지 지정. Flink는 메트릭 삭제를 최선으로 시도하지만 보장되지는 않아요.
filterLabelValueCharacters	true	Boolean	라벨 값 문자를 필터링할지 지정. 활성화하면 [a-zA-Z0-9:_]와 일치하지 않는 모든 문자가 제거되고, 그렇지 않으면 제거되지 않아요. 이 옵션을 비활성화하기 전에 라벨 값이 Prometheus 요구사항을 충족하는지 확인해주세요.
groupingKey	(none)	String	모든 메트릭의 group 및 global 라벨인 grouping key를 지정. 라벨 이름과 값은 '='로 구분되고, 라벨은 ';'로 구분(예: k1=v1;k2=v2). grouping key가 Prometheus 요구사항을 충족하는지 확인해주세요.
hostUrl	(none)	String	스킴, 호스트 이름, 포트를 포함한 PushGateway 서버 호스트 URL
jobName	(none)	String	메트릭이 푸시될 job 이름
password	(none)	String	(선택) PushGateway와의 HTTP Basic Authentication용 비밀번호
randomJobNameSuffix	true	Boolean	job 이름에 임의 접미사를 추가할지 지정
username	(none)	String	(선택) PushGateway와의 HTTP Basic Authentication용 사용자 이름

구성 예:

metrics.reporter.promgateway.factory.class: org.apache.flink.metrics.prometheus.PrometheusPushGatewayReporterFactory
metrics.reporter.promgateway.hostUrl: http://localhost:9091
metrics.reporter.promgateway.jobName: myJob
metrics.reporter.promgateway.randomJobNameSuffix: true
metrics.reporter.promgateway.deleteOnShutdown: false
metrics.reporter.promgateway.groupingKey: k1=v1;k2=v2
metrics.reporter.promgateway.interval: 60 SECONDS
metrics.reporter.promgateway.allowList: metricA,metricB

PrometheusPushGatewayReporter는 Prometheus가 스크랩할 수 있는 Pushgateway에 메트릭을 푸시해요. 사용 사례는 Prometheus 문서를 참고해요.

HTTP Basic Authentication

reporter는 보안 PushGateway 인스턴스에 연결하기 위한 HTTP Basic Authentication을 지원해요. 인증을 활성화하려면 username과 password를 모두 구성해요:

metrics.reporter.promgateway.factory.class: org.apache.flink.metrics.prometheus.PrometheusPushGatewayReporterFactory
metrics.reporter.promgateway.hostUrl: https://pushgateway.example.com:9091
metrics.reporter.promgateway.jobName: myJob
metrics.reporter.promgateway.username: flink-reporter
metrics.reporter.promgateway.password: ${PUSHGATEWAY_PASSWORD}
metrics.reporter.promgateway.interval: 60 SECONDS

참고: Basic authentication은 username과 password가 모두 구성될 때만 활성화돼요. 인증이 활성화되면 전송 중 자격 증명을 보호하기 위해 HTTPS를 사용하는 것이 권장돼요.

StatsD

(org.apache.flink.metrics.statsd.StatsDReporter)

유형: push/identifier

파라미터:

• host - StatsD 서버 호스트
• port - StatsD 서버 포트

구성 예:

metrics.reporter.stsd.factory.class: org.apache.flink.metrics.statsd.StatsDReporterFactory
metrics.reporter.stsd.host: localhost
metrics.reporter.stsd.port: 8125
metrics.reporter.stsd.interval: 60 SECONDS

Datadog

(org.apache.flink.metrics.datadog.DatadogHttpReporter)

유형: push/tags

참고: <host>, <job_name>, <tm_id>, <subtask_index>, <task_name>, <operator_name> 같은 Flink 메트릭의 모든 변수는 Datadog에 태그로 전송돼요. 태그는 host:localhost, job_name:myjobname처럼 보일 거예요.

참고: 하위 호환성(legacy) 이유로 reporter는 둘 다 메트릭 식별자 와 태그를 사용해요. 이 중복은 useLogicalIdentifier를 활성화해 피할 수 있어요.

참고: 히스토그램은 Datadog 히스토그램의 명명 규칙(<metric_name>.<aggregation>)을 따르는 일련의 gauge로 노출돼요. min 집계가 기본으로 보고되며, sum은 사용할 수 없어요. Datadog 제공 히스토그램과 달리 보고된 집계는 특정 reporting 간격에 대해 계산되지 않아요.

파라미터:

• apikey - Datadog API 키
• proxyHost - (선택) Datadog로 보낼 때 사용할 프록시 호스트.
• proxyPort - (선택) Datadog로 보낼 때 사용할 프록시 포트, 기본값 8080.
• dataCenter - (선택) 연결할 데이터 센터(EU/US), 기본값 US.
• maxMetricsPerRequest - (선택) 각 요청에 포함할 최대 메트릭 수, 기본값 2000.
• useLogicalIdentifier - (선택) reporter가 논리 메트릭 식별자를 사용하는지 여부, 기본값 false.

구성 예:

metrics.reporter.dghttp.factory.class: org.apache.flink.metrics.datadog.DatadogHttpReporterFactory
metrics.reporter.dghttp.apikey: ***
metrics.reporter.dghttp.proxyHost: my.web.proxy.com
metrics.reporter.dghttp.proxyPort: 8080
metrics.reporter.dghttp.dataCenter: US
metrics.reporter.dghttp.maxMetricsPerRequest: 2000
metrics.reporter.dghttp.interval: 60 SECONDS
metrics.reporter.dghttp.useLogicalIdentifier: true

OpenTelemetry

(org.apache.flink.metrics.otel.OpenTelemetryMetricReporterFactory)

파라미터:

키 (Key)	기본값 (Default)	타입 (Type)	설명 (Description)
batch.size	0	Integer	export 배치당 메트릭 수. 값이 0보다 작거나 같으면 배칭이 비활성화되고 모든 메트릭이 단일 요청으로 내보내져요.
export-completion-timeout-millis	300000	Long	비동기 export 완료를 기다리는 타임아웃(밀리초).
exporter.compression	"none"	String	OTel Reporter용 압축 방법. 'gzip' 또는 'none'만. 기본값은 'none'.
exporter.endpoint	(none)	String	OpenTelemetry Reporter용 엔드포인트.
exporter.protocol	gRPC	Enum	OpenTelemetry Reporter용 프로토콜. 가능한 값: "gRPC", "HTTP"
exporter.timeout	(none)	String	OpenTelemetry Reporter용 타임아웃, Duration 문자열. 예: 10초는 10s
service.name	(none)	String	OpenTelemetry Reporter에 전달되는 service.name
service.version	(none)	String	OpenTelemetry Reporter에 전달되는 service.version

구성 예:

metrics.reporter.otel.factory.class: org.apache.flink.metrics.otel.OpenTelemetryMetricReporterFactory
metrics.reporter.otel.exporter.endpoint: http://127.0.0.1:1337
metrics.reporter.otel.exporter.protocol: gRPC

metrics.reporter.otel.factory.class: org.apache.flink.metrics.otel.OpenTelemetryMetricReporterFactory
metrics.reporter.otel.exporter.endpoint: http://127.0.0.1:9090
metrics.reporter.otel.exporter.protocol: HTTP

# With batching enabled (500 metrics per export request)
metrics.reporter.otel.factory.class: org.apache.flink.metrics.otel.OpenTelemetryMetricReporterFactory
metrics.reporter.otel.exporter.endpoint: http://127.0.0.1:1337
metrics.reporter.otel.exporter.protocol: gRPC
metrics.reporter.otel.batch.size: 1500
metrics.reporter.otel.export-completion-timeout-millis: 60000

Slf4j

(org.apache.flink.metrics.slf4j.Slf4jReporter)

유형: push/identifier

구성 예:

metrics.reporter.slf4j.factory.class: org.apache.flink.metrics.slf4j.Slf4jReporterFactory
metrics.reporter.slf4j.interval: 60 SECONDS

더 알아보기 (Learn more)

• 메트릭 시스템 문서
• 플러그인
• Flink 설정 파일