Мониторинг бэкенда в Elastic APM: установка агента, trace ID и проверка

Ниже — практический пример подключения Python-бэкенда к Elastic APM. Тот же порядок подходит и для других языков: сначала проверяем APM endpoint, затем подключаем агент, создаём тестовую транзакцию и убеждаемся, что она появилась в Elasticsearch и Kibana.

1. Проверяем APM endpoint

export ELASTIC_APM_SERVER_URL=https://apm.example.com
curl -vk $ELASTIC_APM_SERVER_URL/

Ответ 200, 401 или 403 означает, что endpoint доступен. Timeout и connection refused указывают на DNS, firewall, proxy или неверный адрес.

2. Создаём тестовое Python-приложение

python3 -m venv /opt/apm-demo-venv
/opt/apm-demo-venv/bin/pip install flask elastic-apm
install -d -m 755 /opt/apm-demo

3. Добавляем приложение

cat > /opt/apm-demo/app.py <<'EOF'
from flask import Flask
from elasticapm.contrib.flask import ElasticAPM
import time

app = Flask(__name__)
app.config['ELASTIC_APM'] = {
    'SERVICE_NAME': 'apm-demo',
    'SERVER_URL': 'https://apm.example.com',
    'SECRET_TOKEN': 'CHANGE_ME',
    'ENVIRONMENT': 'test',
}
apm = ElasticAPM(app)

@app.get('/fast')
def fast():
    return {'status': 'ok'}

@app.get('/slow')
def slow():
    time.sleep(2)
    return {'status': 'slow'}

@app.get('/error')
def error():
    raise RuntimeError('APM test error')

app.run(host='127.0.0.1', port=5000)
EOF

4. Запускаем вручную

/opt/apm-demo-venv/bin/python /opt/apm-demo/app.py

В другом терминале отправьте тестовые запросы:

curl -sS http://127.0.0.1:5000/fast
curl -sS http://127.0.0.1:5000/slow
curl -i http://127.0.0.1:5000/error

5. Создаём systemd unit

cat > /etc/systemd/system/apm-demo.service <<'EOF'
[Unit]
Description=Elastic APM demo backend
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/apm-demo
ExecStart=/opt/apm-demo-venv/bin/python /opt/apm-demo/app.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now apm-demo
systemctl status apm-demo --no-pager
journalctl -u apm-demo -n 100 --no-pager

6. Проверяем данные через Elasticsearch API

curl -sS -u elastic:CHANGE_ME \
  'https://es.example.com/traces-apm*/_search?size=5&sort=@timestamp:desc' \
  -H 'Content-Type: application/json' \
  -d '{"query":{"term":{"service.name":"apm-demo"}},"_source":["@timestamp","service.name","transaction.name","transaction.duration.us","trace.id","error.exception.message"]}'

В выдаче должны появиться транзакции GET /fast, GET /slow и ошибка из /error.

7. Ищем trace ID в Kibana

service.name : "apm-demo"
trace.id : "TRACE_ID_FROM_EVENT"
transaction.name : "GET /slow"

Проверьте duration медленного запроса, stack trace ошибки и связанный trace ID.

8. Проверяем корреляцию логов и traces

Приложение должно писать trace.id и transaction.id в структурированные логи. После этого в Kibana можно перейти от медленной транзакции к связанным сообщениям приложения.

9. Диагностика

systemctl status apm-demo --no-pager
journalctl -u apm-demo --since '15 min ago' --no-pager
curl -vk https://apm.example.com/
ss -lntp | grep ':5000'
python3 -c 'import elasticapm; print(elasticapm.VERSION)'

Ошибки 401/403 означают неверный secret token или API key. Отсутствие событий при рабочем endpoint чаще связано с неправильным service name, environment, sampling или сертификатом.

10. Rollback

systemctl disable --now apm-demo
rm -f /etc/systemd/system/apm-demo.service
systemctl daemon-reload
rm -rf /opt/apm-demo /opt/apm-demo-venv

Критерий успеха: сервис запускается без ошибок, три тестовых endpoint создают транзакции, медленный запрос имеет ожидаемую duration, ошибка содержит stack trace, а trace ID находится через Elasticsearch и Kibana.