Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Мониторинг метрик JVM с помощью ClickStack

View as MarkdownEdit this pageReport an issueSet up docs MCP

Интеграция с существующим JVM-приложением

В этом разделе описано, как настроить существующее JVM-приложение для отправки метрик в ClickStack с помощью Java-агента OpenTelemetry.

Если вы хотите протестировать интеграцию перед настройкой окружения в продакшн, можно использовать наш демо-набор данных в разделе о демо-наборе данных.

Предварительные требования
  • Запущенный экземпляр ClickStack
  • Имеющееся Java-приложение (Java 8+)
  • Возможность изменить аргументы запуска JVM

Получите ключ API ClickStack

Java-агент OpenTelemetry отправляет данные в конечную точку OTLP ClickStack, для которой требуется аутентификация.

  1. Откройте HyperDX по URL-адресу ClickStack (например, http://localhost:8080)
  2. При необходимости зарегистрируйтесь или войдите в систему
  3. Перейдите в Team Settings → API Keys
  4. Скопируйте свой ключ API для приёма данных
Ключ API ClickStack

Скачайте Java-агент OpenTelemetry

Скачайте JAR-файл Java-агента OpenTelemetry:

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar

Эта команда скачает агент в текущий каталог. Вы можете разместить его там, где это удобно для вашего развертывания (например, в /opt/opentelemetry/ или рядом с JAR-файлом вашего приложения).

Настройте аргументы запуска JVM

Добавьте Java-агент в команду запуска JVM. Агент автоматически собирает метрики JVM и отправляет их в ClickStack.

Вариант 1: Флаги командной строки
java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=my-java-app \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.headers="authorization=YOUR_API_KEY" \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=none \
  -Dotel.traces.exporter=none \
  -jar my-application.jar

Замените следующее:

  • opentelemetry-javaagent.jar → Полный путь к JAR-файлу агента (например, /opt/opentelemetry/opentelemetry-javaagent.jar)
  • my-java-app → Понятное имя вашего сервиса (например, payment-service, user-api)
  • YOUR_API_KEY → Ваш ключ API ClickStack из предыдущей команды
  • my-application.jar → Имя JAR-файла вашего приложения
  • http://localhost:4318 → Ваша конечная точка ClickStack (используйте localhost:4318, если ClickStack работает на той же машине, в противном случае — http://your-clickstack-host:4318)
Вариант 2: Переменные окружения

Либо используйте переменные окружения:

export JAVA_TOOL_OPTIONS="-javaagent:opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="my-java-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=YOUR_API_KEY"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="none"
export OTEL_TRACES_EXPORTER="none"

java -jar my-application.jar

Замените следующее:

  • opentelemetry-javaagent.jar → Полный путь к JAR-файлу агента
  • my-java-app → Имя вашего сервиса
  • YOUR_API_KEY → Ваш ключ API ClickStack
  • http://localhost:4318 → Ваша конечная точка ClickStack
  • my-application.jar → Имя JAR-файла вашего приложения

Проверьте метрики в HyperDX

Когда приложение будет запущено с агентом, убедитесь, что метрики поступают в ClickStack:

  1. Откройте HyperDX по адресу http://localhost:8080 (или по URL-адресу ClickStack)
  2. Перейдите в Chart Explorer
  3. Найдите метрики, начинающиеся с jvm. (например, jvm.memory.used, jvm.gc.duration, jvm.thread.count)

Демо-набор данных

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

Скачайте демо-набор данных

# Скачайте метрики gauge (memory, threads, CPU, classes)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-gauge.jsonl

# Скачайте метрики sum (GC events)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-sum.jsonl

Датасет содержит 24 часа метрик JVM, включая:

  • рост памяти кучи с периодическими событиями сборки мусора
  • изменения числа потоков
  • реалистичные паузы GC
  • активность загрузки классов
  • характер использования CPU

Запустите ClickStack

Если ClickStack у вас ещё не запущен:

docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Подождите немного, пока ClickStack полностью запустится.

Импортируйте демо-набор данных

# Импортируйте метрики gauge (memory, threads, CPU, classes)
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_gauge FORMAT JSONEachRow
" < jvm-metrics-gauge.jsonl

# Импортируйте метрики sum (GC events)
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_sum FORMAT JSONEachRow
" < jvm-metrics-sum.jsonl

Это импортирует метрики напрямую в таблицы метрик ClickStack.

Проверьте демо-данные

После импорта:

  1. Откройте HyperDX по адресу http://localhost:8080 и войдите в систему (при необходимости создайте учётную запись)
  2. Перейдите в представление Search и выберите для source значение Metrics
  3. Установите временной диапазон 2025-12-06 14:00:00 - 2025-12-09 14:00:00
  4. Выполните поиск по jvm.memory.used или jvm.gc.duration

Вы должны увидеть метрики для демо-сервиса.

Дашборды и визуализация

Чтобы упростить мониторинг JVM-приложений в ClickStack, мы предоставляем преднастроенный дашборд с основными визуализациями для метрик JVM.

Скачайте конфигурацию дашборда

Скачайте файл конфигурации дашборда.

Импортируйте преднастроенный дашборд

  1. Откройте HyperDX и перейдите в раздел Dashboards
  2. Нажмите Import Dashboard в правом верхнем углу в меню с многоточием
Кнопка импорта дашборда
  1. Загрузите файл jvm-metrics-dashboard.json и нажмите Finish Import
Завершение импорта

Просмотрите дашборд

Дашборд будет создан со всеми преднастроенными визуализациями:

Дашборд Kafka Metrics

Устранение неполадок

Агент не запускается

Убедитесь, что JAR-файл агента существует:

ls -lh /path/to/opentelemetry-javaagent.jar

Проверьте, совместима ли версия Java (требуется Java 8+):

java -version

Найдите в логе сообщение о запуске agent: При запуске приложения вы должны увидеть:

[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started

В HyperDX не отображаются метрики

Убедитесь, что ClickStack запущен и доступен:

docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics

Убедитесь, что экспортёр метрик настроен:

# Если используются переменные окружения, проверьте:
echo $OTEL_METRICS_EXPORTER
# Ожидаемый вывод: otlp

Проверьте журналы приложения на наличие ошибок OpenTelemetry: Поищите в журналах приложения сообщения об ошибках, связанных с OpenTelemetry или ошибками экспорта OTLP.

Проверьте сетевую доступность: Если ClickStack размещён на удалённом хосте, убедитесь, что порт 4318 доступен с сервера приложения.

Проверьте версию агента: Убедитесь, что вы используете последнюю стабильную версию агента (на данный момент 2.22.0), так как в новых версиях часто входят улучшения производительности.

Следующие шаги

  • Настройте оповещения для критически важных метрик, таких как высокое потребление памяти кучи, частые паузы GC или исчерпание потоков
  • Изучите другие интеграции ClickStack, чтобы объединить данные обсервабилити

Переход в продакшн

В этом руководстве показано, как настроить Java-агент OpenTelemetry для локального тестирования. Для развертываний в продакшн включайте JAR-файл агента в образы контейнеров и настраивайте его через переменные окружения — так им проще управлять. В более крупных средах с большим количеством экземпляров JVM разверните централизованный OpenTelemetry Collector, чтобы формировать батчи метрик и пересылать их из нескольких приложений, а не отправлять напрямую в ClickStack.

См. Приём данных с OpenTelemetry, чтобы ознакомиться с паттернами развертывания для продакшн и примерами конфигурации коллектора.

Navigation