콘텐츠로 이동

Studio 자체 관측 구성 및 지표 설명

본 문서는 배포 플랜 Studio 측에서 자체 관측 구성이 활성화되었는지 확인하는 방법과 자체 관측 지표 집합 df_studio에서 API, Celery 비동기 작업, Redis/Broker, 비즈니스 작업 및 내보내기 링크와 관련된 지표, 태그, 단위 및 모니터링 제안을 설명합니다.

적용 버전

  • 자체 관측 능동 지표 기능은 2026년 5월 20일 릴리스 버전부터 제공됩니다.
  • 2026년 5월 13일 릴리스 버전은 이 능동 지표 기능을 아직 지원하지 않습니다.
  • Lark(飞书) 문의 티켓에서 최신 배포 플랜 v1.130.225가 이 기능을 지원하는 것으로 확인되었습니다. 해당 버전은 Studio 현재 시스템 커밋 60a71d992에 해당하며, 본 문서의 지표 및 구성은 해당 커밋을 기준으로 확인되었습니다.
  • 환경이 v1.130.225보다 낮은 경우, 먼저 업그레이드한 후 구성하는 것을 권장합니다.

수집 링크

Studio 애플리케이션 측은 외부 서비스로 지표를 능동적으로 푸시하지 않습니다. 권장 링크는 다음과 같습니다.

Studio API / Celery / WebSocket / Snapshot
  -> 애플리케이션 내 경량 지표 기록
  -> Redis 지표 캐시
  -> inner /metrics Prometheus 텍스트 익스포터
  -> Datakit 정기 풀링
  -> 자체 관측 워크스페이스
  -> 대시보드 / 모니터 / 알림

Datakit 풀링 주소:

http://<inner-service-ip>:5000/api/v1/inner/metrics?from=datakit&type=df_studio

Prometheus 텍스트 익스포터는 전체 지표 이름을 출력합니다(예: df_studio_celery_task_published_total). Guance UI 또는 DQL에서는 일반적으로 "지표 집합 + 필드"로 조회합니다. 즉, 지표 집합은 df_studio이고 필드는 celery_task_published_total입니다.

자체 관측 구성 활성화 확인 방법

1. Studio 백엔드 구성 확인

Studio 백엔드 구성 항목은 SelfMonitorMetricsSet입니다. 기본적으로 비활성화되어 있으며, 사용자는 enable을 명시적으로 활성화하기만 하면 됩니다.

SelfMonitorMetricsSet:
  enable: true

다른 구성은 기본값을 유지하면 됩니다. 의미는 다음과 같습니다.

구성 항목 기본값 단위 설명
enable false 불리언 자체 관측 통합 스위치입니다. true인 경우에만 API, Celery, 비즈니스 작업 및 /metrics 내보내기 관련 지표가 기록됩니다.
expireSeconds 3600 주기 증분 지표의 Redis 보존 기간입니다.
stateExpireSeconds 604800 beat 최근 게시 시간, 비즈니스 작업 최근 성공/실패 등 상태 유형 지표의 보존 기간입니다.
beatMissedLagThresholdSeconds 300 beat 게시 후 실행이 시작되지 않은 것으로 판단하는 기본 지연 임계값입니다.
beatMissedIntervalMultiplier 2 배수 저주파 beat의 스케줄링 누락 여부 판단 시 사용하는 최근 게시 간격 배수입니다.
celeryQueues celery, correlation_task, snapshot_queue, compute_task 목록 큐 길이 및 가장 오래된 대기 시간을 읽어야 하는 Celery 큐입니다.

환경 변수를 통해 재정의할 수도 있습니다.

STUDIO__SelfMonitorMetricsSet__enable=true

참고: enable은 불리언 의미의 true 또는 false여야 합니다. 잘못된 문자열이나 null은 구성 로드 실패를 초래합니다.

2. /metrics에서 자체 관측 지표 출력 확인

클러스터 내에서 inner 서비스에 접근합니다.

