Zabbix 8.0 LTS: nastavení APM s ClickHouse a OpenTelemetry

Přidejte APM k běžícímu Zabbixu 8.0 LTS. Připravte ClickHouse, nastavte zdroj ve frontendu a spusťte příjem tras, metrik a logů přes Zabbix proxy.

Co nás čeká?

V tomto návodu nastavíme APM v běžícím Zabbixu 8.0 LTS. Nainstalujeme ClickHouse pro telemetrii, zapneme sběr na proxy a v Zabbixu si zobrazíme metriky, trasování a logy z aplikace.

Zapojení

OTLP je protokol OpenTelemetry pro přenos metrik, tras a logů z aplikací. Zabbix proxy přijímá OTLP přes gRPC. Pokud aplikace exportuje jen přes HTTP nebo HTTPS, vložíme mezi ni a proxy OpenTelemetry Collector. Ten převezme telemetrii a předá ji proxy přes gRPC.

Tok telemetrie do Zabbixu a ClickHouse OTLP/gRPC Zápis Čtení Aplikace s OTLP/HTTP(S) Export bez gRPC Aplikace s OTLP/gRPC Přímý export OpenTelemetry Collector Předává telemetrii přes gRPC Zabbix proxy Přijímá OTLP/gRPC Zabbix server + frontend APM a dotazy nad telemetrií ClickHouse Databáze otel

ClickHouse v návodu běží na samostatném stroji v privátní síti. Proxy do něj zapisuje telemetrii. Frontend z něj čte data pro obrazovky APM a Zabbix server pro položky Telemetry query. Collector běží vedle proxy na stejném stroji. Hlavní databáze Zabbixu dál slouží pro konfiguraci a běžný monitoring. Na Zabbix serveru a ClickHouse synchronizujte čas.

SpojeníPort a protokol
Aplikace → Collector4318 OTLP/HTTP nebo 8443 OTLP/HTTPS
Collector → proxy4317 OTLP/gRPC na stejném stroji
Aplikace s gRPC → proxy4317 OTLP/gRPC po povolení na proxy
Aktivní proxy → Zabbix server10051 protokol Zabbixu
Proxy, server a frontend → ClickHouse8123 HTTP v privátní síti

Podporované verze

Podle dokumentace ověřené 19. listopadu 2026 podporuje Zabbix 8.0 pro APM ClickHouse od 26.8.17.4 do 26.9.x.x. Před instalací nebo aktualizací ověřte aktuální rozsah. Pro server, frontend, proxy i balík se schématem použijte Zabbix 8.0. Aktuální požadavky Zabbixu 8.0

Výběr operačního systému

Začněte systémem stroje pro ClickHouse. Ukázkové adresy a názvy v příkazech nahraďte svými. Pro instalaci Zabbix serveru použijte náš instalační návod.

Alma/CentOS/RHEL/Rocky 10
Debian 13

Připravte ClickHouse pro telemetrii

Nainstalujte ClickHouse

Příkazy v této větvi spouštějte jako root. Na samostatném stroji pro ClickHouse přidejte oficiální repozitář LTS a vypište dostupnou verzi.

dnf install dnf-plugins-core curl nano
dnf config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo
dnf config-manager --set-disabled clickhouse-stable
dnf config-manager --set-enabled clickhouse-lts
dnf --refresh list --available clickhouse-server clickhouse-client

Následující příkaz spusťte, pokud nabízená verze splňuje aktuální požadavky Zabbixu pro APM. Pokud je mimo rozsah, vyberte pro server i klienta shodnou podporovanou verzi z oficiálních balíčků ClickHouse. Při čisté instalaci přes dnf zůstane účet default bez hesla. Nastavíte ho po ověření verze.

dnf install clickhouse-server clickhouse-client

Nainstalujte balík se schématem Zabbixu

Na stejném stroji s ClickHouse přidejte repozitář Zabbixu 8.0. Balík zabbix-sql-scripts obsahuje skript pro vytvoření tabulek APM.

. /etc/os-release
rpm -Uvh "https://repo.zabbix.com/zabbix/8.0/release/${ID%linux}/${VERSION_ID%%.*}/noarch/zabbix-release-latest.el${VERSION_ID%%.*}.noarch.rpm"
dnf --setopt='epel.excludepkgs=zabbix*' install zabbix-sql-scripts

Nastavte přístup ke ClickHouse

Na stroji s ClickHouse povolte port 8123/TCP pro Zabbix server, frontend a proxy. Příkazy pro firewalld spusťte jako root. Ukázka používá zónu public na privátním síťovém rozhraní.

firewall-cmd --permanent --zone=public --add-port=8123/tcp
firewall-cmd --reload

Po nastavení firewallu vytvořte na stroji s ClickHouse následující soubor.

nano /etc/clickhouse-server/config.d/20-otel-listen.xml
<clickhouse>
    <listen_host>0.0.0.0</listen_host>
