Расширенная конфигурация

На этой странице:

Настройка именования сервисов и дополнительных тегов
Алгоритм группировки эндпоинтов
Объединение быстрых SQL запросов в трейсах

Настройка именования сервисов и дополнительных тегов

Для добавления дополнительной мета-информации к трейсам и метрикам используются теги (лейблы). Теги делятся на произвольные и зарезервированные.

Формат тегов

Теги должны начинаться с буквы и после нее могут содержать символы, перечисленные ниже:

буквенно-цифровые символы
подчеркивания
минусы
двоеточия
точки
слэши

Другие специальные символы преобразуются в символы подчеркивания.

Теги могут содержать до 200 символов и поддерживают буквы Unicode.

Теги для метрик преобразуются в нижний регистр, для тегов спанов регистр не меняется. Поэтому не рекомендуется использовать теги CamelCase.

Тег может быть в формате value или <KEY>:<VALUE>. Ключ всегда предшествует первому двоеточию в глобальном определении тега, например:

TAG	KEY	VALUE
`env:staging:east`	`env`	`staging:east`
`env_staging:east`	`env_staging`	`east`

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

Зарезервированные теги

`service` – имя сервиса

Каждому сервису в интерфейсе Proto OBP присваивается определенное имя сервиса. Имя сервиса может определяться автоматически, правила и возможности автоматического определения зависят от среды исполнения сервиса, языка разработки, параметров окружения и тд.

В случае, если имя сервиса, присваиваемое по умолчанию, не является достаточно информативным или уникальным, есть возможность переопределить имя сервиса.

Для задания имени сервиса используется переменнная окружения POBP_SERVICE.

`env` – название окружения

Для указания в каком окружении запущен сервис, например, DEV, STAGE, PRODUCTION и т.д. добавьте переменную окружения POBP_ENV. Значением переменной могут быть любые символы.

После указания пременной окружения к трейсам будет добавлен тег со значением переменной POBP_ENV.

Также будет изменено название сервиса. Например, при значении перевенных POBP_SERVICE=my-app и POBP_ENV=dev, итоговое имя сервиса будет отображаться как my-app-dev. Данное поведение может быть изменено в будущих версиях.

`version` – версия приложения

Для указания версии сервиса может использоваться переменная окружения POBP_VERSION. Значением переменной могут быть любые символы.

После указания пременной окружения к трейсам будет добавлен тег со значением переменной POBP_VERSION.

`service_group` – группа, к которой относится сервис

Для указания к какому бизнес-приложению или системе относится сервис, например, Ddbo_Fiz, Online_banking и т.д. добавьте тег с ключом service_group.

Пример:

POBP_TAGS="team:frontend-ecomm, service_group:ecommerce_app"
POBP_ENV="production"

`team` – команда, к которой относится сервис

Для указания к какой команде или подразделению относится сервис, например, frontent_devs, faktoring, external_dbo и т.д. добавьте тег с ключом team.

Пример:

POBP_TAGS="team:frontend-ecomm, service_group:ecommerce_app"
POBP_ENV="production"

Произвольные теги

Для использования произвольных тегов добавьте их к значению переменной окружения POBP_TAGS, например:

ENV POBP_TAGS=custom_tag:value,another_tag:somevalue

Добавление тегов

apiVersion: apps/v1
kind: Deployment
...
template:
  containers:
  -  ...
    env:
      - name: POBP_ENV
        value: "<ENV>"
      - name: POBP_SERVICE
        value: "<SERVICE>"
      - name: POBP_VERSION
        value: "<VERSION>"

Теги можно задать в Dockerfile:

ENV POBP_SERVICE=<SERVICE>
ENV POBP_VERSION=<VERSION>
ENV POBP_ENV=<ENV>
ENV POBP_TAGS=<TAGS>

Или в момент запуска приложения:

docker run -e POBP_ENV="<ENV>" \
           -e POBP_SERVICE="<SERVICE>" \
           -e POBP_VERSION="<VERSION>" \
           ...

Примеры использования тегов