curl 'http://management-backend.forethought-core:5000/api/v1/inner/metrics?from=datakit&type=df_studio'

활성화되어 있고 정상적으로 내보내지면 응답에 다음과 유사한 내용이 표시됩니다.

df_studio_self_monitor_export_total{exporter="prometheus_inner",result="success"} 1
df_studio_self_monitor_export_duration_seconds{exporter="prometheus_inner",result="success"} ...
df_studio_self_monitor_export_last_success_timestamp_seconds{exporter="prometheus_inner"} ...

내보내기 중 예외가 발생하면 인터페이스는 fail-open 방식으로 작동하여 가능한 한 실패 지표를 반환합니다.

df_studio_self_monitor_export_total{exporter="prometheus_inner",result="failure"} 1
df_studio_self_monitor_export_error_total{exception_type="...",exporter="prometheus_inner"} 1
df_studio_self_monitor_export_last_failure_timestamp_seconds{exception_type="...",exporter="prometheus_inner"} ...

3. 기존 상태 확인 인터페이스 확인

관리 백엔드는 여전히 Celery worker 상태 확인 인터페이스를 유지하고 있습니다.

curl 'http://management-backend.forethought-core:5000/api/v1/const/celery/ping'

이 인터페이스는 Redis의 celery_active_point를 읽어 각 큐의 최근 활성화 시간을 반환합니다. 200을 반환하면 구성된 유효 오프셋 시간 내에 활성화 지점이 있음을 의미합니다. 400을 반환하면 일반적으로 해당 worker가 오랫동안 활성화 지점을 업데이트하지 않았음을 의미하며, worker가 실행되지 않음, 작업 누적, Redis/Broker 연결 이상 등의 상황이 있을 수 있습니다.

이 인터페이스는 호환성 상태 확인에 적합합니다. 완전한 자체 관측은 아래의 df_studio 지표를 우선 사용하는 것을 권장합니다.

지표 및 태그 규칙

글로벌 태그

태그 적용 범위 의미 일반적인 값 사용 제안
service API 서비스 진입점 이름 front, inner, openapi, admin, external, center, aiapi, sse 낮은 카디널리티, 개요에 사용 가능.
run_app_code API 현재 프로세스 실행 진입점 service와 동일 낮은 카디널리티, 진입점 구분에 사용 가능.
route_rule API Flask route 규칙 /api/v1/... 원래 URL보다 집계에 더 적합.
method API HTTP 메서드 GET, POST, PUT 낮은 카디널리티.
status_class API HTTP 상태 코드 계열 2xx, 4xx, 5xx 성공률, 오류율에 사용.
queue Celery Celery 큐 이름 celery, correlation_task, snapshot_queue, compute_task 낮은 카디널리티, 비동기 작업 개요의 핵심 차원.
task Celery / 비즈니스 작업 Celery 작업 이름 또는 비즈니스 작업 이름 forethought.tasks..., statistics_upload 중간 카디널리티, 작업 수준 문제 해결에 사용.
status Celery 작업 종료 상태 success, failure, retry 작업 품질 분석에 사용.
exception_type Celery / 내보내기 링크 예외 유형 TimeoutError, OperationalError 예외 TopN에 사용.
beat_name Celery beat beat 항목 이름 구성의 beat 항목 이름 정기 작업 스케줄링 누락 여부 판단에 사용.
domain 비즈니스 작업 비즈니스 도메인 archive_report, incidents, billing, cleanup 낮은 카디널리티, 비즈니스 작업 개요의 주요 차원.
result 비즈니스 작업 / 내보내기 링크 실행 결과 success, error, failure, partial_success, skipped 성공률 및 실패율에 사용.
item_type 비즈니스 작업 처리 대상 유형 workspace, report_task, notification 낮은 카디널리티.
reason 비즈니스 작업 부분 실패 원인 notify_failed, item_error 열거 제어 후 알림에 사용 가능.
entry 독립 진입점 Flask 외 진입점 websocket, snapshot 독립 진입점 상태에 사용.
event 독립 진입점 진입점 이벤트 connect, disconnect, send_task 진입점 이벤트 분석에 사용.
state 현재 상태 지표 상태 이름 size, checked_out, overflow 구체적인 의미는 지표에 따라 다름.
exporter /metrics 내보내기 익스포터 이름 prometheus_inner 낮은 카디널리티.
le Histogram 버킷 버킷 상한 0.1, 1, 5, +Inf _bucket 지표에서 분위수 계산에만 사용.

