OpenTelemetry 시맨틱 컨벤션 안정화 — 속성 이름이 바뀌면 대시보드가 깨진다

OpenTelemetry 시맨틱 컨벤션은 트레이스·메트릭·로그의 속성(attribute) 이름과 값을 표준으로 못 박은 규약이다. http.method를 쓸지 http.request.method를 쓸지 같은 사소해 보이는 결정을, 전 세계 계측 라이브러리와 백엔드가 똑같이 따르도록 만드는 사전이라고 보면 된다. 2023~2025년을 거치며 HTTP·데이터베이스·네트워크 같은 핵심 도메인의 컨벤션이 차례로 Stable로 승격됐고, 그 과정에서 속성 이름이 대거 바뀌었다.

문제는 여기서 시작된다. 이름이 바뀌면 그 이름에 의존하던 대시보드 쿼리, 알림 규칙, 샘플링 정책이 조용히 깨진다. 나도 라이브러리 하나 올렸다가 그래프 절반이 빈 채로 하루를 흘려보낸 적이 있다.

왜 이름이 바뀌었나

초기 컨벤션은 실무에서 급하게 정한 게 많았다. HTTP 서버 스팬에 http.method, http.status_code, http.url을 쓰다가, 정식 안정화 과정에서 네임스페이스를 정리했다. 지금 기준 정답은 http.request.method, http.response.status_code, url.full이다. 언뜻 사소하지만, 관측성 파이프라인 전체가 이 문자열을 키로 쓰기 때문에 파급이 크다.

마이그레이션을 부드럽게 — opt-in 스위치

OpenTelemetry는 이런 파괴적 변경을 한 번에 강요하지 않는다. 계측 라이브러리 상당수가 환경변수로 과도기 모드를 제공한다. 핵심은 OTEL_SEMCONV_STABILITY_OPT_IN이다.

# 구 속성만 유지 (기본, 아무 것도 안 하면 이 상태인 경우가 많음)
# OTEL_SEMCONV_STABILITY_OPT_IN 미설정
# 신·구 속성을 동시에 방출 → 대시보드 이관 기간에 안전
export OTEL_SEMCONV_STABILITY_OPT_IN=http/dup
# 신 속성만 방출 → 이관이 끝났을 때
export OTEL_SEMCONV_STABILITY_OPT_IN=http

내가 실제로 쓰는 순서는 이렇다. 먼저 http/dup으로 배포해서 신·구 속성이 둘 다 나오게 한다. 카디널리티가 잠깐 늘지만 며칠은 감당된다. 그동안 대시보드와 알림을 새 이름으로 바꾼다. 새 쿼리로 그래프가 제대로 그려지는 걸 확인한 뒤에야 http로 전환한다. 순서를 거꾸로 하면 반드시 빈 그래프를 본다.

흔히 데는 지점

• 메트릭 이름도 바뀐다. http.server.duration(ms, Histogram)이 http.server.request.duration(초, 단위까지 변경)으로 바뀌었다. 단위가 밀리초에서 초로 바뀐 걸 놓치면 p99 그래프가 1000배 틀어진다.
• 여러 언어를 섞어 쓰면 라이브러리별 안정화 속도가 다르다. Go 계측은 신 규약인데 Node 쪽은 아직 구 규약이면, 같은 서비스인데 스팬 속성이 제각각이 된다.
• Collector에서 이름을 강제 통일하는 것도 방법이다. 아래처럼 transform 프로세서로 구 속성을 신 속성으로 복사해 두면, 소스 코드를 못 건드리는 서드파티 스팬도 정규화된다.

processors:
  transform:
    trace_statements:
      - context: span
        statements:
          - set(attributes["http.request.method"], attributes["http.method"])
            where attributes["http.request.method"] == nil

지금 당장 확인할 것

솔직히 처음엔 "이름 좀 바뀐 게 뭐 대수냐" 싶었다. 그런데 관측성은 문자열 일치에 통째로 의존한다. 오탈자 하나, 네임스페이스 하나 어긋나면 데이터가 사라진 것처럼 보인다. 그러니 라이브러리를 올리기 전에 릴리스 노트에서 semconv 버전이 올라갔는지부터 본다. 올라갔다면 */dup 모드로 완충 구간을 두는 게 사고를 막는 가장 값싼 보험이다.

자주 묻는 질문

시맨틱 컨벤션이 Stable이면 이제 이름이 안 바뀌나요?

Stable로 승격된 도메인(HTTP 등)은 하위 호환을 깨는 변경을 하지 않겠다는 약속이 붙습니다. 다만 아직 Experimental 상태인 도메인(예: GenAI, 일부 messaging)은 계속 바뀔 수 있으니, 도메인별 안정화 상태를 따로 확인해야 합니다.

OTEL_SEMCONV_STABILITY_OPT_IN은 어디에 설정하나요?

계측이 실행되는 애플리케이션 프로세스의 환경변수로 넣습니다. Collector가 아니라 계측 SDK가 읽는 값이라, 각 서비스 컨테이너에 주입해야 효과가 있습니다. 지원 여부는 언어·라이브러리마다 다르니 문서를 확인하세요.

구 속성을 계속 써도 되나요?

당장은 동작합니다. 하지만 계측 라이브러리들이 점차 신 규약을 기본값으로 바꾸고 있어서, 언젠가는 업그레이드하는 순간 구 속성이 사라집니다. 미루면 미룰수록 한꺼번에 깨지므로, 완충 모드로 미리 옮겨 두는 편이 낫습니다.

대시보드가 이미 깨졌는데 빨리 복구하려면?

Collector의 transform 프로세서로 신 속성을 구 속성 이름에도 복사하면, 소스 수정 없이 기존 쿼리를 임시로 살릴 수 있습니다. 응급 처치로 쓰고, 대시보드 쿼리 자체를 신 규약으로 옮기는 게 정공법입니다.