OpenTelemetry 메트릭 속성, 이름 짓기에도 규칙이 있다? 🧐 네임스페이스 완전 정복!

안녕하세요! 여러분의 시스템을 더욱 투명하게 만들어주는 Observability의 세계에 오신 것을 환영합니다. 🚀 OpenTelemetry를 사용해 메트릭, 로그, 트레이스 같은 데이터를 수집하는 것은 시스템 상태를 파악하는 첫걸음입니다. 하지만 데이터를 단순히 모으기만 하면 될까요?

 

수집된 데이터가 일관성 없고 의미가 불분명하다면, 정작 문제가 발생했을 때 아무런 도움이 되지 못할 수 있습니다. 오늘은 그중에서도 메트릭(Metric)의 속성(Attribute) 이름을 어떻게 지어야 하는지, 그리고 왜 그것이 중요한지에 대해 깊이 파고들어 보겠습니다.

 

🤔 문제의 시작: "이름이 같아서 헷갈려요!"

전체적인 맥락부터 살펴봅시다. 우리가 다양한 컴포넌트로부터 메트릭을 수집한다고 상상해 보세요. 예를 들어, 아래와 같은 두 가지 메트릭이 있습니다.

1. http.server.duration: HTTP 서버 요청 처리 시간
2. db.client.duration: DB 클라이언트 쿼리 실행 시간

두 메트릭 모두 처리 결과를 나타내는 status라는 속성을 가질 수 있겠죠?

• HTTP 서버의 status: 200, 404, 500 등 (HTTP 상태 코드)
• DB 클라이언트의 status: OK, TIMEOUT, ERROR 등 (DB 처리 결과)

만약 우리가 대시보드에서 "모든 요청 중 status가 ERROR인 것들을 찾아줘"라고 필터링하면 어떻게 될까요? 🤯 아마 HTTP 서버의 500 에러와 DB 클라이언트의 ERROR 상태가 뒤섞여서 원인 파악이 더 어려워질 겁니다.

 

이처럼 서로 다른 의미를 가진 속성이 같은 이름을 사용하면서 발생하는 충돌을 '이름 충돌(Name Collision)'이라고 부릅니다. 이런 문제를 방지하고 데이터의 의미를 명확하게 하기 위해 OpenTelemetry는 가이드라인을 제시합니다.

 

✨ 해답은 바로 '네임스페이스'에 있습니다!

OpenTelemetry 가이드라인의 핵심은 간단합니다.

특정 메트릭에만 고유하게 사용되는 속성이라면, 해당 메트릭의 네임스페이스를 사용해 이름을 지정하라.

 

즉, 속성 이름 앞에 그것이 어떤 종류의 속성인지를 명확히 밝혀주는 접두사(prefix)를 붙이는 것입니다. 형식은 보통 domain.name.attribute_name 과 같습니다.

 

위의 예시를 올바른 네임스페이스 방식으로 바꿔볼까요?

• http.server.duration 메트릭의 경우:
  • (나쁜 예 👎) status: 200
  • (좋은 예 👍) http.status_code: 200
• db.client.duration 메트릭의 경우:
  • (나쁜 예 👎) status: "OK"
  • (좋은 예 👍) db.operation.result: "OK" (Semantic Convention에 따른 예시)

이렇게 네임스페이스를 사용하면 http.status_code와 db.operation.result는 완전히 다른 속성으로 취급됩니다. 이제 우리는 "HTTP 요청 중 상태 코드가 500번대인 것" 또는 "DB 작업 결과가 TIMEOUT인 것"처럼 훨씬 명확하고 정확한 분석을 할 수 있게 됩니다.

 

코드로 직접 확인해보기

이해를 돕기 위해 Python OpenTelemetry SDK를 사용한 간단한 예제 코드를 살펴보겠습니다.

# 필요한 라이브러리 import
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader

# 메트릭을 수집하고 내보낼 준비
reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
provider = MeterProvider(metric_readers=[reader])
metrics.set_meter_provider(provider)
meter = metrics.get_meter("my-web-server")

# http.server.duration 메트릭 생성
http_duration_histogram = meter.create_histogram(
    name="http.server.duration",
    unit="ms",
    description="Measures the duration of inbound HTTP requests."
)