</clickhouse>

0.0.0.0 znamená všechna IPv4 rozhraní stroje. Nahrazuje výchozí poslech pouze na místním rozhraní, aby se k databázi mohly připojit i ostatní stroje. Pokud chcete ClickHouse zpřístupnit jen na konkrétní privátní IP, uveďte ji místo 0.0.0.0 a přidejte druhý listen_host s 127.0.0.1 pro místní správu.

Port 9000 používá clickhouse-client pro nativní SQL spojení. Vestavěná webová konzole pro SQL je na http://127.0.0.1:8123/play. Pracuje se stejnými účty a oprávněními jako klient. Parametr access_management dává účtu default právo spravovat uživatele a jejich přístupy přes SQL, například příkazy CREATE USER a GRANT. Tento účet povolíme jen místně. Webová konzole ClickHouse

nano /etc/clickhouse-server/users.d/20-local-admin.xml
<clickhouse>
    <users>
        <default>
            <networks replace="replace">
                <ip>127.0.0.1</ip>
                <ip>::1</ip>
            </networks>
            <access_management>1</access_management>
        </default>
    </users>
</clickhouse>

Spusťte ClickHouse a ověřte verzi. Klient se místně připojí jako default. Pokud už účet heslo má, přidejte do dotazu --ask-password.

systemctl enable clickhouse-server
systemctl restart clickhouse-server
clickhouse-client --host 127.0.0.1 --query 'SELECT version()'

Nastavte heslo účtu default

Pokud účet default ještě nemá heslo, spusťte následující blok v Bashi a zadejte nové heslo.

read -rsp 'Nové heslo účtu default v ClickHouse: ' CH_PASSWORD
printf '\n'
printf '%s' "$CH_PASSWORD" | sha256sum | cut -d ' ' -f 1
unset CH_PASSWORD

Vypsaný otisk si zkopírujte do dočasné poznámky. Potom jako root otevřete konfigurační soubor.

nano /etc/clickhouse-server/users.d/20-local-admin.xml

Nahraďte celý obsah souboru tímto XML. Místo SHA256_HASH vložte zkopírovaný otisk a soubor uložte.

<clickhouse>
    <users>
        <default>
            <networks replace="replace">
                <ip>127.0.0.1</ip>
                <ip>::1</ip>
            </networks>
            <access_management>1</access_management>
            <password remove="1" />
            <password_sha256_hex>SHA256_HASH</password_sha256_hex>
        </default>
    </users>
</clickhouse>

Restartujte ClickHouse. Při tvorbě databáze a dalších výzvách pro účet default použijte nové heslo.

systemctl restart clickhouse-server

Vytvořte databázi a účet pro Zabbix

V Bashi na stroji s ClickHouse vytvořte databázi otel a spusťte skript, který založí tabulky pro metriky, trasy a logy. Volba -t 604800 nastaví uchovávání na sedm dní.

clickhouse-client --host 127.0.0.1 --ask-password \
  --query 'CREATE DATABASE IF NOT EXISTS otel'

read -rsp 'Heslo účtu default v ClickHouse: ' CH_PASSWORD
echo
/usr/share/zabbix/sql-scripts/clickhouse/otel_all.sh \
  -s http://127.0.0.1:8123 -d otel -u default -p "$CH_PASSWORD" -t 604800
unset CH_PASSWORD

Otevřete konzoli ClickHouse. Vytvořte účet otel_zabbix pro zápis z proxy a čtení ze serveru a frontendu. Doplňte nové heslo. Poslední příkaz vypíše tabulky včetně otel_traces a otel_logs.

clickhouse-client --host 127.0.0.1 --ask-password
-- Doplňte vlastní heslo pro Zabbix.
CREATE USER otel_zabbix IDENTIFIED WITH sha256_password BY 'REPLACE_OTEL_PASSWORD';
GRANT SELECT, INSERT ON otel.* TO otel_zabbix;
SHOW TABLES FROM otel;

Nastavte ClickHouse ve frontendu Zabbixu

Otevřete Administration → Data source. V části APM zaškrtněte Enable global data source. Uložením nastavíte společný zdroj pro zápis z proxy, dotazy na Zabbix serveru i zobrazení ve frontendu. Zabbix to uloží do hlavní databáze a server předá nastavení proxy při synchronizaci. Parametr TelemetryProvider v jejich souborech je potřeba pouze pro vlastní připojení dané komponenty.

Pole ve frontenduHodnota
Database typeClickHouse
URLhttp://clickhouse.example.com:8123 s vaším DNS názvem nebo IP
AuthenticationUsername and password
Usernameotel_zabbix
PasswordHeslo, které jste nastavili v ClickHouse
Databaseotel

Klikněte na Test a po úspěšném ověření na Update. Test ověřuje spojení frontendu s ClickHouse a potřebuje rozšíření cURL.

