Метрики - это количественный фундамент наблюдаемости. Это те самые числа, которые показывают, как работает наша система.
Это третья статья из серии о правилах именования в OpenTelemetry - ранее мы уже разбирали, как правильно называть спаны и как обогащать их атрибутами. Теперь настало время поговорить о том, как называть метрики, чтобы они были понятны и полезны.
В отличие от спанов, которые рассказывают истории о событиях, метрики показывают количественные данные: сколько, как часто, насколько быстро.
Но - и это важно - хорошие имена для метрик не менее критичны, чем для спанов. И те же принципы применимы и здесь: “кто” — всегда в атрибутах, а не в имени.
Чему можно научиться у традиционных систем
Прежде чем говорить об OpenTelemetry, давайте посмотрим, как метрики именовались раньше.
Например, в Kubernetes часто встречаются такие шаблоны:
scheduler_schedule_attempts_total
container_cpu_usage_seconds_total
kubelet_volume_stats_used_bytes
Здесь заметен общий паттерн: компонент + ресурс + действие + единица измерения.
То есть имя метрики сразу включает название сервиса. Это было логично в старых моделях данных, где не было богатого контекста.
Однако у такого подхода есть серьёзные минусы:
- метрики разных сервисов дублируются и засоряют систему наблюдения;
- невозможно агрегировать значения между компонентами;
- имена метрик становятся “жёстко привязанными” к конкретным сервисам;
- каждый новый сервис требует новых имён метрик.
Главная ошибка: имя сервиса в названии метрики
Главное правило OpenTelemetry:
не включайте имя сервиса в имя метрики.
Например, у вас есть сервис оплаты. Возникает соблазн создать такие метрики:
payment.latency.p95
payment.error.rate
Но так делать не стоит.
Имя сервиса уже есть в контексте - в атрибуте service.name.
Правильный вариант:
http.server.request.duration (service.name=payment)
error.rate (service.name=payment)
Почему это лучше?
Потому что теперь можно агрегировать данные по всем сервисам:
sum(transaction.count{service.name="payment"}) # Только для сервиса payment
Если бы имя сервиса было “вшито” в метрику, пришлось бы писать отдельные запросы для каждого сервиса.
Модель контекста OpenTelemetry
В OpenTelemetry контекст не прячется в имени - он структурирован в несколько уровней:
ресурсы, scope (область инструментации) и атрибуты.
Традиционный подход (Prometheus-стиль):
user_service_auth_latency_milliseconds{endpoint="/login",region="us-east"}
inventory_service_db_query_seconds{table="products",operation="select"}
OpenTelemetry-подход:
- 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, где контекст распределён по уровням, а не “сплющен” в имя.
Единицы измерения - не часть имени
Аналогично: единицы измерения не должны быть частью имени метрики.
Раньше было так:
memory_usage_bytes
throughput_requests_per_second
В OpenTelemetry единицы измерения указываются отдельно:
system.memory.usage {unit: By}
http.server.request.rate {unit: {request}/s}
Преимущества:
- читаемые имена без “хвостов”;
- поддержка стандарта UCUM (Unified Code for Units of Measure);
- автоматическое преобразование единиц в системах наблюдения;
- совместимость со всеми OpenTelemetry-инструментами.
Практические рекомендации
При выборе имени метрики используйте схему {глагол}.{объект} - как и для спанов.
- Фокус на действии, а не на том, кто выполняет.
- Не добавляйте имя сервиса.
- Не включайте единицы измерения.
- Следуйте семантическим соглашениям 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. - Какое главное правило именования метрик?
Имя метрики должно описывать что измеряется, а не кто измеряет. Всё остальное - версия, сервис, окружение - хранится в атрибутах.