☰
06.11.2025

Как правильно называть метрики в OpenTelemetry

Метрики - это количественный фундамент наблюдаемости. Это те самые числа, которые показывают, как работает наша система.
Это третья статья из серии о правилах именования в OpenTelemetry - ранее мы уже разбирали, как правильно называть спаны и как обогащать их атрибутами. Теперь настало время поговорить о том, как называть метрики, чтобы они были понятны и полезны.

В отличие от спанов, которые рассказывают истории о событиях, метрики показывают количественные данные: сколько, как часто, насколько быстро.
Но - и это важно - хорошие имена для метрик не менее критичны, чем для спанов. И те же принципы применимы и здесь: “кто” — всегда в атрибутах, а не в имени.

Чему можно научиться у традиционных систем

Прежде чем говорить об OpenTelemetry, давайте посмотрим, как метрики именовались раньше.
Например, в Kubernetes часто встречаются такие шаблоны:

apiserver_request_total
scheduler_schedule_attempts_total
container_cpu_usage_seconds_total
kubelet_volume_stats_used_bytes

Здесь заметен общий паттерн: компонент + ресурс + действие + единица измерения.
То есть имя метрики сразу включает название сервиса. Это было логично в старых моделях данных, где не было богатого контекста.

Однако у такого подхода есть серьёзные минусы:

Главная ошибка: имя сервиса в названии метрики

Главное правило OpenTelemetry:
не включайте имя сервиса в имя метрики.

Например, у вас есть сервис оплаты. Возникает соблазн создать такие метрики:

payment.transaction.count
payment.latency.p95
payment.error.rate

Но так делать не стоит.
Имя сервиса уже есть в контексте - в атрибуте service.name.

Правильный вариант:

transaction.count (service.name=payment)
http.server.request.duration (service.name=payment)
error.rate (service.name=payment)

Почему это лучше?
Потому что теперь можно агрегировать данные по всем сервисам:

sum(transaction.count) # Все транзакции во всех сервисах
sum(transaction.count{service.name="payment"}) # Только для сервиса payment

Если бы имя сервиса было “вшито” в метрику, пришлось бы писать отдельные запросы для каждого сервиса.

Запустите проект за минуты с VPS в России — предустановленное ПО, высокая производительность и надёжная инфраструктура Serverspace - Арендовать VPS

Модель контекста OpenTelemetry

В OpenTelemetry контекст не прячется в имени - он структурирован в несколько уровней:
ресурсы, scope (область инструментации) и атрибуты.

Традиционный подход (Prometheus-стиль):

payment_service_transaction_total{method="credit_card",status="success"}
user_service_auth_latency_milliseconds{endpoint="/login",region="us-east"}
inventory_service_db_query_seconds{table="products",operation="select"}

OpenTelemetry-подход:

transaction.count
- Resource: service.name=payment, deployment.environment.name=prod
- Attributes: method=credit_card, status=success

auth.duration
- Resource: service.name=user
- Attributes: endpoint=/login, region=us-east
- Unit: ms

db.client.operation.duration
- Resource: service.name=inventory
- Attributes: db.sql.table=products, db.operation=select
- Unit: s

Такой подход соответствует спецификации OpenTelemetry, где контекст распределён по уровням, а не “сплющен” в имя.

Единицы измерения - не часть имени

Аналогично: единицы измерения не должны быть частью имени метрики.

Раньше было так:

response_time_milliseconds
memory_usage_bytes
throughput_requests_per_second

В OpenTelemetry единицы измерения указываются отдельно:

http.server.request.duration {unit: ms}
system.memory.usage {unit: By}
http.server.request.rate {unit: {request}/s}

Преимущества:

Практические рекомендации

При выборе имени метрики используйте схему {глагол}.{объект} - как и для спанов.

Правильно Неправильно
http.server.request.duration payment_http_requests_ms
db.client.operation.duration user_service_db_queries_seconds
transaction.count payment_transaction_total
messaging.client.sent.messages order_service_messages_sent_total

Преимущества чистых имён

Типичные ошибки

Контекст, который меняется (версия, среда, инстанс), должен быть в атрибутах, а не в имени.

Итог

Хорошо названная метрика - это подарок вашему будущему “я”.
Она делает данные наблюдаемыми, дашборды - универсальными, а инциденты - понятными.

Главный принцип прост:

имя метрики описывает, что измеряется, а не кем или где.

Всё остальное - в атрибутах, где контекст гибко фильтруется и агрегируется.

Часто задаваемые вопросы (FAQ)