Руководство прикладного разработчика#
Термины и определения#
Общие термины и определения, используемые в данном документе, представлены в общей документации продукта Platform V Monitor (OPM).
Термин/Аббревиатура |
Определение |
|---|---|
Management application |
Компонент Единого коллектора, предоставляющий пользователям возможность управления настройками и мониторинга сбора метрик |
Prometheus-агент |
Модуль клиентской части Prometheus, который собирает метрики с клиентских приложений |
Pull-модель сбора |
Модель сбора данных, где инициатором выступает серверная сторона, а не клиентская. Также модель называют активной |
Push-модель сбора |
Модель сбора данных, где клиент отправляет запросы на сервер, а сервер публикует API для их обработки. Также модель называют пассивной |
Pipeline сбора телеметрических данных |
Конвейер обработки информации. Представлен набором компонентов и связей между ними |
Zipkin |
Распределенная система отслеживания данных в реальном времени |
Системные требования#
В этом разделе представлены только минимальные требования КТС, прочие требования к окружению и конфигурации представлены в «Руководстве по установке».
Минимальные КТС#
Сервис |
RAM |
CPU |
Кол-во инстансов |
|---|---|---|---|
Pipeline Management Application |
2048 |
1 |
1 |
Pull Collector |
4096 |
2 |
2 |
Push Collector |
4096 |
2 |
2 |
Ingress/Egress/ISTIO/FluentBit/Unimon-agent |
4096 |
2 |
- |
Зависимость пропускной способности от требуемых КТС представлена в отчетах НТ.
Подключение и конфигурирование push-api#
Перед началом работы с Единым коллектором ваш проект должен быть зарегистрирован в Abyss, а также в проекте должен быть заведен пользователь с правом TC_PIPELINE_PUSH. Доступ к PUSH API Единого коллектора осуществляется по технологии API Key. Ключ выдается администраторами Abyss. После получения ключа можно обращаться к PUSH API Единого коллектора передавая ключ в заголовке X-PVM-API-KEY. Также необходимо настроить Egress на клиенте для исходящего трафика на PUSH API Единого коллектора.
Сбор Prometheus метрик: Настройка Prometheus агентов (Unimon-agent) в клиентском NameSpace#
Все примеры приведены на базе сбора собственных метрик/логов/трассировок!
Чтобы обеспечить сбор прикладных метрик, приложение должно выставить метрики через HTTP-endpoint, например, /metrics (путь может быть любым). Prometheus-agent (или unimon-agent) находит HTTP-endpoint, собирает и обогащает метрики, а затем передает их в приложение. Данные предоставляются в формате Actuator Prometheus. Prometheus читает секцию конфигурации scrape_configs, согласно которой настраивает свой внутренний механизм обнаружения сервисов (Service Discovery). Механизм Service Discovery взаимодействует с Kubernetes API (в основном для получения endpoints). На основании данных из Kubernetes механизм Service Discovery обновляет Targets (список целей).
Структура конфигурации:
global:
# How frequently to scrape targets by default.
[ scrape_interval: <duration> | default = 1m ]
# How long until a scrape request times out.
[ scrape_timeout: <duration> | default = 10s ]
# How frequently to evaluate rules.
[ evaluation_interval: <duration> | default = 1m ]
# The labels to add to any time series or alerts when communicating with
# external systems (federation, remote storage, Alertmanager).
external_labels:
[ <labelname>: <labelvalue> ... ]
# File to which PromQL queries are logged.
# Reloading the configuration will reopen the file.
[ query_log_file: <string> ]
# A list of scrape configurations.
scrape_configs:
[ - <scrape_config> ... ]
# Settings related to the remote write feature.
remote_write:
[ - <remote_write> ... ]
Global секция определяет параметры, которые действительны во всех других контекстах конфигурации. Они также служат значениями по умолчанию для других разделов конфигурации.
Секция scrape_config определяет список заданий сбора.
Секция relabel_configs позволяет добавлять настройки «фильтрации» - какие endpoints будет брать, а какие — нет, и "relabeling" - какие лейблы добавить или удалить (для всех получаемых метрик). Конфигурация Service discovery Kubernetes определяется в секции kubernetes_sd_configs.
Секция remote_write определяет URL-адрес endpoint, на который отправляются метрики.
Подробная структура описана на странице конфигурации Prometheus.
Пример конфигурации Prometheus-агента (фактически в scrape_configs нужно оставить kubernetes-pods и kubernetes-pods-https и далее задать endpoint).
kind: ConfigMap
apiVersion: v1
metadata:
name: unimon-agent-config.r4
labels:
app: unimon-agent
data:
prometheus.yml: |-
global:
scrape_interval: %GLOBAL_SCRAPE_INTERVAL%
scrape_timeout: %GLOBAL_SCRAPE_TIMEOUT%
scrape_configs:
- job_name: 'kubernetes-pods'
kubernetes_sd_configs:
- role: endpoints
namespaces:
names:
- "ci02707148-idevgen-audit-mmv"
relabel_configs:
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
regex: true
action: keep
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_path]
regex: (.+)
target_label: __metrics_path__
action: replace
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scheme]
action: drop
regex: https
- source_labels: [__address__, __meta_kubernetes_service_annotation_prometheus_io_port]
action: replace
target_label: __address__
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
- source_labels: [__meta_kubernetes_namespace]
separator: ;
regex: (.*)
target_label: namespace
replacement: $1
action: replace
- source_labels: [__meta_kubernetes_pod_name]
separator: ;
regex: (.*)
target_label: pod
replacement: $1
action: replace
- source_labels: [__meta_kubernetes_service_name]
separator: ;
regex: (.*)
target_label: service
replacement: $1
action: replace
- source_labels: [__meta_kubernetes_pod_node_name]
separator: ;
regex: (.*)
target_label: nodeName
replacement: $1
action: replace
- action: labelmap
regex: __meta_kubernetes_pod_label_(.+)
- source_labels: [__address__]
separator: ;
regex: (.*)
target_label: unimonVersion
action: replace
replacement: "D-04.000.00-2373_client"
- source_labels: [__address__]
separator: ;
regex: (.*)
target_label: tenant
action: replace
replacement: "undefined"
- source_labels: [__address__]
separator: ;
regex: (.*)
target_label: source
action: replace
replacement: OpenShift
- job_name: 'kubernetes-pods-https'
scheme: https
tls_config:
ca_file: /etc/prom-certs/root-cert.pem
cert_file: /etc/prom-certs/cert-chain.pem
key_file: /etc/prom-certs/key.pem
insecure_skip_verify: true
kubernetes_sd_configs:
- role: endpoints
namespaces:
names:
- "ci02707148-idevgen-audit-mmv"
relabel_configs:
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
regex: true
action: keep
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_path]
regex: (.+)
target_label: __metrics_path__
action: replace
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scheme]
action: keep
regex: https
- source_labels: [__address__, __meta_kubernetes_service_annotation_prometheus_io_port]
action: replace
target_label: __address__
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
- source_labels: [__meta_kubernetes_namespace]
separator: ;
regex: (.*)
target_label: namespace
replacement: $1
action: replace
- source_labels: [__meta_kubernetes_pod_name]
separator: ;
regex: (.*)
target_label: pod
replacement: $1
action: replace
- source_labels: [__meta_kubernetes_service_name]
separator: ;
regex: (.*)
target_label: service
replacement: $1
action: replace
- source_labels: [__meta_kubernetes_pod_node_name]
separator: ;
regex: (.*)
target_label: nodeName
replacement: $1
action: replace
- action: labelmap
regex: __meta_kubernetes_pod_label_(.+)
- source_labels: [__address__]
separator: ;
regex: (.*)
target_label: unimonVersion
action: replace
replacement: "D-04.000.00-2373_client"
- source_labels: [__address__]
separator: ;
regex: (.*)
target_label: tenant
action: replace
replacement: "undefined"
- source_labels: [__address__]
separator: ;
regex: (.*)
target_label: source
action: replace
replacement: OpenShift
remote_write:
- url: "http://{host}:{port}/push/project/{projectName}/pipeline/{pipelineName}/prometheus-proto"
, где http://{host}:{port}/push/project/{projectName}/pipeline/{pipelineName}/prometheus-proto - это http-endpoint push-коллектора для отправки метрик, {projectName} - имя проекта, используемого для сбора данных, {pipelineName} - имя pipeline.
Конфигурация pipeline для импорта:
{
"quota": {
"limitTrafficPerMin": 10000
},
"name": "self-monitoring-pipe",
"input": {
"typeName": "standard-http-api",
"config": "{}"
},
"processors": [
{
"typeName": "prometheus-unimon-converter",
"config": "{\"allowNan\": false, \"required\": false, \"headersToEnrich\": []}",
"order": 1
},
{
"typeName": "jackson-mapper-processor",
"config": "{}",
"order": 2
},
{
"typeName": "pipeline-data-enrichment-processor",
"config": "{}",
"order": 3
},
{
"typeName": "json-flattener-processor",
"config": "{\"flattenMode\": \"KEEP_ARRAYS\", \"standardFlatteningForFieldsWithDots\": false}",
"order": 4
}
],
"outputs": [
{
"typeName": "kafka-output",
"config": "{\"acks\": -1, \"topic\": \"METRICS_TOPIC_NAME\", \"clientId\": \"cidddd\", \"lingerMs\": 0, \"batchSize\": 16384, \"maxBlockMs\": 60000, \"keySerializer\": \"org.apache.kafka.common.serialization.StringSerializer\", \"sslClientAuth\": false, \"requestTimeout\": 30000, \"deliveryTimeout\": 120000, \"valueSerializer\": \"org.springframework.kafka.support.serializer.JsonSerializer\", \"bootstrapServers\": \"KAFKA_ADDRESS_AND_PORT\", \"securityProtocol\": \"SSL\", \"idempotenceEnabled\": true, \"sslKeystoreKeyPass\": \"KAFKA_PASSWORD_ID\", \"sslEnabledProtocols\": \"TLSv1.2\", \"sslKeystoreLocation\": \"/certificates/kafka.jks\", \"sslKeystorePassword\": \"KAFKA_PASSWORD_ID\", \"sslTruststoreLocation\": \"/certificates/kafka.jks\", \"sslTruststorePassword\": \"KAFKA_PASSWORD_ID\", \"maxInFlightRequestsPerConnection\": 5, \"sslEndpointIdentificationAlgorithm\": \"https\"}"
}
]
}
, где METRICS_TOPIC_NAME - это имя topic Apache Kafka для записи метрик (topic создается с помощью UI Abyss),
KAFKA_PASSWORD_ID - идентификатор пароля, от сертификатов Apache Kafka.
Подробнее о создании/получении/редактировании паролей смотрите в документации API /configuration/identifiable-entity/password/.
KAFKA_ADDRESS_AND_PORT - список bootstrap серверов Apache Kafka Abyss (эта информация должна быть известна Администраторам PVM).
Сбор логов: настройка FluentBit агента#
Логи приложений записываются в файл в формате JSON и в лог в обычном формате.
На файлы логов подписан FluentBit sidecar, который отправляет логи дальше по pipeline.
Конфигурация FluentBit, носит информативный характер:
[SERVICE]
Flush 1
Daemon Off
Parsers_File /fluent-bit/etc/parsers.conf
HTTP_Server On
HTTP_Listen 0.0.0.0
HTTP_PORT 8085
[INPUT]
Name tail
Tag file.tail
Path /fluent-bit/etc/logs/*.json
Mem_Buf_Limit 10MB
Skip_Long_Lines On
Refresh_Interval 2
Rotate_Wait 1
Read_from_Head Off
DB /fluent-bit/etc/logs/kube.db
Parser custom
[OUTPUT]
Name stdout
Match *
[OUTPUT]
Name http
Match file.tail
Host telemetry-collector-push-service
Port 8083
URI push/project/{projectName}/pipeline/{pipelineName}
Format json
, где OUTPUT - это настройка вывода логов до Apache Kafka через единый коллектор, {projectName} - имя проекта, используемого для сбора данных, {pipelineName} - имя pipeline.
Конфигурация pipeline для импорта:
Pipeline для обработки всех логов
{
"quota": {
"limitTrafficPerMin": 10000
},
"name": "PIPELINE_NAME",
"input": {
"typeName": "standard-http-api",
"config": "{}"
},
"processors": [
{
"typeName": "http-jackson-converter",
"config": "{\"required\": false, \"headersToEnrich\": []}",
"order": 1
},
{
"typeName": "pipeline-data-enrichment-processor",
"config": "{}",
"order": 2
},
{
"typeName": "json-flattener-processor",
"config": "{\"flattenMode\": \"KEEP_ARRAYS\", \"standardFlatteningForFieldsWithDots\": false}",
"order": 3
}
],
"outputs": [
{
"typeName": "kafka-output",
"config": "{\"acks\": -1, \"topic\": \"LOGS_TOPIC_NAME\", \"clientId\": \"cid-3\", \"lingerMs\": 0, \"batchSize\": 16384, \"maxBlockMs\": 60000, \"keySerializer\": \"org.apache.kafka.common.serialization.StringSerializer\", \"sslClientAuth\": false, \"requestTimeout\": 30000, \"deliveryTimeout\": 120000, \"valueSerializer\": \"org.springframework.kafka.support.serializer.JsonSerializer\", \"bootstrapServers\": \"KAFKA_ADDRESS_AND_PORT\", \"securityProtocol\": \"SSL\", \"idempotenceEnabled\": true, \"sslKeystoreKeyPass\": \"KAFKA_PASSWORD_ID\", \"sslEnabledProtocols\": \"TLSv1.2\", \"sslKeystoreLocation\": \"/certificates/kafka.jks\", \"sslKeystorePassword\": \"KAFKA_PASSWORD_ID\", \"sslTruststoreLocation\": \"/certificates/kafka.jks\", \"sslTruststorePassword\": \"KAFKA_PASSWORD_ID\", \"maxInFlightRequestsPerConnection\": 5, \"sslEndpointIdentificationAlgorithm\": \"https\"}"
}
]
}
, где LOGS_TOPIC_NAME - это имя topic Apache Kafka для записи логов (topic создается с помощью UI Abyss),
KAFKA_PASSWORD_ID - идентификатор пароля, от сертификатов Apache Kafka,
KAFKA_ADDRESS_AND_PORT - список bootstrap серверов Apache Kafka Abyss (эта информация должна быть известна Администраторам PVM).
Сбор траcсировок#
Конфигурирование приложения (источника телеметрии)#
Сбор данных происходит с помощью Spring Zipkin. Трассировки пишутся для всех приложений сервиса: pull/push collector, management application.
Конфигурация:
spring.zipkin.enabled: true
spring.zipkin.base-url: http://{host}:{port}/push/project/{projectName}/pipeline/{pipelineName}
spring.zipkin.api-path: /
spring.zipkin.sender.type: WEB
, где {projectName} - имя проекта, используемого для сбора данных, {pipelineName} - имя pipeline.
Конфигурация pipeline для импорта:
{
"quota": {
"limitTrafficPerMin": 10000
},
"name": "PIPELINE_NAME",
"input": {
"typeName": "standard-http-api",
"config": "{}"
},
"processors": [
{
"typeName": "http-jackson-converter",
"config": "{\"required\": false, \"headersToEnrich\": []}",
"order": 1
},
{
"typeName": "pipeline-data-enrichment-processor",
"config": "{}",
"order": 2
},
{
"typeName": "json-flattener-processor",
"config": "{\"flattenMode\": \"KEEP_ARRAYS\", \"standardFlatteningForFieldsWithDots\": false}",
"order": 3
}
],
"outputs": [
{
"typeName": "kafka-output",
"config": "{\"acks\": -1, \"topic\": \"TRACE_TOPIC_NAME\", \"clientId\": \"cid-3\", \"lingerMs\": 0, \"batchSize\": 16384, \"maxBlockMs\": 60000, \"keySerializer\": \"org.apache.kafka.common.serialization.StringSerializer\", \"sslClientAuth\": false, \"requestTimeout\": 30000, \"deliveryTimeout\": 120000, \"valueSerializer\": \"org.springframework.kafka.support.serializer.JsonSerializer\", \"bootstrapServers\": \"KAFKA_ADDRESS_AND_PORT\", \"securityProtocol\": \"SSL\", \"idempotenceEnabled\": true, \"sslKeystoreKeyPass\": \"KAFKA_PASSWORD_ID\", \"sslEnabledProtocols\": \"TLSv1.2\", \"sslKeystoreLocation\": \"/certificates/kafka.jks\", \"sslKeystorePassword\": \"KAFKA_PASSWORD_ID\", \"sslTruststoreLocation\": \"/certificates/kafka.jks\", \"sslTruststorePassword\": \"KAFKA_PASSWORD_ID\", \"maxInFlightRequestsPerConnection\": 5, \"sslEndpointIdentificationAlgorithm\": \"https\"}"
}
]
}
, где TRACE_TOPIC_NAME - это имя topic Apache Kafka для записи трассировок(topic создается с помощью UI Abyss),
KAFKA_PASSWORD_ID - идентификатор пароля, от сертификатов Apache Kafka,
KAFKA_ADDRESS_AND_PORT - список bootstrap серверов Apache Kafka Abyss (эта информация должна быть известна Администраторам PVM).
Настройка FluentBit агента для сбора трассировок#
Пример конфигурации FluentBit для отправки трейсов из системы распределенной трассировки Zipkin в FluentBit:
apiVersion: v1
kind: ConfigMap
metadata:
name: volume-conf-fluent-bit-sidecar
data:
fluent-bit.conf: |-
[SERVICE]
Flush 1
Daemon Off
Parsers_File /fluent-bit/etc/parsers.conf
HTTP_Server On
HTTP_Listen 0.0.0.0
HTTP_PORT ${fluentbit_monitoring_port_number}
[INPUT]
Name http
Tag api_v2_spans
Port ${spans_port_number}
Buffer_max_size ${buffer_max_size}
Buffer_chunk_size ${buffer_chunk_size}
[FILTER]
Name nest
Match *
Operation lift
Nested_under tags
Add_prefix tag_
[FILTER]
Name nest
Match *
Operation lift
Nested_under localEndpoint
Add_prefix localEndpoint_
[FILTER]
Name nest
Match *
Operation lift
Nested_under remoteEndpoint
Add_prefix remoteEndpoint_
[OUTPUT]
Name stdout
Match *
[OUTPUT]
Name http
Match file.tail
Host telemetry-collector-push-service
Port 8083
URI push/project/{projectName}/pipeline/{pipelineName}
Format json
parsers.conf: |-
[PARSER]
Name custom
Format json
, где {projectName} - имя проекта, используемого для сбора данных, {pipelineName} - имя pipeline.
Здесь в секции [INPUT] для плагина HTTP, тег api_v2_spans такой же, какой динамически устанавливается путем добавления в конец URL-адреса запроса. Затем этот тег используется для маршрутизации события через систему. Если вы не установите этот тег, http.0 будет использоваться автоматически. Если у вас несколько [INPUT]'ов HTTP, они будут следовать шаблону http.N, где N - целое число, представляющее [INPUT].
Для приложений на базе spring-boot c использованием стартера spring-cloud-starter-zipkin в файле application.properties/yaml установить следующие настройки:
1. spring.zipkin.base-url=http://localhost:${spans_port_number}
2. spring.zipkin.encoder=json_v2
Первый параметр - базовый URL для отправки трассировок Zipkin. Возможна отправка через FluentBit, в этом случае необходимо убедиться, что откидываемые приложением метрики (трассировки) направляются в выставленный FluentBit endpoint без gzip-компрессии;
Второй параметр выставит кодировку спанов в соответстующий формат json_v2.
spring.zipkin.compression.enabled=false (дефолтное значение)
Конфигурация pipeline для импорта:
{
"quota": {
"limitTrafficPerMin": 10000
},
"name": "self-tracing-pipe",
"input": {
"typeName": "standard-http-api",
"config": "{}"
},
"processors": [
{
"typeName": "http-jackson-converter",
"config": "{\"required\": false, \"headersToEnrich\": []}",
"order": 1
},
{
"typeName": "pipeline-data-enrichment-processor",
"config": "{}",
"order": 2
},
{
"typeName": "json-flattener-processor",
"config": "{\"flattenMode\": \"KEEP_ARRAYS\", \"standardFlatteningForFieldsWithDots\": false}",
"order": 3
}
],
"outputs": [
{
"typeName": "kafka-output",
"config": "{\"acks\": -1, \"topic\": \"TRACE_TOPIC_NAME\", \"clientId\": \"cid-3\", \"lingerMs\": 0, \"batchSize\": 16384, \"maxBlockMs\": 60000, \"keySerializer\": \"org.apache.kafka.common.serialization.StringSerializer\", \"sslClientAuth\": false, \"requestTimeout\": 30000, \"deliveryTimeout\": 120000, \"valueSerializer\": \"org.springframework.kafka.support.serializer.JsonSerializer\", \"bootstrapServers\": \"KAFKA_ADDRESS_AND_PORT\", \"securityProtocol\": \"SSL\", \"idempotenceEnabled\": true, \"sslKeystoreKeyPass\": \"KAFKA_PASSWORD_ID\", \"sslEnabledProtocols\": \"TLSv1.2\", \"sslKeystoreLocation\": \"/certificates/kafka.jks\", \"sslKeystorePassword\": \"KAFKA_PASSWORD_ID\", \"sslTruststoreLocation\": \"/certificates/kafka.jks\", \"sslTruststorePassword\": \"KAFKA_PASSWORD_ID\", \"maxInFlightRequestsPerConnection\": 5, \"sslEndpointIdentificationAlgorithm\": \"https\"}"
}
]
}
Миграция на текущую версию#
Не применимо: для миграции на текущую версию дополнительные настройки по подключению к Единому коллектору не требуются, т.к. это первая версия Единого коллектора.
Быстрый старт#
Быстрый старт для клиентов сервиса представлен в документации Indicator, в разделе, посвященному UI Единого коллектора. В качестве быстрого старта также может рассматриваться раздел «Настройка обслуживания сервиса».
Использование программного компонента#
Единый коллектор предназначен для сбора данных телеметрии (включая поддержку существующих механизмов сбора, реализованных в компонентах Business activity monitoring (BAMN), Dashboard состояния сервисов (DSST), Объединенный мониторинг Unimon (MONA), Журналирование (LOGA), входящих в состав продукта Platform V Monitor, которые затем могут быть визуализированы. Типы данных, которые собирает Единый коллектор:
метрики, отражающие информацию о работе приложений;
метрики для контроля бизнес-показателей, отражающие активность и опыт конечного пользователя или конечной точки подключения;
трейсы и логи, формируемые в результате работы приложения.
Часто встречающиеся проблемы и пути их разрешения#
Не отображаются Prometheus метрики в Grafana#
Проверить работоспособность Grafana. Например, выбрать больший временной период отображения метрик или зайти на другие дашборды. Если на дашбордах есть сообщения об ошибках (обычно в правом верхнем углу), это говорит о проблемах с Grafana. Если метрики или графики за любой период отображаются, Grafana доступна;
Убедиться, что pipeline, настроенный в едином коллекторе, обеспечивает сбор метрик от приложения. Данную информацию необходимо уточнить у сотрудников, имеющих в Grafana доступ к разделу со списком задач сбора данных телеметрии, в рамках рассматриваемого проекта;
Проверить, что в Service вашего приложения указаны аннотации Prometheus;
Проверить работоспособность Prometheus-agent по логам. Необходимо убедиться в отсутствии сообщений об ошибках в POD Prometheus-agent.
Не отображаются логи и трассировки#
Проверить работоспособность средства отображения логов и трассировок;
Убедиться, что pipeline, настроенный в едином коллекторе, обеспечивает сбор логов/трассировок от приложения.
Остальные шаги выполняются при наличии доступов в Kafka и хранилище Abyss#
Проверить метрики нужного приложения в topic;
Проверить метрики нужного приложения в хранилище Abyss (работоспособность перекладчика Kafka → хранилище Abyss). С подробной информацию можно ознакомиться в документе «Руководство оператора» Abyss.