1 Zapněte zdroj · 2 Vyplňte připojení · 3 Klikněte na Test. Poté uložte přes Update.
1 Zapněte zdroj · 2 Vyplňte připojení · 3 Klikněte na Test. Poté uložte přes Update.

Nainstalujte Zabbix proxy s APM

Přejděte na stroj pro Zabbix proxy. Pokud má jiný systém než ClickHouse, nahoře přepněte výběr a vraťte se k instalaci proxy. Přidejte repozitář Zabbixu 8.0.

. /etc/os-release
rpm -Uvh "https://repo.zabbix.com/zabbix/8.0/release/${ID%linux}/${VERSION_ID%%.*}/noarch/zabbix-release-latest.el${VERSION_ID%%.*}.noarch.rpm"

Na EL 10 má proxy s podporou APM samostatný balík s příponou -apm. Pro SQLite použijte zabbix-proxy-sqlite3-apm. Příkazy povolí také CRB a EPEL pro závislosti.

dnf install dnf-plugins-core

. /etc/os-release
if [ "$ID" = rhel ]; then
  subscription-manager repos --enable "codeready-builder-for-rhel-10-$(arch)-rpms"
  dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm
else
  dnf config-manager --set-enabled crb
  dnf install epel-release
fi

dnf --setopt='epel.excludepkgs=zabbix*' install zabbix-proxy-sqlite3-apm nano

Balík podporuje běžný monitoring přes agenty i SNMP. Funguje jako běžná proxy i s vypnutým APM. Sběr OpenTelemetry přidáte nastavením StartAPMCollector=1.

Připravte ClickHouse pro telemetrii

Nainstalujte ClickHouse

Na samostatném stroji pro ClickHouse přidejte oficiální repozitář LTS a vypište dostupnou verzi.

sudo apt update
sudo apt install ca-certificates curl gnupg nano
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/clickhouse.gpg
ARCH=$(dpkg --print-architecture)
printf '%s\n' "deb [arch=$ARCH signed-by=/etc/apt/keyrings/clickhouse.gpg] https://packages.clickhouse.com/deb lts main" \
  | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt update
apt-cache policy clickhouse-server clickhouse-client

Následující příkaz spusťte, pokud nabízená verze splňuje aktuální požadavky Zabbixu pro APM. Pokud je mimo rozsah, vyberte pro server i klienta shodnou podporovanou verzi z oficiálních balíčků ClickHouse. Při interaktivní instalaci přes apt zadejte vlastní heslo, až se zobrazí výzva Set up the password for the default user.

sudo apt install clickhouse-server clickhouse-client

Nainstalujte balík se schématem Zabbixu

Na stejném stroji s ClickHouse přidejte repozitář Zabbixu 8.0. Balík zabbix-sql-scripts obsahuje skript pro vytvoření tabulek APM.

sudo apt update
sudo apt install curl ca-certificates
curl -fLO https://repo.zabbix.com/zabbix/8.0/release/debian/pool/main/z/zabbix-release/zabbix-release_latest_8.0+debian13_all.deb
sudo dpkg -i zabbix-release_latest_8.0+debian13_all.deb
sudo apt update
sudo apt install zabbix-sql-scripts

Nastavte přístup ke ClickHouse

Příkazy pro firewall v návodu předpokládají spuštěný firewalld na příslušném stroji. Pokud na Debianu 13 firewall teprve zavádíte, nainstalujte a spusťte ho takto. Pokud firewall spravujete jiným nástrojem, povolte stejné porty v něm.

sudo apt install firewalld
sudo systemctl enable --now firewalld

Na stroji s ClickHouse povolte port 8123/TCP pro Zabbix server, frontend a proxy. Příkazy pro firewalld spusťte jako root. Ukázka používá zónu public na privátním síťovém rozhraní.

firewall-cmd --permanent --zone=public --add-port=8123/tcp
firewall-cmd --reload

Po nastavení firewallu vytvořte na stroji s ClickHouse následující soubor.

nano /etc/clickhouse-server/config.d/20-otel-listen.xml
<clickhouse>
    <listen_host>0.0.0.0</listen_host>
</clickhouse>

0.0.0.0 znamená všechna IPv4 rozhraní stroje. Nahrazuje výchozí poslech pouze na místním rozhraní, aby se k databázi mohly připojit i ostatní stroje. Pokud chcete ClickHouse zpřístupnit jen na konkrétní privátní IP, uveďte ji místo 0.0.0.0 a přidejte druhý listen_host s 127.0.0.1 pro místní správu.

Port 9000 používá clickhouse-client pro nativní SQL spojení. Vestavěná webová konzole pro SQL je na http://127.0.0.1:8123/play. Pracuje se stejnými účty a oprávněními jako klient. Parametr access_management dává účtu default právo spravovat uživatele a jejich přístupy přes SQL, například příkazy CREATE USER a GRANT. Tento účet povolíme jen místně. Webová konzole ClickHouse

