OpenTelemetry (OTel) предоставляет данным наблюдаемости общий словарь через свои семантические конвенции, однако этот словарь продолжает развиваться. Например, когда в OpenTelemetry были стабилизированы семантические конвенции HTTP, атрибут http.method стал называться http.request.method. Поскольку организации могут одновременно использовать сервисы, инструментированные разными версиями конвенций, и сервисы, использующие нативные конвенции Datadog, запросы должны корректно работать со всеми этими представлениями.
На первый взгляд, поддержка этих конвенций может показаться простой задачей сопоставления: например, http.method сопоставляется с http.request.method. Но семантическая эквивалентность — это нечто более сложное, чем просто совпадение имен. Две метрики могут представлять одну и ту же концепцию, используя при этом разные единицы измерения или типы метрик. Эквивалентность может применяться только при наличии определенного тега, а один и тот же атрибут может иметь разные значения в зависимости от контекста. Сопоставление только по именам может привести к неполным или неверным результатам запросов.
В Datadog мы представляем эти взаимосвязи в виде графа знаний под названием Semantic Core. Граф фиксирует эквивалентности между метриками и атрибутами спанов Datadog и OpenTelemetry, а также условия, определяющие, когда эти эквивалентности действительны. Datadog применяет эти знания во время выполнения запроса, позволяя запросам прозрачно разрешать эквивалентные данные телеметрии независимо от подходов к инструментированию и версий конвенций, без необходимости перезаписи хранимых данных или участия пользователей в процессе определения того, как эти данные были созданы.
В этой статье мы объясним, почему семантические сопоставления требуют большего, чем просто плоская таблица трансляции, как мы представляем условные эквивалентности в Semantic Core и как мы проверяем их на реальных данных телеметрии.
Одновременная поддержка нескольких семантических конвенций
Поддержка смешанного инструментирования — это не разовая миграция с одного словаря на другой. Сервисы, использующие нативные средства Datadog и OTel, могут сосуществовать бесконечно долго, а сервисы OTel могут одновременно передавать данные с использованием разных версий семантических конвенций. Уровень запросов должен разрешать эквивалентную семантику для всех них, чтобы продукты и пользователи не были вынуждены учитывать каждое физическое имя.
Почему нам понадобился граф, а не плоская таблица сопоставлений
Плоская таблица сопоставлений, такая как http.method → http.request.method, может справиться с прямыми подстановками, но наши требования выходят за рамки сопоставлений «один к одному». Нам необходимо представлять транзитивные отношения, условные эквивалентности и метаданные о том, когда эквивалентность является действительной.
Семантические конвенции OpenTelemetry развиваются, и клиенты не обновляют свое инструментирование синхронно. В любой момент времени некоторые сервисы могут передавать http.method (устаревший атрибут до стабилизации), в то время как другие передают http.request.method (текущая конвенция), и оба должны корректно разрешаться относительно @http.method в Datadog. Плоская таблица, сопоставляющая только текущее имя OTel, незаметно перестает работать для сервисов, использующих старую конвенцию. В графе ребро «устаревшее → текущее» делает устаревшее имя транзитивно доступным для запросов без необходимости явного перечисления каждой пары между словарями. Плоские сопоставления также не могут фиксировать происхождение: кто определил эквивалентность, к какой версии конвенции она применяется и является ли она стабильной или экспериментальной. Наконец, они не масштабируются на несколько словарей без кратного увеличения количества явных сопоставлений.
Граф знаний дает нам более богатую модель данных для представления этих отношений и условий их корректности. В Semantic Core метрики представлены как узлы, содержащие метаданные, такие как тип или единицы измерения. Теги, связанные с этими метриками, являются отдельными узлами, соединенными с метриками, в которых они появляются. Эквивалентности — это ребра: между узлами метрик, чтобы выразить, что две метрики представляют одну и ту же концепцию, и между узлами тегов, чтобы выразить, что два имени тегов относятся к одному и тому же объекту. Важное отличие заключается в том, что ребро может описывать не только эквивалентность, но и условия, при которых эта эквивалентность соблюдается.
Когда эквивалентных имен недостаточно
Что делает эквивалентности более сложными для определения, чем кажется на первый взгляд, так это то, что они — не просто сопоставления имен, они несут в себе условия корректности.
Возьмем system.cpu.utilization (OTel) и system.cpu.user (Datadog): оба могут представлять использование процессора в пользовательском пространстве, но их эквивалентность требует фильтра по тегу и коэффициента масштабирования. Фильтр state:user изолирует время пользовательского пространства в метрике OTel. Коэффициент масштабирования учитывает разницу в единицах измерения: метрика OTel сообщает коэффициент в диапазоне [0,1], в то время как метрика Datadog сообщает процент в диапазоне [0,100]. Наивное сопоставление только по именам упускает оба этих фактора и выдает неверные результаты без каких-либо предупреждений.
Типы метрик добавляют еще один уровень сложности: http.server.request.duration (гистограмма OTel) и trace.web.request.duration (распределение Datadog) представляют одну и ту же концепцию, но в разных типах метрик. Эквивалентность сохраняется для запросов перцентилей, но нарушается для агрегаций по общему количеству или сумме, где структуры бакетов различаются. Это означает, что семантическая эквивалентность может зависеть от выполняемой операции, а не только от самих метрик. Метаданные ребер графа дают нам возможность закодировать эти условия, вместо того чтобы рассматривать каждое сопоставление как универсально взаимозаменяемое.
Представление эквивалентностей в графе — это только часть проблемы: эти эквивалентности также должны быть доступны, когда Datadog выполняет запрос, без необходимости обращения к графу для каждого запроса. Semantic Core создает предварительно вычисленную конфигурацию эквивалентностей, которую использует Semantics SDK. Механизмы запросов используют эту кэшированную конфигурацию для переписывания запросов в памяти, а не для обращения к графу во время выполнения.
Как переписывание запросов меняет то, что видят клиенты
Когда запрос ссылается на имя атрибута, SDK ищет это имя в своем кэше эквивалентностей. Если эквивалентности существуют, запрос переписывается для охвата всех эквивалентных выражений.
Одно из самых простых преобразований — это расширение через OR. Запрос service.name:payments (OTel) расширяется до (service.name:payments OR service:payments), охватывая нативный эквивалент Datadog. Запрос метрики system.cpu.user (нативная Datadog) расширяется, чтобы также охватить system.cpu.utilization{state:user} (OTel), с сохранением соответствующей семантики агрегации.
Эти примеры также показывают, почему условия корректности, хранящиеся в графе, важны во время выполнения: переписывание имени метрики без добавления необходимого фильтра по тегу или преобразования изменило бы смысл запроса.
Важно отметить, что переписывание работает в обоих направлениях. Мы не просто расширяем запрос, чтобы найти данные, хранящиеся под другим именем. Мы также нормализуем результаты так, чтобы они соответствовали словарю запроса. Если вы делаете запрос с использованием нативных имен Datadog, вы видите результаты в формате Datadog, даже если исходные данные были получены как OpenTelemetry. Трансляция прозрачна для вызывающей стороны.
Как мы проверяем семантические эквивалентности
Кодирование взаимосвязи в графе само по себе не доказывает, что эта взаимосвязь верна. Поскольку эквивалентности могут зависеть от единиц измерения, тегов, типов метрик и контекста, нам также необходимо проверять их на основе поведения реальных телеметрических данных.
Проверка начинается с команд, которые отвечают за каждый домен. Эксперты в предметной области подтверждают семантические определения и задают сценарии тестирования, которые абстрагируются от базовой инфраструктуры, будь то запуск Datadog Agent, OTel Collector или обоих компонентов. Команды описывают ожидаемое поведение эквивалентности, не вникая в прямое управление тестовой средой. Затем мы проверяем эквивалентности в Datadog на реальных телеметрических данных.
Измерения корректности изнутри системы недостаточно. Semantics SDK может сообщать о том, найдены ли эквивалентности и обслуживаются ли они из кэша, но эти сигналы описывают поведение самой системы, а не то, являются ли применяемые ею эквивалентности действительно верными для реальных данных телеметрии. Для этого мы используем внешний валидатор.
Валидатор запускает один и тот же сценарий одновременно для нескольких конфигураций: только OTel, только Datadog и гибридной конфигурации, объединяющей компоненты OTel и Datadog. Каждый сценарий отправляет реальные телеметрические данные, выполняет одни и те же запросы, используя словари как OTel, так и Datadog, и проверяет согласованность результатов во всех конфигурациях.
Проверка является сквозной: отправка данных, выполнение запроса и сравнение результатов происходят как единый процесс. Любой пробел в эквивалентностях, такой как отсутствие эквивалентности, неверное преобразование единиц измерения или отсутствие тега, необходимого для соблюдения эквивалентности, приводит к обнаруживаемому расхождению результатов.
Это позволяет нам тестировать свойство, которое нас действительно волнует: эквивалентные запросы должны давать эквивалентные результаты, даже если базовая инструментация и семантические соглашения различаются.
Когда проверка не проходит, мы уведомляем ответственную команду, которая принимает меры. Поскольку конфигурации эквивалентности динамически распространяются на экземпляры SDK без необходимости перезапуска службы, ошибочная эквивалентность может быть исправлена и быстро развернута по всей платформе.
Что дальше
По мере роста числа семантических соглашений и поддерживаемых сигналов наблюдаемости задача смещается от определения отдельных эквивалентностей к поддержанию корректности большого, постоянно развивающегося набора эквивалентностей.
Поддержка графа — это федеративная задача: инженерные команды, владеющие каждым продуктовым доменом, также владеют его семантическими эквивалентностями. Каждая команда достаточно хорошо понимает телеметрические данные своего домена, чтобы определить условия корректности — какие атрибуты соответствуют друг другу, при каких типах метрик и в каких контекстах. Команды передают эти определения и связанные с ними метаданные команде платформы для включения в граф, после чего новые наборы эквивалентностей автоматически распространяются на экземпляры SDK.
Поддержание этих эквивалентностей в актуальном состоянии по мере развития OTel — это непрерывный процесс. Semantic Core периодически сканирует репозитории семантических соглашений OTel и выявляет новые или измененные определения метрик и тегов для соответствующих команд. Например, когда OTel стабилизировала свои семантические соглашения HTTP и переименовала несколько атрибутов, эти изменения были автоматически помечены, чтобы соответствующие команды могли обновить свои эквивалентности.
Инструментарий вокруг Semantic Core продолжает развиваться по мере роста графа. Создание эквивалентностей в масштабе, управление владением в разных пространствах имен интеграции и проверка изменений в различных средах инструментации теперь сами по себе являются инженерными задачами.
Семантическая трансляция как инфраструктура
Семантическая интероперабельность требует большего, чем просто перевод одного имени атрибута в другое. Она требует представления того, что означают телеметрические данные, и условий, при которых два представления можно безопасно считать эквивалентными.
Представляя эти взаимосвязи явно в Semantic Core и применяя их во время выполнения запроса, мы можем отделить словарь, используемый для запроса телеметрических данных, от имен, использованных при создании этих данных. Это позволяет различным подходам к инструментации и версиям семантических соглашений сосуществовать без необходимости учитывать каждое представление в каждом отдельном запросе.
Поскольку OpenTelemetry продолжает развиваться, нам необходимо поддерживать Semantic Core в актуальном состоянии с учетом новых и изменяющихся соглашений. Это означает оценку того, являются ли метрики и атрибуты действительно эквивалентными, учет таких условий, как теги, единицы измерения и типы метрик, а также проверку этих сопоставлений на реальных телеметрических данных. Рассмотрение семантической трансляции как инфраструктуры дает нам последовательный способ управления этой работой по мере изменения соглашений и сред инструментации.
Если решение таких задач, как семантическая трансляция в масштабе, кажется вам интересным, ознакомьтесь с нашими открытыми инженерными вакансиями в Datadog.