le는 히스토그램 버킷의 작거나 같음 상한을 나타내며, 비즈니스 차원이 아닙니다. 예를 들어 le="1"은 1초 이하의 샘플 누적 수를 의미하고, le="+Inf"는 모든 샘플 수를 의미합니다.

API 지표

지표 필드 단위 태그 의미
api_request_count service, api_path 이전 API 비 5xx 요청량과의 호환.
api_request_error_count service, api_path 이전 API 5xx 요청량과의 호환.
api_requests_total service, run_app_code, route_rule, method, status_class API 총 요청량, 주기 증분.
api_errors_total service, run_app_code, route_rule, method, status_class, error_type API 오류량, 현재 주로 HTTP 5xx를 포함.
api_duration_seconds_bucket service, run_app_code, route_rule, method, status_class, le API 요청 지연 시간 분포.
api_duration_seconds_sum service, run_app_code, route_rule, method, status_class API 요청 지연 시간 합계.
api_duration_seconds_count service, run_app_code, route_rule, method, status_class API 요청 지연 시간 샘플 수.

Celery 큐 및 작업 지표

다음 지표는 커밋 60a71d992에서 Celery 시그널을 통해 기록되며, df_studio 지표 집합으로 내보내집니다. worker_queue_countcelery_queue_oldest_wait_seconds는 Redis 브로커 큐를 직접 읽어 Redis/Broker 큐 적체 또는 worker 미소비를 발견하는 데 사용됩니다. Celery 작업 수명 주기 지표는 "소비 시작 안 함"과 "시작 후 멈춤"을 추가로 구분하는 데 사용됩니다.

지표 필드 단위 태그 의미
worker_queue_count queue Redis 브로커 큐의 현재 길이.
celery_queue_oldest_wait_seconds queue 큐에서 가장 오래된 작업의 게시 후 현재까지 대기 시간.
celery_task_published_total task, queue Celery 작업 게시 횟수.
celery_task_started_total task, queue Celery 작업 실행 시작 횟수.
celery_task_finished_total task, queue, status Celery 작업 종료 횟수, 상태별 구분.
celery_task_active task, queue 현재 실행 중인 Celery 작업 수.
celery_task_duration_seconds_bucket task, queue, le 작업 실행 지연 시간 분포.
celery_task_duration_seconds_sum task, queue 작업 실행 지연 시간 합계.
celery_task_duration_seconds_count task, queue 작업 실행 지연 시간 샘플 수.
celery_task_queue_wait_seconds_bucket task, queue, le 작업 게시 후 실행 시작까지의 큐 대기 지연 시간 분포.
celery_task_queue_wait_seconds_sum task, queue 작업 큐 대기 지연 시간 합계.
celery_task_queue_wait_seconds_count task, queue 작업 큐 대기 지연 시간 샘플 수.
celery_task_failure_exception_total task, queue, exception_type 작업 실패 예외 유형 분포.
celery_task_timeout_total task, queue, timeout_type Celery soft/hard timeout 횟수.
celery_task_retry_total task, queue, exception_type 작업 재시도 횟수.
celery_task_retry_delay_seconds_bucket task, queue, le 작업 재시도 지연 분포.
celery_task_retry_delay_seconds_sum task, queue 작업 재시도 지연 합계.
celery_task_retry_delay_seconds_count task, queue 작업 재시도 지연 샘플 수.

Beat 및 정기 작업 지표