nano /etc/clickhouse-server/users.d/20-local-admin.xml
<clickhouse>
    <users>
        <default>
            <networks replace="replace">
                <ip>127.0.0.1</ip>
                <ip>::1</ip>
            </networks>
            <access_management>1</access_management>
        </default>
    </users>
</clickhouse>

Spusťte ClickHouse a ověřte verzi. Na výzvu zadejte heslo účtu default nastavené při instalaci.

sudo systemctl enable clickhouse-server
sudo systemctl restart clickhouse-server
clickhouse-client --host 127.0.0.1 --ask-password --query 'SELECT version()'
Pokud se instalátor nezeptal na heslo

U čisté instalace bez hesla ověřte verzi bez --ask-password. Pak spusťte následující blok v Bashi a zadejte nové heslo.

read -rsp 'Nové heslo účtu default v ClickHouse: ' CH_PASSWORD
printf '\n'
printf '%s' "$CH_PASSWORD" | sha256sum | cut -d ' ' -f 1
unset CH_PASSWORD

Vypsaný otisk si zkopírujte do dočasné poznámky. Potom jako root otevřete konfigurační soubor.

nano /etc/clickhouse-server/users.d/20-local-admin.xml

Nahraďte celý obsah souboru tímto XML. Místo SHA256_HASH vložte zkopírovaný otisk a soubor uložte.

<clickhouse>
    <users>
        <default>
            <networks replace="replace">
                <ip>127.0.0.1</ip>
                <ip>::1</ip>
            </networks>
            <access_management>1</access_management>
            <password remove="1" />
            <password_sha256_hex>SHA256_HASH</password_sha256_hex>
        </default>
    </users>
</clickhouse>

Restartujte ClickHouse. Při tvorbě databáze a dalších výzvách pro účet default použijte nové heslo.

sudo systemctl restart clickhouse-server

Vytvořte databázi a účet pro Zabbix

V Bashi na stroji s ClickHouse vytvořte databázi otel a spusťte skript, který založí tabulky pro metriky, trasy a logy. Volba -t 604800 nastaví uchovávání na sedm dní.

clickhouse-client --host 127.0.0.1 --ask-password \
  --query 'CREATE DATABASE IF NOT EXISTS otel'

read -rsp 'Heslo účtu default v ClickHouse: ' CH_PASSWORD
echo
/usr/share/zabbix/sql-scripts/clickhouse/otel_all.sh \
  -s http://127.0.0.1:8123 -d otel -u default -p "$CH_PASSWORD" -t 604800
unset CH_PASSWORD

Otevřete konzoli ClickHouse. Vytvořte účet otel_zabbix pro zápis z proxy a čtení ze serveru a frontendu. Doplňte nové heslo. Poslední příkaz vypíše tabulky včetně otel_traces a otel_logs.

clickhouse-client --host 127.0.0.1 --ask-password
-- Doplňte vlastní heslo pro Zabbix.
CREATE USER otel_zabbix IDENTIFIED WITH sha256_password BY 'REPLACE_OTEL_PASSWORD';
GRANT SELECT, INSERT ON otel.* TO otel_zabbix;
SHOW TABLES FROM otel;

Nastavte ClickHouse ve frontendu Zabbixu

Otevřete Administration → Data source. V části APM zaškrtněte Enable global data source. Uložením nastavíte společný zdroj pro zápis z proxy, dotazy na Zabbix serveru i zobrazení ve frontendu. Zabbix to uloží do hlavní databáze a server předá nastavení proxy při synchronizaci. Parametr TelemetryProvider v jejich souborech je potřeba pouze pro vlastní připojení dané komponenty.

Pole ve frontenduHodnota
Database typeClickHouse
URLhttp://clickhouse.example.com:8123 s vaším DNS názvem nebo IP
AuthenticationUsername and password
Usernameotel_zabbix
PasswordHeslo, které jste nastavili v ClickHouse
Databaseotel

Klikněte na Test a po úspěšném ověření na Update. Test ověřuje spojení frontendu s ClickHouse a potřebuje rozšíření cURL.

1 Zapněte zdroj · 2 Vyplňte připojení · 3 Klikněte na Test. Poté uložte přes Update.
1 Zapněte zdroj · 2 Vyplňte připojení · 3 Klikněte na Test. Poté uložte přes Update.

Nainstalujte Zabbix proxy s APM

Přejděte na stroj pro Zabbix proxy. Pokud má jiný systém než ClickHouse, nahoře přepněte výběr a vraťte se k instalaci proxy. Přidejte repozitář Zabbixu 8.0.

