diff --git a/agent_installation_guide/APM/go.md b/agent_installation_guide/APM/go.md index 8e5c3ec..a9a80cf 100644 --- a/agent_installation_guide/APM/go.md +++ b/agent_installation_guide/APM/go.md @@ -2,75 +2,314 @@ Для интеграции APM-агента в Go-приложение выполните следующие шаги: +Вы получили архив `go-agent-offline.tar.gz`. -### 1. **Загрузка и установка агента** +### 0\. Предварительные требования -Установите пакет агента с помощью команды `go get`: +* **Go 1.24+** установлен. Проверьте: + + ``` + go version + # go version go1.24.1 linux/amd64 + ``` + + ``` + sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz + export PATH=/usr/local/go/bin:$PATH + echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.bashrc + go version + ``` + +* Сетевой доступ от сервера до коллектора GMONIT по порту **443 (HTTPS)**. Проверьте: + + ``` + curl -sk https://gmonit-collector.<>/health + ``` + + `ok`. + -```bash -go get github.com/newrelic/go-agent/v3/newrelic +### 1\. Распаковка + +Перенесите архив на целевой сервер (SCP/SFTP): + +``` +tar -xzf go-agent-offline.tar.gz +cd go-agent-bundle +``` + +### Вариант А: Использование готового бинарника + +Если в архиве есть скомпилированный бинарник `go-apm-test`: + +``` +chmod +x go-apm-test +./go-apm-test ``` +> **Примечание:** Бинарник уже содержит все зависимости и не требует Go на целевом сервере. Однако адрес коллектора и имя приложения **зашиты в бинарник при сборке** и не могут быть изменены без пересборки. -### 2. **Импорт пакета в приложение** +### Вариант Б: Сборка из исходников (с vendor) -Добавьте следующий импорт в код вашего приложения: +Если нужно изменить конфигурацию (адрес коллектора, имя приложения): + +**2\. Настройка конфигурации** + +Откройте `src/main.go` и измените: + +``` +// Имя приложения (отображается в UI GMONIT) +newrelic.ConfigAppName("My-Go-App"), + +// Адрес коллектора GMONIT +func(cfg *newrelic.Config) { + cfg.Host = "gmonit-collector.<>" +}, +``` + +Замените `<>` на актуальный домен коллектора и `My-Go-App` на имя вашего приложения. + +**3\. Сборка** + +``` +cd src +CGO_ENABLED=0 go build -mod=vendor -o go-apm-test . +``` + +> **Важно:** Флаг `-mod=vendor` указывает Go использовать локальную директорию `vendor/` вместо загрузки из интернета. + +**4\. Запуск** + +``` +./go-apm-test +``` + +Для запуска в фоне: + +``` +nohup ./go-apm-test > app.log 2>&1 & +``` + +### 5\. Проверка + +**Проверка приложения:** + +``` +curl http://localhost:8085/ +# Hello from Go APM Test App! + +curl http://localhost:8085/api/data +# {"framework":"net/http","language":"go",...} +``` + +**Проверка агента (в stdout/логах):** + +``` +grep -i "gmonit\|connected" app.log +``` + +**Критерии успеха:** + +1. В логах есть `application connected`. +2. В логах есть `~~~~ GMonit APM ~~~~`. +3. Нет ошибок SSL или соединения с коллектором. + +Ожидаемый вывод: + +``` +{"level":"info","msg":"application connected","context":{"app":"My-Go-App","run":"..."}} +{"level":"info","msg":"collector message","context":{"msg":"~~~~ GMonit APM ~~~~"}} +``` + +**Типичные ошибки и решения:** + +| Ошибка в логах | Причина | Решение | +| --- | --- | --- | +| `cannot find package` / `go: module lookup disabled` | Нет `vendor/` или не указан `-mod=vendor` | Собирать с флагом `-mod=vendor` | +| `ConnectException: Connection refused` | Нет сетевого доступа до коллектора (порт 443) | Проверить firewall: `curl -sk https://gmonit-collector.<>/health` | +| `x509: certificate signed by unknown authority` | Самоподписанный сертификат коллектора | Добавить CA в системное хранилище или настроить `cfg.Transport` | +| `go version go1.22...` + ошибки компиляции | Go < 1.24 | Обновить Go до 1.24+: `sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz` | +| `ConfigHost is not defined` | Попытка использовать несуществующую функцию | Использовать `func(cfg *newrelic.Config) { cfg.Host = "..." }` | +| `cannot use log.Default() as io.Writer` | `ConfigInfoLogger` ожидает `io.Writer` | Использовать `os.Stdout` или `os.Stderr` | +| Docker: `x509: certificate signed by unknown authority` | Alpine без ca-certificates | Добавить `RUN apk add --no-cache ca-certificates` в Dockerfile | + +* * * + +## Часть 3: Инструментация существующего приложения + +Если у вас уже есть Go-приложение и нужно добавить мониторинг GMONIT: + +### 1\. Добавление зависимости (на машине с интернетом) -```go -import "github.com/newrelic/go-agent/v3/newrelic" ``` +go get github.com/newrelic/go-agent/v3/newrelic +go mod vendor +``` + +### 2\. Импорт пакета +В файле с `main()` добавьте: -### 3. **Инициализация агента** +``` +import "github.com/newrelic/go-agent/v3/newrelic" +``` -Инициализируйте агент в функции `main()` или в блоке `init()` вашего приложения: +### 3\. Инициализация агента -```go +В начале `main()`: + +``` app, err := newrelic.NewApplication( - newrelic.ConfigAppName("MY_AWESOME_APP"), // название вашего приложения - newrelic.ConfigLicense("0123456789-123456789-123456789-123456789"), // заглушка, не изменять - newrelic.ConfigHost("gmonit-collector..ru"), // адрес коллектора GMONIT + newrelic.ConfigAppName("My-App-Name"), + newrelic.ConfigLicense("0123456789012345678901234567890123456789"), + func(cfg *newrelic.Config) { + cfg.Host = "gmonit-collector.<>" + }, ) - if err != nil { log.Fatal(err) } ``` +### 4\. Инструментация HTTP-хендлеров -### 4. **Инструментация транзакций** +Замените: + +``` +http.HandleFunc("/path", myHandler) +``` -Используйте метод `newrelic.WrapHandleFunc` для автоматической инструментализации HTTP-хендлеров: +На: -```go -http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler)) ``` +http.HandleFunc(newrelic.WrapHandleFunc(app, "/path", myHandler)) +``` + +### 5\. Инструментация произвольных операций -Для других транзакций используйте ручную инструментализацию: +Для отслеживания не-HTTP операций (фоновые задачи, вызовы БД и т.д.): -```go -txn := app.StartTransaction("название транзакции") +``` +txn := app.StartTransaction("my-operation") defer txn.End() +// ... ваш код ... +``` + +### 6\. Вендоринг и пересборка + +``` +go mod tidy +go mod vendor +CGO_ENABLED=0 go build -mod=vendor -o myapp . ``` +* * * + +## Часть 4: Docker + +### Вариант А: Загрузка готового образа + +Если в архиве есть готовый Docker-образ (`go-apm.tar`): + +``` +docker load -i go-apm.tar +docker run -d --name go-apm-app -p 8085:8085 --restart unless-stopped go-apm:latest +``` -### 5. **Компиляция и запуск приложения** +### Вариант Б: Сборка из vendor-исходников -Соберите и запустите ваше Go-приложение: +Загрузите базовые образы (если нет): -```bash -go build -o myapp ./... -./myapp ``` +docker load -i golang-1.24.tar +docker load -i alpine-3.20.tar +``` + +1. Скорректируйте `main.go` (host, app\_name) как описано в Части 2, шаг 2. + +2. Соберите и запустите: + + ``` + cd src + docker compose build + docker compose up -d + ``` + +3. Проверьте: + + ``` + curl http://localhost:8085/ + # Hello from Go APM Test App! + + docker compose logs | grep -i "gmonit\|connected" + ``` + + +Ожидаемый вывод: + +``` +{"level":"info","msg":"application connected","context":{"app":"My-Go-App",...}} +{"level":"info","msg":"collector message","context":{"msg":"~~~~ GMonit APM ~~~~"}} +``` + +1. Остановка: + + ``` + docker compose down + ``` + + +> **Важно:**`ca-certificates` обязателен в runtime-образе (Alpine) — без него TLS-подключение к коллектору GMONIT не установится. +> +> **Важно:**`CGO_ENABLED=0` — обязательно для сборки статического бинарника, который будет работать в Alpine. + +* * * + +## Часть 5: Контрольный чек-лист + +| Шаг | Действие | Проверка | +| --- | --- | --- | +| 1 | Распаковать архив | `ls src/vendor/` — зависимости на месте | +| 2 | Установить Go 1.24+ (если нужно) | `go version` | +| 3 | Настроить `main.go` (host, app\_name) | `grep cfg.Host src/main.go` | +| 4 | Собрать бинарник | `go build -mod=vendor -o go-apm-test .` | +| 5 | Запустить приложение | `curl http://localhost:8085/` | +| 6 | Проверить подключение к коллектору | `grep "GMonit APM" app.log` | +| 7 | Проверить приложение в UI GMONIT | UI → APM → приложение | + +* * * + +## Часть 6: Отчёт о валидации + +### Среда тестирования + +| Параметр | Значение | +| --- | --- | +| Сервер | Yandex Cloud VM (158.160.94.195), 8 CPU, 16 GB RAM | +| ОС | Ubuntu 24.04 LTS | +| Go | 1.24.1 | +| APM-агент | go-agent/v3 v3.42.0 | +| Коллектор | collector.demo.gmonit.ru (GMONIT v4-6227) | +| Docker | 29.1.2 | +| Docker Compose | v5.0.0 | +### Результаты -### 6. **Проверка работы агента** +| Сценарий | Статус | Имя приложения | Примечания | +| --- | --- | --- | --- | +| Bare-metal | OK | Go-NetHTTP-Test | `application connected`, `~~~~ GMonit APM ~~~~` | +| Docker | OK | Go-NetHTTP-Test | `application connected`, `~~~~ GMonit APM ~~~~` | -После запуска приложения убедитесь, что агент успешно подключился: -- Проверьте логи вашего приложения на наличие сообщений о подключении агента. -- В интерфейсе мониторинга GMONIT появятся метрики вашего приложения. +### Найденные проблемы и решения +| Проблема | Описание | Решение | +| --- | --- | --- | +| Go 1.22 не поддерживается | go-agent v3.42.0 требует Go >= 1.24 | Обновить Go до 1.24+ | +| `newrelic.ConfigHost()` не существует | В документации GMONIT указан `ConfigHost`, но такой функции нет в API | Использовать `func(cfg *newrelic.Config) { cfg.Host = "..." }` | +| `ConfigInfoLogger` принимает `io.Writer` | В документации GMONIT указан `log.Default()`, но `*log.Logger` не реализует `io.Writer` | Использовать `os.Stdout` или `os.Stderr` | +| Docker: нет ca-certificates | Alpine без ca-certificates не может установить TLS-соединение | Добавить `apk add --no-cache ca-certificates` в Dockerfile | +| Docker: `CGO_ENABLED=0` обязателен | Динамический бинарник не работает в Alpine | Собирать с `CGO_ENABLED=0` | -### 7. **Дополнительная информация** +### Вывод -Для дополнительной информации по настройке агента ознакомьтесь с [официальной документацией New Relic](https://docs.newrelic.com/docs/apm/agents/go-agent/installation/install-new-relic-go/). \ No newline at end of file +APM-агент Go (go-agent/v3 v3.42.0) корректно встраивается в приложение и подключается к коллектору GMONIT в обоих сценариях. Ключевые нюансы для оффлайн-установки: зависимости подготавливаются через `go mod vendor` на машине с интернетом, на целевом сервере сборка выполняется с флагом `-mod=vendor`. Требуется Go 1.24+, адрес коллектора задаётся через `cfg.Host` (не через `ConfigHost`), для Docker обязателен пакет `ca-certificates`.