지표 필드 단위 태그 의미
celery_beat_task_last_publish_timestamp_seconds Unix 초 beat_name, task beat 항목의 최근 작업 게시 시간.
celery_beat_task_last_started_timestamp_seconds Unix 초 beat_name, task beat 항목에 해당하는 작업의 최근 실행 시작 시간.
celery_beat_lag_seconds beat_name, task beat 작업 게시 후 worker 실행 시작까지의 지연.
celery_beat_publish_interval_seconds beat_name, task beat 항목의 최근 두 번 게시 사이의 실제 간격.
celery_beat_missed 불리언 beat_name, task 스케줄링 누락 의심 여부, 1은 누락 의심을 의미.

비즈니스 작업 지표

지표 필드 단위 태그 의미
business_task_runs_total domain, task, result 비즈니스 작업 실행 횟수.
business_task_items_total domain, task, item_type, result 비즈니스 작업 처리 대상 수.
business_task_duration_seconds_bucket domain, task, result, le 비즈니스 작업 종단 간 지연 시간 분포.
business_task_duration_seconds_sum domain, task, result 비즈니스 작업 종단 간 지연 시간 합계.
business_task_duration_seconds_count domain, task, result 비즈니스 작업 종단 간 지연 시간 샘플 수.
business_task_last_success_timestamp_seconds Unix 초 domain, task 비즈니스 작업 최근 성공 시간.
business_task_last_failure_timestamp_seconds Unix 초 domain, task, exception_type 비즈니스 작업 최근 실패 시간.
business_task_partial_failure_total domain, task, reason 작업이 전체적으로 실패하지는 않았지만 부분 실패가 존재하는 횟수.

현재 접속된 비즈니스 도메인은 다음과 같습니다.

domain 일반적인 작업 관심 사항
archive_report 아카이브 보고서 v2/v3, 첫 주기 알림, 지연 알림 보고서 트리거, 스크린샷, 알림 성공 여부, 부분 실패 존재 여부.
incidents 인시던트 온콜 정책 분석, 인시던트 큐 동기화, 인시던트 알림 전송 인시던트 알림 링크 성공 여부, 적체 여부.
billing 청구 통계 보고 정시 여부, 성공 여부, 처리 워크스페이스 수.
workspace_usage OpenAPI API Key 사용량 DB 업데이트 사용량 업데이트 성공 여부, 처리 버킷 및 액세스 키 수.
cleanup 대시보드 기록 정리 등 정리 작업 장기 실패 또는 건너뛰기 여부.
sync_config 통합 템플릿 동기화 구성 동기화 성공 여부.
notification Status Page 상태 변경 알림 알림 작업 성공 또는 실패 여부.
keyevent 주요 이벤트 미복구 비동기 조회 주요 이벤트 비동기 조회 이상 여부.
cloud_collector 클라우드 수집기 비동기 작업 비동기 작업 분할, 잠금 대기, 성공/실패.
catalog 통합 카탈로그 엔터티 상태 엔터티 상태 작업 정시 여부, 성공 여부 및 처리량 이상 여부.
snapshot 대시보드 스크린샷, 차트 스크린샷, 차트 데이터 생성 스냅샷 서비스 스크린샷/차트 데이터 작업 결과.

독립 진입점 및 종속성 상태 지표

지표 필드 단위 태그 의미
service_entry_events_total entry, event, result WebSocket, snapshot 등 Flask 외 진입점 이벤트 횟수.
service_entry_active 개/불리언 entry, state Flask 외 진입점 현재 활성 상태.
dependency_db_pool_connections pool, state 익스포터가 위치한 프로세스의 데이터베이스 연결 풀 현재 상태. statesize, checked_in, checked_out, overflow를 포함.
self_monitor_export_total exporter, result /metrics 이번 내보내기 결과.
self_monitor_export_points_total exporter, result /metrics 이번 성공적으로 내보낸 Prometheus 샘플 수.
self_monitor_export_duration_seconds exporter, result /metrics 이번 내보내기 지연 시간.
self_monitor_export_last_success_timestamp_seconds Unix 초 exporter 최근 성공적인 내보내기 시간.
self_monitor_export_last_failure_timestamp_seconds Unix 초 exporter, exception_type 최근 fail-open 실패 내보내기 시간.
self_monitor_export_error_total exporter, exception_type 이번 fail-open 실패 이벤트.

