Grafana로 지표 시각화
n8n v2.29n8n에서 Prometheus 지표 엔드포인트를 활성화한 다음, Prometheus 인스턴스를 통해 Grafana를 연결하여 n8n 데이터를 시각화하세요. /metrics 엔드포인트는 n8n Cloud에서는 사용할 수 없습니다.
n8n에서 Prometheus 지표 엔드포인트를 활성화한 다음, Prometheus 인스턴스를 통해 Grafana를 연결하여 n8n 데이터를 시각화하세요. 이 가이드를 따르기 전에 Prometheus 지표 활성화를 참고하세요.
기능 사용 가능 여부
/metrics 엔드포인트는 n8n Cloud에서는 사용할 수 없습니다.
재사용 가능한 대시보드 템플릿#
n8n 인스턴스에 대해 Prometheus 지표를 활성화하고 나면, 이를 관찰하기 위한 대시보드를 만들고 싶어질 것입니다.
n8n은 지원되는 여러 Prometheus 지표에 대해 재사용 가능한 Grafana 대시보드를 다음 GitHub 프로젝트에 공개하고 있습니다: n8n-observability
Prometheus가 n8n을 스크레이핑하도록 구성#
Prometheus는 일정에 따라 n8n의 /metrics 엔드포인트를 스크레이핑하여 데이터를 저장합니다. 그러면 Grafana가 Prometheus에 쿼리하여 이를 표시합니다.
prometheus.yml에 n8n 인스턴스를 대상으로 하는 스크레이프 작업을 추가하세요:
scrape_configs:
- job_name: n8n
static_configs:
- targets:
- <n8n-host>:<n8n-port>
metrics_path: /metrics
<n8n-host>와 <n8n-port>를 여러분의 n8n 인스턴스 주소로 바꾸세요. n8n의 기본 포트는 5678입니다.
편집을 마친 후 변경 사항을 적용하려면 Prometheus를 다시 로드하거나 재시작하세요.
Prometheus를 Grafana 데이터 소스로 추가#
- Grafana에서 Connections > Data sources로 이동합니다.
- Add new data source를 선택합니다.
- Prometheus를 선택합니다.
- Prometheus server URL을 여러분의 Prometheus 인스턴스 주소로 설정합니다. 예:
http://prometheus:9090 - Save & test를 선택합니다.
Grafana가 성공 메시지로 연결을 확인해줍니다.
웹훅 관찰성#
n8n 버전 2.28.0부터 사용할 수 있습니다.
n8n은 모든 웹훅 호출에 대해 n8n_webhook_request_duration_seconds 히스토그램을 노출합니다. 이를 수집하려면 다음 환경 변수를 활성화하세요:
| 변수 | 기본값 | 설명 |
|---|---|---|
N8N_METRICS_INCLUDE_WEBHOOK_METRICS |
false |
n8n_webhook_request_duration_seconds 히스토그램을 노출합니다. |
N8N_METRICS_INCLUDE_WORKFLOW_INFO |
false |
사람이 읽을 수 있는 워크플로 이름을 위한 n8n_workflow_info 게이지를 노출합니다. 워크플로 이름 조회를 참고하세요. |
이 히스토그램에 대해 바로 사용 가능한 대시보드를 n8n-observability 프로젝트에서 찾을 수 있습니다.
이 지표가 추적하는 항목#
n8n_webhook_request_duration_seconds는 Prometheus 히스토그램입니다. n8n은 각 웹훅 호출마다 요청이 걸린 시간("요청 수신" -> "응답 전송")을 기록합니다. 이 지표는 레이블 조합마다 세 가지 시리즈를 노출합니다:
| 시리즈 | 설명 |
|---|---|
_bucket{le="<bound>"} |
<bound>초 이내에 완료된 요청의 누적 개수입니다. |
_sum |
모든 요청에 걸린 총 초입니다. |
_count |
총 요청 수입니다. |
각 시리즈는 다음 레이블을 가집니다:
| 레이블 | 예시 | 설명 |
|---|---|---|
method |
GET |
수신 요청의 HTTP 메서드입니다. |
status_code |
200 |
n8n이 반환한 HTTP 상태 코드입니다. |
webhook_path |
294febd8-… |
웹훅 엔드포인트를 식별하는 UUID 경로입니다. |
workflow_id |
KhcGg7EmAMoa7Bmv |
웹훅이 속한 워크플로의 ID입니다. |
대시보드 아이디어#
| 패널 | PromQL |
|---|---|
| 워크플로별 요청 비율 | sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count[5m])) |
| 모든 웹훅의 p95 지연 시간 | histogram_quantile(0.95, sum by (le) (rate(n8n_webhook_request_duration_seconds_bucket[5m]))) |
| 워크플로별 p95 지연 시간 | histogram_quantile(0.95, sum by (le, workflow_id) (rate(n8n_webhook_request_duration_seconds_bucket[5m]))) |
| 오류율 (비 2xx) | sum by (workflow_id) (rate(n8n_webhook_request_duration_seconds_count{status_code!="2.."}[5m])) |
| 평균 요청 처리 시간 | rate(n8n_webhook_request_duration_seconds_sum[5m]) / rate(n8n_webhook_request_duration_seconds_count[5m]) |
폼 제출 관찰성#
n8n 버전 2.28.0부터 사용할 수 있습니다.
n8n은 모든 폼 제출에 대해 n8n_form_submission_duration_seconds 히스토그램을 노출합니다. 이를 수집하려면 다음 환경 변수를 활성화하세요:
| 변수 | 기본값 | 설명 |
|---|---|---|
N8N_METRICS_INCLUDE_FORM_METRICS |
false |
n8n_form_submission_duration_seconds 히스토그램을 노출합니다. |
N8N_METRICS_INCLUDE_WORKFLOW_INFO |
false |
사람이 읽을 수 있는 워크플로 이름을 위한 n8n_workflow_info 게이지를 노출합니다. 워크플로 이름 조회를 참고하세요. |
이 히스토그램에 대해 바로 사용 가능한 대시보드를 n8n-observability 프로젝트에서 찾을 수 있습니다.
이 지표가 추적하는 항목#
n8n_form_submission_duration_seconds는 Prometheus 히스토그램입니다. n8n은 각 폼 제출마다 "사용자가 제출을 누른 시점"부터 "사용자가 폼 제출에 대한 피드백을 받는 시점"까지 걸린 시간을 기록합니다. 이 지표는 레이블 조합마다 세 가지 시리즈를 노출합니다:
| 시리즈 | 설명 |
|---|---|
_bucket{le="<bound>"} |
<bound>초 이내에 완료된 제출의 누적 개수입니다. |
_sum |
모든 제출을 처리하는 데 걸린 총 초입니다. |
_count |
총 제출 수입니다. |
각 시리즈는 다음 레이블을 가집니다:
| 레이블 | 예시 | 설명 |
|---|---|---|
status_code |
200 |
n8n이 반환한 HTTP 상태 코드입니다. |
form_path |
b395d2e2-… |
폼 엔드포인트를 식별하는 UUID 경로입니다. |
workflow_id |
qTzTyGlEROwSuVlY |
폼이 속한 워크플로의 ID입니다. |
method 레이블 없음
n8n은 POST를 통해서만 폼 데이터를 수신하므로, 폼 제출에는 method 레이블이 포함되지 않습니다.
대시보드 아이디어#
| 패널 | PromQL |
|---|---|
| 워크플로별 제출 비율 | sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count[5m])) |
| 모든 폼의 p95 처리 시간 | histogram_quantile(0.95, sum by (le) (rate(n8n_form_submission_duration_seconds_bucket[5m]))) |
| 워크플로별 p95 처리 시간 | histogram_quantile(0.95, sum by (le, workflow_id) (rate(n8n_form_submission_duration_seconds_bucket[5m]))) |
| 오류율 (비 2xx) | sum by (workflow_id) (rate(n8n_form_submission_duration_seconds_count{status_code!="2.."}[5m])) |
| 평균 처리 시간 | rate(n8n_form_submission_duration_seconds_sum[5m]) / rate(n8n_form_submission_duration_seconds_count[5m]) |
워크플로 이름 조회#
n8n 버전 2.28.0부터 사용할 수 있습니다.
N8N_METRICS_INCLUDE_WORKFLOW_INFO를 활성화하면, n8n은 워크플로마다 게이지를 하나씩 노출합니다:
n8n_workflow_info{workflow_id="VaQPuPmx9tPpo6BX",workflow_name="My workflow"} 1
이를 workflow_id를 통해 다른 n8n 지표와 조인하면, Grafana 패널에서 불투명한 ID 대신 사람이 읽을 수 있는 이름을 사용할 수 있습니다. 예를 들어 워크플로 이름별 웹훅 요청 비율을 표시하려면 다음과 같이 작성하세요:
sum by (workflow_name) (
rate(n8n_webhook_request_duration_seconds_count[5m])
* on(workflow_id) group_left(workflow_name)
n8n_workflow_info
)