# ✅ 올바른 방법: 네임스페이스를 사용한 속성 정의
good_attributes = {
    "http.method": "GET",
    "http.status_code": 200,
    "net.peer.ip": "192.168.1.1" # net.*은 일반적인 네트워크 속성이므로 그대로 사용
}
http_duration_histogram.record(150, attributes=good_attributes)
print("✅ [GOOD] Metric with namespaced attributes recorded.")

# ❌ 잘못된 방법: 일반적인 이름의 속성 정의
bad_attributes = {
    "method": "POST", # 'method'는 다른 곳에서도 쓰일 수 있어 모호함
    "status": 500,    # 'status'가 숫자인지 문자열인지, HTTP 상태인지조차 알 수 없음
    "net.peer.ip": "192.168.1.10"
}
http_duration_histogram.record(520, attributes=bad_attributes)
print("❌ [BAD] Metric with generic attributes recorded.")

 

위 코드를 실행하면 콘솔에 다음과 같은 Raw 데이터가 출력될 수 있습니다. (출력 형식은 Exporter에 따라 다름)

// ✅ 좋은 예시의 Raw Metric Data
{
  "name": "http.server.duration",
  "data": {
    "sum": 150,
    "count": 1,
    // ...
  },
  "attributes": {
    "http.method": "GET",
    "http.status_code": 200,
    "net.peer.ip": "192.168.1.1"
  }
}

// ❌ 나쁜 예시의 Raw Metric Data
{
  "name": "http.server.duration",
  "data": {
    "sum": 520,
    "count": 1,
    // ...
  },
  "attributes": {
    "method": "POST",
    "status": 500,
    "net.peer.ip": "192.168.1.10"
  }
}

 

Raw 데이터를 보면 차이가 명확하죠? good_attributes 쪽은 누가 보더라도 http.method가 HTTP 요청 메서드임을, http.status_code가 HTTP 상태 코드임을 알 수 있습니다. 이것이 바로 데이터의 상호 운용성(Interoperability)과 일관성(Consistency)을 높이는 방법입니다.

 

🧐 다른 방법들은 왜 정답이 아닐까요?

1. 그냥 일반적인 이름 사용하기 (예: status, name, type)

• 왜 아닌가요? 😵 위에서 설명했듯, '이름 충돌'의 주범입니다. type이라는 속성은 메시지 큐에서는 메시지 타입, DB에서는 쿼리 타입, 시스템에서는 CPU 타입 등 수십 가지 의미로 사용될 수 있습니다. 이렇게 되면 데이터를 종합적으로 분석하는 것이 거의 불가능해집니다.

2. 모든 속성에 고유한 접두사 붙이기 (예: my_http_status, my_db_status)

• 왜 아닌가요? 🗣️ 이름 충돌은 피할 수 있겠지만, OpenTelemetry의 가장 큰 장점 중 하나인 'Semantic Conventions(의미론적 명세)'를 위반하게 됩니다. OpenTelemetry는 http.method, db.statement처럼 널리 사용되는 속성들에 대해 표준 이름을 정의해두었습니다. 이 표준을 따르면 Grafana, Datadog 등 다양한 분석 도구들이 별도 설정 없이도 데이터를 자동으로 인식하고 멋진 대시보드를 만들어줍니다. 우리만의 '방언'을 만드는 것은 이런 편리함을 포기하는 것과 같습니다.

 

결론: 표준을 따라서 명확하게! ✨

Observability는 단순히 데이터를 모으는 행위가 아니라, 그 데이터를 통해 시스템을 이해하는 과정입니다. OpenTelemetry 메트릭 속성에 네임스페이스를 적용하는 것은 이 과정을 훨씬 원활하고 정확하게 만들어주는 작지만 강력한 규칙입니다.

• 핵심 요약: 특정 메트릭에만 관련된 속성이라면 http.status_code처럼 네임스페이스를 꼭 사용하자!

이렇게 잘 정제된 데이터는 미래의 나, 그리고 동료들에게 디버깅 시간을 단축시켜주는 최고의 선물이 될 것입니다. 🎁

---