비동기 작업 및 Redis/Broker 모니터링 제안

고객이 우려하는 "비동기 작업 이상 여부, Redis 연결 끊김 여부, worker 중단 여부"는 단일 지표만으로 판단할 수 없으며, 조합 조건을 기준으로 판단하는 것이 좋습니다.

시나리오 우선 관찰 지표 권장 차원 판단 방법
worker 미소비 또는 소비 능력 부족 worker_queue_count, celery_queue_oldest_wait_seconds, celery_task_published_total, celery_task_started_total queue, task 큐 길이와 가장 오래된 대기 시간이 지속적으로 증가하고, published는 증가하지만 started는 매우 낮으면 일반적으로 worker가 소비하지 않거나, 소비가 부족하거나, 브로커 연결에 이상이 있음을 의미.
Redis/Broker는 읽을 수 있지만 worker 연결 끊김 worker_queue_count, celery_queue_oldest_wait_seconds, celery_task_active queue 익스포터가 큐를 읽을 수 있고, 큐 적체는 증가하지만 active가 장기간 0이거나 현저히 낮으면 worker 측 연결 끊김, 중단 또는 미시작을 우선 의심.
Redis/Broker 완전히 사용 불가 또는 익스포터 읽기 실패 self_monitor_export_total, self_monitor_export_error_total, self_monitor_export_last_failure_timestamp_seconds, self_monitor_export_points_total exporter, exception_type /metrics가 fail-open되고, 실패 시간이 갱신되며, 샘플 수가 현저히 감소하면 수집 링크 자체가 Redis, DB 또는 지표 소스에 접근하지 못할 수 있음을 의미.
작업 시작 후 멈춤 및 종료 안 됨 celery_task_active, celery_task_started_total, celery_task_finished_total, celery_task_duration_seconds_bucket queue, task active가 장기간 감소하지 않고, started는 증가하지만 finished는 증가하지 않거나, 지연 시간 P99가 지속적으로 상승하면 작업이 외부 호출, 잠금, DB 또는 루프 로직에서 멈출 수 있음을 의미.
작업 실패 또는 재시도 폭풍 celery_task_finished_total, celery_task_failure_exception_total, celery_task_retry_total, celery_task_retry_delay_seconds_bucket task, exception_type failure/retry가 동시에 증가하고 예외 유형이 집중되면 작업이 실패-재시도 루프에 진입할 수 있음을 의미.
beat가 정상적으로 게시하지만 worker가 시작하지 않음 celery_beat_task_last_publish_timestamp_seconds, celery_beat_task_last_started_timestamp_seconds, celery_beat_lag_seconds, celery_beat_missed beat_name, task last_publish는 갱신되지만 last_started는 갱신되지 않고, lag가 증가하거나 missed=1이면 정기 작업이 전달되었지만 worker가 소비를 시작하지 않았음을 의미.
beat 게시 중단 또는 저주파 작업 스케줄링 누락 celery_beat_publish_interval_seconds, celery_beat_task_last_publish_timestamp_seconds, celery_beat_missed beat_name, task publish interval이 과거 주기를 초과하거나 last_publish가 너무 오래되었으면 beat가 중단되었거나, 구성이 활성화되지 않았거나, 스케줄러에 이상이 있음을 의미.
비즈니스 작업 전체 성공 but 일부 객체 실패 business_task_partial_failure_total, business_task_items_total, business_task_runs_total domain, task, reason, item_type partial failure가 증가하지만 전체 작업은 여전히 partial_success일 수 있으므로, 구체적인 비즈니스 객체 실패 원인을 확인해야 함.
비즈니스 작업 장기간 성공 없음 business_task_last_success_timestamp_seconds, business_task_last_failure_timestamp_seconds, business_task_runs_total domain, task last_success가 현재 시간으로부터 너무 오래되었고, last_failure가 갱신되거나 runs에 success가 없으면 해당 비즈니스 링크가 자동으로 실패하고 있을 수 있음을 의미.