Добавление связи сервиса с инфраструктурой Kubernetes

Для этого в спецификации пода с приложением добавьте следующие пермененные окружения:

  - name: NODE_NAME
    valueFrom:
        fieldRef:
            fieldPath: spec.nodeName
  - name: POD_NAMESPACE
    valueFrom:
        fieldRef:
            fieldPath: metadata.namespace
  - name: POD_NAME
    valueFrom:
        fieldRef:
            fieldPath: metadata.name
  - name: POBP_TAGS
    value: "pod_name:$(POD_NAME),node:$(NODE_NAME),kube_namespace:$(POD_NAMESPACE),kube_cluster_name:<my_cluster_name>"

Переменная окруженияPOBP_TAGS добавляет тэги в формате key:value,key1:value1 к каждому вызову инструментированного приложения.

После этого соответствующие теги появятся в деталях вызовов и будут доступны при фильтрации трейсов по тегам:

Сбор кастомных HTTP заголовков

Добавьте переменную окружения к приложению:

POBP_TRACE_HEADER_TAGS="<ИМЯ_HTTP_ЗАГОЛОВКА>,<ИМЯ_HTTP_ЗАГОЛОВКА>"

В значение переменной, через зяпятую, укажите список HTTP заголовков которые необходимо собирать. Заголовки будут доступны в деталях вызова в виде тэга http.request.headers.<ИМЯ_HTTP_ЗАГОЛОВКА>:<ЗНАЧЕНИЕ>

Использование имени хоста, как Service Instance для приложений

Для этого добавьте переменную окружения на хост или в Docker контейнер:

POBP_TAGS="host.name:<my_host_name>"

Алгоритм группировки эндпоинтов