sudo apt update
sudo apt install curl ca-certificates
curl -fLO https://repo.zabbix.com/zabbix/8.0/release/debian/pool/main/z/zabbix-release/zabbix-release_latest_8.0+debian13_all.deb
sudo dpkg -i zabbix-release_latest_8.0+debian13_all.deb
sudo apt update

V Debianu 13 obsahuje podporu APM přímo balík zabbix-proxy-sqlite3.

sudo apt install zabbix-proxy-sqlite3 nano

Balík podporuje běžný monitoring přes agenty i SNMP. Funguje jako běžná proxy i s vypnutým APM. Sběr OpenTelemetry přidáte nastavením StartAPMCollector=1.

Spusťte proxy a zapněte sběr APM

V Zabbixu otevřete Administration → Proxies → Create proxy. Zadejte název apm-proxy, režim Active a do Proxy address IP proxy, ze které se připojuje k serveru. Na kartě APM zapněte Data collection enabled a klikněte na Add.

1 Otevřete kartu APM · 2 Zapněte sběr dat · 3 Klikněte na Add.
1 Otevřete kartu APM · 2 Zapněte sběr dat · 3 Klikněte na Add.

Systémové příkazy ve společných krocích spouštějte jako root na stroji uvedeném u daného kroku.

Pro nastavení SQLite upravte pouze parametr DBName v souboru /etc/zabbix/zabbix_proxy.conf. Zadejte úplnou cestu k souboru .sqlite. Proxy při prvním spuštění databázový soubor sama vytvoří a dál ho spravuje.

U běžící proxy zachovejte stávající hodnotu DBName. Pro novou proxy použijte trvalý adresář zapisovatelný uživatelem zabbix. Pokud takový adresář nemáte, vytvořte /var/lib/zabbix příkazem níže.

install -d -o zabbix -g zabbix -m 0750 /var/lib/zabbix

Na stroji s proxy otevřete konfiguraci v Nano. Upravte uvedené klíče na jejich místě a zachovejte ostatní nastavení z balíku. Hodnotu Server nahraďte adresou svého Zabbix serveru. Hostname musí odpovídat názvu proxy z frontendu.

nano /etc/zabbix/zabbix_proxy.conf
# …
Server=zabbix.example.com
Hostname=apm-proxy
DBName=/var/lib/zabbix/zabbix_proxy.sqlite

StartAPMCollector=1
APMListenIP=0.0.0.0
# …

Výchozí hodnota 0.0.0.0 znamená, že proxy přijímá OTLP/gRPC na všech rozhraních IPv4 na portu 4317. Collector na stejném stroji se připojuje na 127.0.0.1:4317. Pokud telemetrii posílá pouze místní Collector, ponechte příchozí 4317/TCP z ostatních strojů ve firewallu zavřený.

Před spuštěním proxy povolte na Zabbix serveru službu zabbix-server (10051/TCP). Pokud jste ji povolili při instalaci serveru, tento blok přeskočte.

firewall-cmd --permanent --zone=public --add-service=zabbix-server

Pro přímý příjem OTLP/gRPC z jiného stroje povolte příchozí 4317/TCP na stroji s proxy. Příkaz povolí port v celé zóně public. Ukázka počítá s privátní sítí odesílatelů.

firewall-cmd --permanent --zone=public --add-port=4317/tcp

Po přidání pravidel načtěte firewall jednou na každém stroji, kde jste pravidla upravili.

firewall-cmd --reload

Ověřte konfiguraci a spusťte službu. V Administration → Proxies zkontrolujte, že se u proxy aktualizuje Last seen (age).

zabbix_proxy -T
systemctl enable zabbix-proxy
systemctl restart zabbix-proxy

Při první synchronizaci Zabbix proxy převezme od serveru povolení sběru APM a globální zdroj. S nastaveným StartAPMCollector=1 pak automaticky spustí příjem OTLP/gRPC na portu 4317.

Připojte aplikaci přes HTTP nebo HTTPS

Aplikace využívající OTLP/HTTP posílá data do OpenTelemetry Collectoru. Ten je předá Zabbix proxy přes OTLP/gRPC. Pokud vaše aplikace posílají telemetrii přímo na proxy přes gRPC, můžete přejít na test gRPC.

Konfigurace Collectoru pouze pro HTTP

Na stroji s proxy uložte nejdřív konfiguraci do /etc/otelcol-contrib/config.yaml. Výchozí konfigurace balíku používá port 4317, který má v tomto návodu Zabbix proxy.

mkdir -p /etc/otelcol-contrib
nano /etc/otelcol-contrib/config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch: {}
exporters:
  otlp_grpc/zabbix:
    endpoint: 127.0.0.1:4317
    tls:
      insecure: true
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc/zabbix]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc/zabbix]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc/zabbix]

Receivers určuje, kde Collector přijímá data. 0.0.0.0:4318 zpřístupní příjem na síťových rozhraních stroje s proxy. Exporters určuje, kam Collector data posílá. 127.0.0.1:4317 je místní gRPC přijímač Zabbix proxy. Pipelines propojí příjem, dávkování a odesílání zvlášť pro trasy, metriky a logy.

