이스케이프 스킴

이스케이프 스킴 (Escaping schemes)

이 문서는 Prometheus 텍스트 익스포지션 형식에서 메트릭 이름·라벨 값·주석 같은 문자열 안의 특수 문자를 이스케이프(escape)하는 규칙을 설명해요. 특히 \n, \", \\ 같은 제어 문자의 표현 방식과, 형식 버전별 이스케이프 스킴 선택을 다룹니다.

메트릭 라벨 값은 자유로운 UTF-8 문자열이 될 수 있어요. 텍스트 형식으로 직렬화할 때는 이스케이프 규칙을 지켜야 반올림(round-trip) 파싱이 정확해집니다.

출처: 문서

본문

배경

Prometheus 텍스트 형식에서는 라벨 값 등이 개행(\n)이나 큰따옴표(") 같은 문자를 포함할 수 있습니다. 이 문자들을 그대로 출력하면 형식이 깨지므로 이스케이프 규칙이 필요합니다.

기본 이스케이프

Prometheus 텍스트 형식(기존 형식)에서는 다음과 같이 이스케이프합니다:

  • 개행은 \n
  • 큰따옴표는 \"
  • 백슬래시는 \\

라벨 값은 큰따옴표로 감싸며, 값 안의 이 문자들을 위와 같이 이스케이프합니다.

OpenMetrics 형식의 이스케이프

OpenMetrics 텍스트 형식도 유사하지만, 형식에 따라 이스케이프 규칙의 적용 방식이 다를 수 있습니다. 클라이언트 라이브러리는 자동으로 올바른 이스케이프를 적용합니다.

이스케이프 스킴 선택

문서에서는 메트릭 이름별로 이스케이프 스킴을 정확히 선택해 직렬화·역직렬화(round-trip) 시 값을 보존하는 방법을 다룹니다. 즉:

  • 값을 쓸 때는 형식이 허용하는 이스케이프를 사용하고,
  • 읽을 때는 그 이스케이프를 정확히 해석해 원래 값을 복원해야 합니다.

주의할 점

  • 라벨 값에 개행이나 따옴표가 들어가면 많은 도구(대시보드, 프린터)가 제대로 표시하지 못할 수 있으므로, 가능하면 제어 문자 없이 사용하는 것을 권장합니다.
  • Prometheus 서버는 스크레이프 시 이 이스케이프 규칙대로 값을 해석합니다.

더 알아보기 (Learn more)