Если в названии эндпоинта используется HTTP URL, то строка вида GET /some/path/any-page.html нормализуется к виду GET /*. Добавлен список часто встречающихся сегментов для сохранения в имени эндпоинтов. Например, строка вида GET /api/v1/web/getUser/123456789 будет нормализована к виду GET /api/v1/web/getUser/*, так как сегменты api, v1, web и get добавлены в список исключений для нормализации.

Полный список сегментов, которые не будут нормализованы:

"_health",
"about", "account", "activ", "add", "admin", "advance", "agree", "ajax", "anal", "all", "android", "animate", "api", "app", "attach", "audit", "auth", "auto", "availab", "average",
"balance", "bank", "banner", "base", "basket", "batch", "bill", "bind", "bitrix", "black", "block", "borrow", "bonus", "box", "branch", "build", "buy", "broker",
"cache", "call", "calc", "cancel", "card", "cart", "cash", "catalog", "categor", "change", "check", "cheque", "choose", "cities", "city", "clean", "clear", "client", "close", "code", "complet", "compan", "component", "config", "confirm", "contact", "content", "context", "conver", "count", "collect", "create", "credit", "cross", "curren", "custom", "cvv",
"dash", "data", "decline", "default", "delete", "deliver", "deposit", "device", "discard", "discount", "dist", "doc", "down", "draft", "drop",
"edit", "email", "en", "event", "exchange", "experiment", "export", "express",
"favorite", "feature", "fee", "fetch", "find", "file", "filter", "finance", "finish", "fiscal", "foot", "fraud", "free", "frontend", "fund",
"gateway", "get", "grade", "graphql", "group",
"head", "health", "healz", "heart", "help", "history", "home", "http",
"id", "image", "include", "index", "info", "init", "insur", "int", "item", "invoice",
"js",
"last", "left", "level", "lib", "link", "lim", "list", "load", "loan", "local", "locat", "log", "loy",
"mail", "main", "map", "master", "match", "media", "menu", "message", "method", "metric", "mobile", "model", "modify", "mono", "mortgage", "move", "multi",
"new", "next", "nfc", "nginx", "notif",
"oauth", "off", "onboard", "open", "opt", "order", "other", "otp", "owox", "organ",
"p2p", "pack", "page", "partner", "parameter", "pass", "pay", "perf", "person", "phone", "pick", "pictur", "pin", "place", "pobp", "polic", "position", "post", "pre", "print", "priv", "process", "product", "profile", "project", "promo", "prompt", "proto", "purchase", "push", "put",
"quote",
"rate", "rating", "read", "realm", "receive", "recipe", "recur", "replace", "require", "recom", "refresh", "refund", "region", "registr", "remote", "remove", "render", "report", "request", "resend", "reset", "resolve", "resource", "resp", "rest", "review", "right", "ru", "sale", "save",
"sample", "send", "sber", "shelf", "short", "scan", "screen", "script", "search", "secur", "segment", "select", "sell", "seo", "service", "session", "set", "shift", "ship", "soap", "shop", "show", "sign", "skip", "social", "sponsor", "ssapi", "start", "stat", "stop", "subscr", "suggest", "sum", "super", "sync",
"tag", "task", "template", "terminate", "terms", "tinkof", "token", "tool", "top", "transf", "transp",
"unbind", "unblock", "union", "unique", "unpaid", "update", "upload", "use", "utility",
"v1", "v2", "v3", "v4", "v5", "v6", "v7", "v8", "v9", "video", "view", "visa", "vote", "voting", "vtb",
"wallet", "web", "widget",
"xo-stats",
"yandex"

Логика работы - сегменты из списка выше, а также все следующие за ними буквенные символы не будут заменены на *. Например, в списке есть сегмент view, тогда имя эндпоинта (Url) вида GET /viewSomething/123 будет заменено на GET /viewSomething/* (так как после view идут только буквенным символы в сегменте). При этом следующие строки размаскированы не будут:

GET /view-Something/123 -> GET /* (так как присутствует символ -)
GET /view_Something/123 -> GET /* (так как присутствует символ _)
GET /view.Something/123 -> GET /* (так как присутствует символ .)
GET /viewSomething-1/123 -> GET /* (так как присутствует цифра)

Для добавления собственных сегментов используется переменная в файле <installation dir>/debug/config.yaml, пример:

POBP_COLLECTOR_CUSTOM_ALLOWED_SEGMENTS:
  - portfolio

После добавления этой переменной строка вида GET /api/v1/web/portfolio/123456789 будет нормализована к виду GET /api/v1/web/portfolio/*.

Объединение быстрых SQL запросов в трейсах

Для упрощения анализа трейсов, содержащих большое количество спанов с SQL запросами, реализован механизм объединения спанов с SQL запросами, если длительность их выполнения меньше определенной величины. Это позволяет не обращать внимание на десятки или сотни спанов с SQL вызовами, которые не влияют на общую производительность транзакции.

Пример трейса без объединения быстрых SQL запросов - видно множество спанов, в которых производились вызовы SQL длительностью 0 мс, 1 мс и тд:

Пример трейса этой же транзакции, но с включенным объединением быстрых SQL запросов - все спаны с вызовами SQL, длительность менее 5 мс объединены в один спан с общей длительностью, равно общей длительности всех объединенных спанов:

Если после нескольких объединенных быстрых SQL запросов будет встречаться SQL запрос с длительностью, превышающей пороговую, или спан с ошибкой, то этот спан с SQL запросом не будет объединен и будет всегда показан отдельно. Объединению подлежат только спаны с SQL вызовами, идущими к одной и той же базе данных подряд.

В деталях объединенного спана будут указаны общие теги для всех вызовов. В теге db.statement будет указано общее количество объединенных спанов и примененное пороговое значение в мс, пример:

Fast SQL: 5 spans faster than 5 ms combined

Управлять этой опцией можно через два конфигурационных параметра в файле config.yaml:

# включает или выключает объединение быстрых SQL запросов, по умолчанию включено (true)
POBP_TRACE_PROCESSOR_CONFIG_FAST_SQL_SPANS_MERGE: true
# пороговое время длительности исполнения SQL запросов, которые считаются быстрыми - в мс, по умолчанию 5 мс
POBP_TRACE_PROCESSOR_CONFIG_FAST_SQL_SPANS_TIME: 5