Nainstalujte a spusťte Collector

Při přechodu ze staršího kontejneru nejdřív zastavte původní Collector, aby uvolnil port pro službu.

Nainstalujte oficiální balík otelcol-contrib. Obsahuje jednotku systemd. Ukázky jsou pro x86-64. Na ARM64 použijte balík s arm64 místo amd64 v názvu.

Alma/CentOS/RHEL/Rocky 10

dnf install https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.165.0/otelcol-contrib_0.165.0_linux_amd64.rpm

Debian 13. Parametr --force-confold při instalaci zachová konfiguraci vytvořenou výše.

curl -fLO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.165.0/otelcol-contrib_0.165.0_linux_amd64.deb
dpkg --force-confold -i otelcol-contrib_0.165.0_linux_amd64.deb

Na stroji s Collectorem povolte port 4318/TCP pro OTLP přes HTTP.

firewall-cmd --permanent --zone=public --add-port=4318/tcp
firewall-cmd --reload

Zapněte službu otelcol-contrib a nastavte její automatické spouštění při startu systému.

systemctl enable --now otelcol-contrib

Nastavte odesílání telemetrie v aplikaci

Na stroji s aplikací, která odesílá telemetrii, nastavte tyto proměnné v prostředí procesu aplikace s OpenTelemetry SDK. V OTEL_EXPORTER_OTLP_ENDPOINT nahraďte collector.example.com DNS názvem nebo IP adresou stroje s Collectorem. V tomto návodu Collector běží na stroji s proxy.

OTEL_SERVICE_NAME=checkout-demo
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

Konfigurace Collectoru pro HTTP a HTTPS

Na stroji s Collectorem otevřete /etc/otelcol-contrib/config.yaml. Celý příklad níže ponechává HTTP na portu 4318 a přidává HTTPS na portu 8443. Oba přijímače běží současně a posílají trasy, metriky a logy do stejné Zabbix proxy.

nano /etc/otelcol-contrib/config.yaml
receivers:
  otlp/http:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
  otlp/https:
    protocols:
      http:
        endpoint: 0.0.0.0:8443
        tls:
          cert_file: /etc/otelcol-contrib/tls/collector.crt
          key_file: /etc/otelcol-contrib/tls/collector.key
processors:
  batch: {}
exporters:
  otlp_grpc/zabbix:
    endpoint: 127.0.0.1:4317
    tls:
      insecure: true
service:
  pipelines:
    traces:
      receivers: [otlp/http, otlp/https]
      processors: [batch]
      exporters: [otlp_grpc/zabbix]
    metrics:
      receivers: [otlp/http, otlp/https]
      processors: [batch]
      exporters: [otlp_grpc/zabbix]
    logs:
      receivers: [otlp/http, otlp/https]
      processors: [batch]
      exporters: [otlp_grpc/zabbix]

Služba běží jako uživatel otelcol-contrib. Uložte certifikát a klíč do cest uvedených v ukázce a nastavte účtu přístup k oběma souborům. Klíč může vlastnit root:otelcol-contrib s oprávněním 0640.

Pokud má Collector přijímat jen HTTPS, odeberte z konfigurace celý blok přijímače otlp/http a ve všech třech pipelines nastavte receivers: [otlp/https].

Na stroji s Collectorem povolte 8443/TCP.

firewall-cmd --permanent --zone=public --add-port=8443/tcp

Při přechodu na příjem pouze přes HTTPS odeberte pravidlo firewallu pro 4318/TCP, pokud bylo vytvořeno jen pro tento Collector.

Po uložení konfigurace načtěte pravidla firewallu a restartujte Collector.

firewall-cmd --reload
systemctl restart otelcol-contrib

Na stroji s aplikací odesílající telemetrii přes HTTPS nastavte OTEL_EXPORTER_OTLP_ENDPOINT na https://collector.example.com:8443. Protokol je i u HTTPS http/protobuf. Aplikace musí důvěřovat certifikátu Collectoru.

Připojte aplikaci přímo přes gRPC

Pokud aplikace posílá OTLP/gRPC přímo z jiného stroje, použijte jako cíl privátní IP nebo DNS název proxy. Na proxy povolte 4317/TCP jen z adres odesílatelů a nastavte vzájemné TLS (mTLS). Při kombinaci obou cest nastavte v exporteru Collectoru důvěryhodnou CA, klientský certifikát a klíč a použijte adresu odpovídající certifikátu proxy. Parametry TLS pro Zabbix APM

Otestujte příjem telemetrie

  • OTLP/gRPC jde z odesílatele přímo na Zabbix proxy na port 4317.
  • OTLP přes HTTP nebo HTTPS jde z odesílatele na OpenTelemetry Collector na port 4318 nebo 8443. Collector trasu předá na Zabbix proxy přes gRPC.