최소한 다음 알림을 설정하는 것을 권장합니다.

알림 항목 권장 레벨 권장 조건
자체 모니터링 내보내기 실패 P0 self_monitor_export_total{result="failure"} 또는 self_monitor_export_error_total 발생.
자체 모니터링 장기간 성공 없음 P0 현재 시간에서 self_monitor_export_last_success_timestamp_seconds를 뺀 값이 2~3회 Datakit 풀링 주기 초과.
Celery 큐 적체 P0 worker_queue_count가 임계값을 지속적으로 초과하거나, celery_queue_oldest_wait_seconds가 비즈니스 허용 대기 시간을 지속적으로 초과.
worker 미소비 의심 P0 celery_task_published_total은 증가하지만 celery_task_started_total이 장기간 증가하지 않고, 동시에 큐 길이 또는 가장 오래된 대기 시간이 증가.
worker 중단 의심 P0 celery_task_active가 장기간 0보다 크고 감소하지 않으며, celery_task_finished_total이 증가하지 않고, 작업 지연 시간 P99가 지속적으로 상승.
beat 스케줄링 누락 P0 celery_beat_missed=1 또는 celery_beat_lag_seconds가 작업 허용 임계값 초과.
Celery 작업 실패율 증가 P1 celery_task_finished_total{status!="success"} 비율이 연속 여러 주기 동안 임계값 초과.
Celery 재시도 폭풍 P1 celery_task_retry_total이 연속적으로 증가하고 동일한 task 또는 exception_type에 집중.
비즈니스 작업 장기간 성공 없음 P0/P1 주요 작업이 business_task_last_success_timestamp_seconds를 장기간 업데이트하지 않음.
DB 풀 고갈 임박 P1 dependency_db_pool_connections{state="checked_out"}state="size"에 근접하거나 state="overflow" > 0이 지속적으로 발생.

자주 사용하는 DQL 예시

각 큐의 현재 적체 확인:

M::`df_studio`:(max(`worker_queue_count`)) BY `queue`

각 큐의 가장 오래된 작업 대기 시간 확인:

M::`df_studio`:(max(`celery_queue_oldest_wait_seconds`)) BY `queue`

작업 게시 및 실행 시작 차이 확인:

M::`df_studio`:(sum(`celery_task_published_total`), sum(`celery_task_started_total`)) BY `queue`,`task`

작업 실패 예외 TopN 확인:

M::`df_studio`:(sum(`celery_task_failure_exception_total`)) BY `task`,`exception_type`

beat 스케줄링 누락 확인:

M::`df_studio`:(max(`celery_beat_missed`), max(`celery_beat_lag_seconds`)) BY `beat_name`,`task`

자체 모니터링 내보내기 상태 확인:

M::`df_studio`:(max(`self_monitor_export_total`), max(`self_monitor_export_points_total`), max(`self_monitor_export_duration_seconds`)) BY `exporter`,`result`

비즈니스 작업 최근 성공 시간 확인:

M::`df_studio`:(max(`business_task_last_success_timestamp_seconds`)) BY `domain`,`task`

기존 자체 관측 문서와의 관계

배포 플랜의 전체 자체 관측 배포 절차는 동일 디렉토리의 《배포 플랜 자체 관측 활성화》를 참조하십시오. 해당 문서는 DataKit 배포, Prometheus 풀링 구성, 애플리케이션 성능 모니터링(APM), 실제 사용자 모니터링(RUM), 신서틱 테스트, 모니터 및 템플릿 가져오기 등 일반적인 단계를 다룹니다. 본 문서는 Studio 백엔드 자체에서 출력하는 df_studio 지표, 구성 스위치, 태그 단위 및 비동기 작업/Redis/Broker 모니터링 기준만을 추가로 설명합니다.

문서 평가

이 페이지가 도움이 되었나요?