Новости
Обновление услуги LLM: управление API-ключами, моделями и расходами
DF
октября 23, 2025
Обновлено ноября 6, 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}

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

  • читаемые имена без “хвостов”;
  • поддержка стандарта UCUM (Unified Code for Units of Measure);
  • автоматическое преобразование единиц в системах наблюдения;
  • совместимость со всеми OpenTelemetry-инструментами.

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

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

Правильно Неправильно
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

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

  • Агрегация между сервисами: один запрос вроде sum(transaction.count) возвращает данные по всем сервисам.
  • Универсальные дашборды: один и тот же дашборд подходит для всех микросервисов - достаточно фильтровать по service.name.
  • Меньше “шума” в неймспейсе: вместо сотен похожих имён остаётся одно (request.count), а контекст задаётся атрибутами.
  • Автоматическая конвертация единиц: теперь метрика request.duration с unit=ms может быть визуализирована и в секундах, и в миллисекундах.
  • Совместимость автогенерации и ручных метрик: все метрики следуют единому соглашению и совместимы с автоинструментами.

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

  • Включение версии или окружения в имя: user_service_v2_latency ломается после релиза v3.
  • Привязка к инфраструктуре: node_42_memory_usage теряет смысл при масштабировании.
  • Префиксы окружений (prod_, staging_) усложняют сравнение.
  • Указание технологии (nodejs_payment_memory) делает имя неактуальным при смене стека.
  • Смешение доменов: ecommerce_cpu_usage - плохой пример (домены и системные метрики нельзя смешивать).

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

Итог

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

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

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

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

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

  • Почему важно правильно называть метрики?
    От корректного нейминга зависит удобство анализа данных и построения дашбордов. Хорошо названные метрики легко агрегировать, фильтровать и использовать повторно в разных сервисах.
  • Почему не стоит включать имя сервиса в название метрики?
    В OpenTelemetry имя сервиса хранится как атрибут service.name. Если добавить его в название, это создаст дубликаты метрик и усложнит агрегацию между сервисами.
  • Нужно ли указывать единицы измерения в названии метрики?
    Нет. OpenTelemetry хранит единицы в метаданных. Это позволяет платформам автоматически конвертировать значения (например, секунды в миллисекунды) и сохранять читаемость имён.
  • Какой формат имени метрики считается правильным?
    Следует использовать короткий и понятный формат: {действие}.{объект}. Например, http.server.request.duration вместо payment_http_requests_ms.
  • Можно ли использовать собственные названия метрик?
    Да, но рекомендуется придерживаться семантических соглашений OpenTelemetry, чтобы ваши данные были совместимы с другими инструментами.
  • Как избежать проблем при миграции со старых систем мониторинга?
    Разделите контекст и имя: используйте чистое имя метрики и добавляйте детали (сервис, окружение, версию) как атрибуты. Это упростит перенос данных и унифицирует дашборды.
  • Что делать с метриками, где нужно указать технологию (например, PostgreSQL)?
    Указывайте технологию через атрибуты или префикс области (scope). Например: db.client.operation.duration с атрибутом db.system=postgresql.
  • Какое главное правило именования метрик?
    Имя метрики должно описывать что измеряется, а не кто измеряет. Всё остальное - версия, сервис, окружение - хранится в атрибутах.
Оценка:
5 из 5
Аverage rating : 5
Оценок: 1
191028 Санкт-Петербург Литейный пр., д. 26, Лит. А
+7 (812) 403-06-99
700 300
ООО «ИТГЛОБАЛКОМ ЛАБС»
700 300

Вам также может быть интересно...