Vyberte test podle své konfigurace. Pokud posíláte telemetrii přímo na proxy přes gRPC, stačí první test. Pokud posíláte přes Collector, použijte test HTTP nebo HTTPS.

Odešlete testovací trasu přímo přes gRPC

Na stroji, ze kterého test odešlete, nainstalujte jako root balíček otel-cli v0.4.5 podle systému odesílatele v přepínači výše. Příkazy jsou pro Linux na x86-64. Na ARM64 nahraďte v názvu souboru amd64 za arm64.

Alma/CentOS/RHEL/Rocky 10

dnf install https://github.com/equinix-labs/otel-cli/releases/download/v0.4.5/otel-cli_0.4.5_linux_amd64.rpm

Debian 13

curl -fLO https://github.com/equinix-labs/otel-cli/releases/download/v0.4.5/otel-cli_0.4.5_linux_amd64.deb &&
  apt install ./otel-cli_0.4.5_linux_amd64.deb

Spuštění bez systémové instalace. Místo balíčku můžete do adresáře se skriptem rozbalit hotovou binárku. Na ARM64 použijte v názvu archivu linux_arm64.

archive=otel-cli_0.4.5_linux_amd64.tar.gz
curl -fLO "https://github.com/equinix-labs/otel-cli/releases/download/v0.4.5/$archive" &&
  tar -xzf "$archive" otel-cli

Otevřete nový soubor. Pokud používáte rozbalenou binárku, uložte ho vedle ní.

nano test-apm-grpc.sh

Vložte následující obsah a soubor uložte.

#!/usr/bin/env bash
set -euo pipefail

endpoint=${1:?Usage: ./test-apm-grpc.sh PROXY_ENDPOINT [otel-cli options]}
shift
unset TRACEPARENT

PATH="$(dirname -- "$0"):$PATH" otel-cli span \
  --protocol grpc --endpoint "$endpoint" --timeout 5s \
  --service apm-test-grpc --name test-request \
  --fail --verbose --tp-print "$@"
printf '\nService: apm-test-grpc\n'

Nastavte soubor jako spustitelný.

chmod +x test-apm-grpc.sh

Lokální test bez TLS. Spusťte ho přímo na Zabbix proxy, pokud její příjem OTLP/gRPC běží bez TLS.

./test-apm-grpc.sh 127.0.0.1:4317 --insecure

Test s mTLS. Příkaz spusťte na odesílateli. Nahraďte proxy.example.com názvem z certifikátu proxy. Soubor ca.crt slouží k ověření certifikátu proxy. client.crt a client.key jsou certifikát a klíč odesílatele. Podle potřeby upravte cesty k souborům.

./test-apm-grpc.sh proxy.example.com:4317 \
  --tls-ca-cert ca.crt --tls-client-cert client.crt --tls-client-key client.key

Po úspěšném odeslání skript vypíše ID trasy a název služby. Podle trace id můžete v Zabbixu poznat právě odeslanou trasu.

# trace id: 7ba3eae5ce58b4a7b54e077e4e324029
#  span id: 1e205f37114e72b6
TRACEPARENT=00-7ba3eae5ce58b4a7b54e077e4e324029-1e205f37114e72b6-01

Service: apm-test-grpc

Odešlete testovací trasu přes Collector

Na linuxovém stroji, odkud bude telemetrie odcházet, otevřete nový soubor.

nano test-apm-http.sh

Vložte následující obsah a soubor uložte.

#!/usr/bin/env bash
set -euo pipefail

collector_url=${1:?Usage: ./test-apm-http.sh COLLECTOR_URL}
now_ns=$(date +%s%N)
read -r trace_id < /proc/sys/kernel/random/uuid
trace_id=${trace_id//-/}

curl -fsS --max-time 10 \
  -H 'Content-Type: application/json' \
  --data-binary @- "${collector_url%/}/v1/traces" <<JSON
{
  "resourceSpans": [{
    "resource": {
      "attributes": [{"key": "service.name", "value": {"stringValue": "apm-test-http"}}]
    },
    "scopeSpans": [{"spans": [{
      "traceId": "$trace_id",
      "spanId": "0000000000000001",
      "name": "test-request",
      "kind": 2,
      "startTimeUnixNano": "$((now_ns - 10000000))",
      "endTimeUnixNano": "$now_ns"
    }]}]
  }]
}
JSON
printf '\nService: apm-test-http\nTrace ID: %s\n' "$trace_id"

Nastavte spustitelnost skriptu a vyberte příkaz podle nastavení Collectoru. V obou příkladech nahraďte collector.example.com adresou svého Collectoru.

chmod +x test-apm-http.sh

HTTP na portu 4318

./test-apm-http.sh http://collector.example.com:4318

HTTPS na portu 8443. Tento test spusťte, pokud na Collectoru používáte TLS a odesílatel důvěřuje jeho certifikátu.

./test-apm-http.sh https://collector.example.com:8443

Ukázka výstupu po přijetí požadavku Collectorem. Trace ID se při každém spuštění změní.

{"partialSuccess":{}}
Service: apm-test-http
Trace ID: be034f426cd944f9afbb09e198313f93

Ověřte první data v Zabbixu

Otevřete APM → Traces, vyberte posledních 15 minut a vyhledejte službu apm-test-http pro test přes Collector nebo apm-test-grpc pro přímý test proxy. Otevřete nalezenou trasu a porovnejte její Trace ID s výstupem skriptu. Při ověření vlastní aplikace v ní vyvolejte požadavek a hledejte její hodnotu OTEL_SERVICE_NAME. Pokud aplikace posílá i metriky a logy, najdete je v APM → Metrics a APM → Logs. Související logy lze dohledat podle Trace ID, pokud ho aplikace posílá.

① Zkopírujte Trace ID pro vyhledání souvisejících logů.
① Zkopírujte Trace ID pro vyhledání souvisejících logů.

Pokud data chybí, zkontrolujte log proxy. Při příjmu přes Collector zkontrolujte i jeho log. Chyby připojení k ClickHouse ověřte proti URL, účtu a oprávnění v nastavení zdroje.

tail -n 50 /var/log/zabbix/zabbix_proxy.log
journalctl -u otelcol-contrib -n 50 --no-pager

uxMAX pro práci s APM

Pro práci s APM doporučujeme bezplatný modul uxMAX. V Traces, Metrics a Logs si pomocí Save as uložíte vlastní filtry a vybraný časový rozsah pro další použití. Změny uloženého filtru potvrdíte tlačítkem Update. Při nastavování položek Telemetry query vám časová osa názorně ukáže čtené období, rozdělení podle Granularity a případné mezery či překryvy. Instalaci najdete v průvodci na Portálu initMAX. Vyberte svůj operační systém a příkazy spusťte na serveru se Zabbix frontendem.

uxMAX v APM Metrics – uložené záložky filtrů a tlačítko Save as
uxMAX přidává do APM vlastní záložky filtrů. Tlačítkem Save as uložíte podmínky a vybrané časové období.
uxMAX – časová osa Telemetry query s parametry Update interval, Time shift, Lookback limit a Granularity
Časová osa uxMAX u položky Telemetry query propojuje Update interval, Time shift, Lookback limit a Granularity. Jde o ilustraci nastavení. Skutečné období závisí na posledním úspěšném dotazu.

Volitelně přepište globální zdroj v konfiguraci

Tuto část použijte, když komponenta potřebuje vlastní databázi nebo účet. Hodnota ze souboru má přednost před Administration → Data source pouze v komponentě, kde ji nastavíte. Následující bloky vložte do existujících konfigurací se zachováním ostatních parametrů.

Proxy pro zápis telemetrie

Na stroji se Zabbix proxy otevřete jeho konfiguraci.

nano /etc/zabbix/zabbix_proxy.conf
# Doplňte URL, databázi, účet a heslo pro tuto komponentu.
TelemetryProvider=clickhouse;url=http://clickhouse.example.com:8123,db=otel,username=otel_zabbix,password="REPLACE_OTEL_PASSWORD"
zabbix_proxy -T
systemctl restart zabbix-proxy

Server pro dotazy nad telemetrií

Na stroji se Zabbix server otevřete jeho konfiguraci.

nano /etc/zabbix/zabbix_server.conf
# Doplňte URL, databázi, účet a heslo pro tuto komponentu.
TelemetryProvider=clickhouse;url=http://clickhouse.example.com:8123,db=otel,username=otel_zabbix,password="REPLACE_OTEL_PASSWORD"
zabbix_server -T
systemctl restart zabbix-server

Frontend pro zobrazení APM

Na stroji s frontendem přidejte celý blok do existujícího PHP souboru. Ten obsahuje také připojení k hlavní databázi Zabbixu.

nano /etc/zabbix/web/zabbix.conf.php
// Doplňte připojení ke ClickHouse pro frontend.
$TELEMETRY_PROVIDERS[] = [
    'provider' => 'clickhouse',
    'url' => 'http://clickhouse.example.com:8123',
    'db' => 'otel',
    'username' => 'otel_zabbix',
    'password' => 'REPLACE_OTEL_PASSWORD'
];
php -l /etc/zabbix/web/zabbix.conf.php

Úpravu ověřte v APM po znovunačtení stránky. Tlačítko Test u globálního zdroje ověřuje hodnoty zadané do formuláře. Dokumentace ke zdroji telemetrie

Dokumentace Zabbixu k APM · Oficiální balíčky ClickHouse · Konfigurace Collectoru

×Košík

Váš košík je prázdný.