OpenTelemetry ve SigNoz ile Docker Kullanarak BookStack'i İzleme Yöntemleri - Teknomers | Dünyadan Güncel Teknoloji | Oyun | Müzik | Film

BookStack uygulamasını deploy etmek kolaydı. Ancak, uygulama içindeki süreçleri anlamak zorlayıcıydı. Gelen istekler, veritabanı sorguları veya Laravel işlemleri hakkında görünürlük olmadan, performans sorunlarını çözmek iyice zorlaşıyordu. Bu makalede, BookStack’ı OpenTelemetry ile donatıp, SigNoz’a bağlayarak uygulamanızın gözlemlenebilirliğini artıracaksınız. Tüm bunları, uygulamanın kaynak kodunu değiştirmeden yapacağız.

<p>BookStack, belgeleri oluşturmak ve yönetmek için açık kaynaklı bir platformdur; ancak yerleşik dağıtılmış izleme veya derin uygulama gözlemlenebilirliği sunmamaktadır. Bu rehberde OpenTelemetry ile BookStack'ı entegre edeceğiz ve izleri SigNoz'a aktararak istekleri izleyecek, Laravel uygulama davranışını analiz edecek ve sorunları daha etkili bir şekilde çözebileceksiniz.</p>

<h2>
    <a name="prerequisites" href="#prerequisites"></a>
    Ön Koşullar
</h2>

<p>Başlamadan önce, aşağıdakilere sahip olduğunuzdan emin olun:</p>

<h2>
    <a name="solution-overview" href="#solution-overview"></a>
    Çözüm Genel Bakış
</h2>

<p>BookStack, izleri OpenTelemetry Collector'a aktaran OpenTelemetry ile donatılmıştır. Collector, telemetriyi SigNoz'a iletir; burada istekleri görselleştirip dağıtılmış izleri analiz edebilirsiniz.<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>                HTTP Requests
                  │
                  ▼
           ┌─────────────┐
           │  BookStack  │
           │  (Laravel)  │
           └──────┬──────┘
                  │
      OpenTelemetry SDK
                  │
         OTLP (HTTP:4318)
                  │
                  ▼
    ┌────────────────────────┐
    │ OpenTelemetry Collector│
    │    (SigNoz Collector)  │
    └───────────┬────────────┘
                │
                ▼
          ┌───────────┐
          │  SigNoz   │
          │ Dashboard │
          └───────────┘

<h2>
    <a name="step-1-install-signoz" href="#step-1-install-signoz"></a>
    Adım 1: SigNoz'ı Kurun
</h2>

<p>BookStack'ı entegre etmeden önce, telemetri verilerini toplamak, depolamak ve görselleştirmek için bir backend kurmalısınız. Bu adımda, <code>foundryctl</code> CLI'sini kullanarak SigNoz’ı kuracak ve BookStack'dan izleri almaya hazır olduğunu doğrulayacaksınız.</p>

<ol>
    <li>
        <p>SigNoz'un deploymentını kolaylaştıran Foundry CLI'yi kurun.<br/></p>
        <pre class="highlight shell"><code>curl <span class="nt">-fsSL</span> https://signoz.io/foundry.sh | bash

export PATH=“/root/.local/bin:$PATH“

Contents

Ne Öğrendim
Sonuç

        <p>Kurulumun başarılı olup olmadığını doğrulayın:<br/></p>
        <pre class="highlight shell"><code>foundryctl version

Aşağıdaki yapılandırma ile casting.yaml adında bir dosya oluşturun. Bu dosya, foundryctl‘ye Docker Compose kullanarak SigNoz’u deploy etmesini söyler.

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
deployment:
flavor: compose
mode: docker

Kurulum yapılandırmasını kullanarak SigNoz’u deploy edin.

foundryctl cast -f casting.yaml

        <p>Kurulum, Docker ortamınızı doğrular, gerekli Docker Compose kaynaklarını oluşturur ve SigNoz hizmetlerini başlatır.</p>
    </li>
    <li>
        <p>Deployment'ın başarılı bir şekilde tamamlandığını doğrulayın.<br/></p>
        <pre class="highlight shell"><code>docker ps

        <p><code>signoz-frontend</code>, <code>signoz-query-service</code>, <code>signoz-otel-collector</code> ve <code>clickhouse</code> gibi konteynerlerin görünmesi gerekir.</p>
    </li>
    <li>
        <p><code>http://<server-ip>:8080</code> adresini tarayıcınızda açın. Kurulum başarılı olduysa, SigNoz dashboard'ı yüklenmelidir. <code><server_ip/></code> ile sunucu IP'nizi değiştirmeyi unutmayın.</p>
    </li>
</ol>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>Enter the email and password to create the initial admin account for SigNoz.

<h2>
    <a name="step-2-build-a-custom-bookstack-image" href="#step-2-build-a-custom-bookstack-image"></a>
    Adım 2: Özel BookStack İmajı Oluşturun
</h2>

<p>Resmi LinuxServer BookStack imajı, izleri dışa aktarmak için gerekli OpenTelemetry bileşenlerini içermemektedir. Bu adımda, OpenTelemetry PHP uzantısını ve Laravel otomatik enstrümantasyon paketlerini imaj oluşturulurken yükleyen özel bir imaj oluşturacaksınız. Bu, dağıtımı tekrarlanabilir hale getirecek ve çalışan bir konteynerde değişiklik yapılmasını gereksiz kılacaktır.</p>

<ol>
    <li>
        <p>Dağıtım için bir proje dizini oluşturun ve içine gidin.<br/></p>
        <pre class="highlight shell"><code><span class="nb">mkdir </span>bookstack-otel

cd bookstack-otel

Bir Laravel uygulama anahtarı oluşturun. BookStack, hassas verileri şifrelemek için bu anahtarı kullanır ve bu anahtarı daha sonra Docker Compose yapılandırmanızı oluştururken kullanacaksınız.

echo "base64:$(openssl rand -base64 32)"

        <p>Üretilen değeri kaydedin; BookStack konteyneri yapılandırılırken kullanacaksınız.</p>
    </li>
    <li>
        <p>Aşağıdaki yapılandırmayla <code>Dockerfile</code> adında bir dosya oluşturun.<br/></p>
        <pre class="highlight docker"><code><span class="k">FROM</span><span class="s"> lscr.io/linuxserver/bookstack:version-v26.03.3</span>

COPY scripts/install-opentelemetry.sh /tmp/install-opentelemetry.sh

RUN chmod +x /tmp/install-opentelemetry.sh \
&& /tmp/install-opentelemetry.sh \
&& rm /tmp/install-opentelemetry.sh \
&& rm -rf /root/.composer/cache

WORKDIR /app/www

        <p>Bu Dockerfile, resmi BookStack imajını genişletir ve imaj oluşturulurken yükleme scriptini çalıştırır.</p>
    </li>
    <li>
        <p>Aşağıdaki yükleme scripti ile <code>install-opentelemetry.sh</code> adında bir dosya oluşturun.<br/></p>
        <pre class="highlight shell"><code><span class="c">#!/bin/sh</span>

set -e

echo “==========================================
echo “Installing OpenTelemetry PHP Extension”
echo “==========================================

# Add Alpine edge testing repository if missing
if ! grep -q “edge/testing” /etc/apk/repositories; then
echo “https://dl-cdn.alpinelinux.org/alpine/edge/testing“ >> /etc/apk/repositories
fi

apk update

apk add –no-cache php85-pecl-opentelemetry

echo “==========================================
echo “Installing OpenTelemetry Laravel Packages”
echo “==========================================

cd /app/www

composer config –no-interaction allow-plugins.php-http/discovery false
composer config –no-interaction allow-plugins.tbachert/spi true

composer require \
open-telemetry/sdk \
open-telemetry/exporter-otlp \
open-telemetry/opentelemetry-auto-laravel \
php-http/guzzle7-adapter \
–no-interaction \
–prefer-dist \
–optimize-autoloader \
–no-scripts

echo “==========================================
echo “Verifying installation…”
echo “==========================================

php -m | grep opentelemetry

composer show open-telemetry/sdk
composer show open-telemetry/opentelemetry-auto-laravel

echo “==========================================
echo “OpenTelemetry installation completed!”
echo “==========================================

        <p>Bu script, OpenTelemetry PHP uzantısını ve Laravel otomatik enstrümantasyonu için gereken Composer paketlerini yükler. Ayrıca, imaj oluşturulurken yükleme sırasında gerekli bileşenlerin başarıyla kurulduğunu doğrulamak için temel bir kontrol yapar.</p>
    </li>
</ol>

<p>Özel imaj hazırlandıktan sonra, BookStack ve MariaDB veritabanını deploy etmeye hazırsınız. Bu adımda, özel imajı oluşturan, OpenTelemetry'yi yapılandıran ve BookStack'ı SigNoz OpenTelemetry Collector ile bağlayan tek bir Docker Compose yapılandırması oluşturacaksınız.</p>

<ol>
    <li>
        <p>Aşağıdaki yapılandırmayla bir <code>docker-compose.yml</code> dosyası oluşturun.<br/></p>
        <pre class="highlight yaml"><code><span class="na">services</span><span class="pi">:</span>

bookstack:
build:
context: .
dockerfile: Dockerfile
image: bookstack-otel:latest
container_name: bookstack

<span class="na">environment</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">PUID=1000</span>
  <span class="pi">-</span> <span class="s">PGID=1000</span>
  <span class="pi">-</span> <span class="s">TZ=Asia/Kolkata</span>

  <span class="pi">-</span> <span class="s">APP_URL=http://<server-ip>:6875</server-ip></span>
  <span class="pi">-</span> <span class="s">APP_KEY=<app_key/></span>

  <span class="pi">-</span> <span class="s">DB_HOST=bookstack_db</span>
  <span class="pi">-</span> <span class="s">DB_PORT=3306</span>
  <span class="pi">-</span> <span class="s">DB_DATABASE=bookstackapp</span>
  <span class="pi">-</span> <span class="s">DB_USERNAME=bookstack</span>
  <span class="pi">-</span> <span class="s">DB_PASSWORD=bookstack</span>

  <span class="c1"># OpenTelemetry</span>
  <span class="pi">-</span> <span class="s">OTEL_SERVICE_NAME=bookstack</span>
  <span class="pi">-</span> <span class="s">OTEL_TRACES_EXPORTER=otlp</span>
  <span class="pi">-</span> <span class="s">OTEL_METRICS_EXPORTER=none</span>
  <span class="pi">-</span> <span class="s">OTEL_LOGS_EXPORTER=none</span>
  <span class="pi">-</span> <span class="s">OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf</span>
  <span class="pi">-</span> <span class="s">OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-ingester-1:4318</span>
  <span class="pi">-</span> <span class="s">OTEL_PHP_AUTOLOAD_ENABLED=true</span>

<span class="na">volumes</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">./bookstack_data:/config</span>

<span class="na">ports</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s2">"</span><span class="s">6875:80"</span>

<span class="na">depends_on</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">bookstack_db</span>

<span class="na">restart</span><span class="pi">:</span> <span class="s">unless-stopped</span>

bookstack_db:
image: lscr.io/linuxserver/mariadb:latest
container_name: bookstack_db

<span class="na">environment</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">PUID=1000</span>
  <span class="pi">-</span> <span class="s">PGID=1000</span>
  <span class="pi">-</span> <span class="s">TZ=Asia/Kolkata</span>
  <span class="pi">-</span> <span class="s">MYSQL_ROOT_PASSWORD=<root_password/></span>
  <span class="pi">-</span> <span class="s">MYSQL_DATABASE=bookstackapp</span>
  <span class="pi">-</span> <span class="s">MYSQL_USER=bookstack</span>
  <span class="pi">-</span> <span class="s">MYSQL_PASSWORD=bookstack</span>

<span class="na">volumes</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="s">./bookstack_db_data:/config</span>

<span class="na">restart</span><span class="pi">:</span> <span class="s">unless-stopped</span>

networks:
default:
external: true
name: signoz-network

Deployment’tan önce aşağıdaki yer tutucuları değiştirdiğinizden emin olun:

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>  *   `<server-ip>` ile sunucunuzun IP adresini veya domain'ini.

<app_key> ile önceki adımda oluşturulan Laravel uygulama anahtarını.
<root_password> ile güvenli bir MariaDB root şifresini.

signoz-network ile SigNoz kurulumunuzun oluşturduğu Docker ağının adını.

Özel imajı oluşturun ve BookStack ile MariaDB konteynerlerini başlatın.

docker compose up -d --build

    <p>Docker, özel BookStack imajını oluşturur, OpenTelemetry bileşenlerini yükler ve iki konteyneri başlatır.</p>
</li>
<li>
    <p>Deployment'ın başarılı bir şekilde tamamlandığını doğrulayın.<br/></p>
    <pre class="highlight shell"><code>docker ps

    <p><code>bookstack</code> ve <code>bookstack_db</code> konteynerlerinin <strong>Up</strong> durumunda olması gerekir.</p>
</li>
<li>
    <p>Tarayıcıda BookStack'ı açın.<br/></p>
    <pre class="highlight plaintext"><code>http://<server-ip>:6875</server-ip></code></pre>

    <p><code><server-ip/></code> ile sunucu IP'nizi değiştirmeyi unutmayın. BookStack giriş sayfasının düzgün bir şekilde yüklendiğini görmelisiniz; bu da özel OpenTelemetry ile etkinleştirilmiş imajın çalıştığını doğrular.<br/> Kullanıcı adı: <code>[email protected]</code>, Şifre: <code>password</code>.</p>
</li>

Uygulama trafiği oluşturmadan önce, OpenTelemetry bileşenlerinin doğru şekilde yüklendiğini ve BookStack’ın izleri dışa aktarmak için yapılandırıldığını doğrulayın. Bu adımda, PHP uzantısının, Composer paketlerinin, Laravel paket keşfi ve OpenTelemetry ortam değişkenlerinin hepsinin beklendiği gibi çalıştığını kontrol edeceksiniz.

OpenTelemetry PHP uzantısının BookStack konteynerinde yüklü olup olmadığını kontrol edin.

docker exec bookstack php -m | grep opentelemetry

    <p>Kurulum başarılı ise, komut aşağıdaki sonucu döndürmelidir:<br/></p>
    <pre class="highlight plaintext"><code>opentelemetry

Gerekli OpenTelemetry Composer paketlerinin yüklendiğini doğrulayın.

docker exec bookstack composer show | grep opentelemetry

    <p>Aşağıdaki gibi paketleri görmelisiniz:<br/></p>
    <pre class="highlight plaintext"><code>open-telemetry/api

open-telemetry/sdk
open-telemetry/exporter-otlp
open-telemetry/opentelemetry-auto-laravel

OpenTelemetry ortam değişkenlerinin çalışan konteynerde mevcut olduğunu doğrulayın.
```
docker exec bookstack printenv | grep OTEL
```
```
    <p>Aşağıdaki gibi bir çıktı almalısınız:<br/></p>
    <pre class="highlight plaintext"><code>OTEL_SERVICE_NAME=bookstack
```
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-ingester-1:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_PHP_AUTOLOAD_ENABLED=true

Laravel’in kurulu paketleri hata vermeden keşfedebildiğini doğrulayın.

docker exec bookstack php artisan package:discover

    <p>Komut, eksik bağımlılıklar veya paket keşif hataları bildirmeden başarıyla tamamlanmalıdır.</p>
</li>
<li>
    <p>Hala çalışan uygulamanızı kontrol etmek için BookStack’ı tarayıcınızda açın.<br/></p>
    <pre class="highlight plaintext"><code>http://<server-ip>:6875</server-ip></code></pre>

    <p>Yer tutucuları doğru şekilde değiştirdiyseniz, giriş sayfası normal bir şekilde yüklenmelidir; bu, özel imajın düzgün çalıştığını ve izleri dışa aktarmaya hazır olduğunu doğrular.</p>
</li>

BookStack yapılandırıldığında ve OpenTelemetry kurulumu doğrulandığında, bir sonraki adım uygulama trafiği oluşturmaktır. Kullanıcılar BookStack ile etkileşime geçtiklerinde, OpenTelemetry her isteği otomatik olarak yakalar ve çıkan izleri SigNoz OpenTelemetry Collector’a aktarır.

Tarayıcınızda BookStack’ı açın.

http://:6875

    <p>Yer tutucuları doğru şekilde değiştirdiyseniz, sunucu IP'niz ile BookStack'a erişilecek.</p>
</li>
<li>
    <p>Varsayılan BookStack yönetici kimlik bilgileri veya mevcut bir kullanıcı hesabıyla giriş yapın.</p>
</li>
<li>
    <p>Uygulama trafiği oluşturmak için birkaç yaygın işlem gerçekleştirin:</p>
</li>

*   Kitapları ve rafları gezmek.


Mevcut sayfaları açmak ve görüntülemek.


Yeni sayfa oluşturmak.


İçeriği düzenleyip kaydetmek.


Uygulamanın farklı bölümleri arasında gezinmek.

Bu işlemlerin her biri, OpenTelemetry tarafından otomatik olarak enstrümante edilen HTTP istekleri oluşturur ve izleri SigNoz’a aktarır.

Uygulama trafiğini oluşturduktan sonra, BookStack’ın izleri SigNoz’a aktardığını doğrulayın. Bu adımda, toplanan izleri inceleyecek ve OpenTelemetry tarafından yakalanan istek ayrıntılarını keşfedeceksiniz.

Tarayıcınızda SigNoz dashboard’unu açın.

http://:8080

    <p>Yer tutucuları doğru şekilde değiştirdiyseniz, sunucu IP'nizi girmeyi unutmayın.</p>
</li>
<li>
    <p>Sol navigasyon menüsünden <strong>Traces</strong> seçeneğine tıklayın.</p>

    <p>Birkaç saniye içinde <strong>bookstack</strong> hizmetinden izler görmelisiniz.</p>

    <p>Eğer hemen iz gözükmezse, birkaç saniye bekleyin, sayfayı yenileyin, BookStack'da başka bir işlem gerçekleştirin ve tekrar kontrol edin.</p>
</li>
<li>
    <p><strong>bookstack</strong> hizmetinden herhangi bir iz tıklayın ve detaylarını inceleyin.</p>

    <p>İz görünümü, bir isteği işlerken yapılan işlem dizisini gösterir. Gerçekleştirdiğiniz işleme bağlı olarak, tipik olarak gelen HTTP isteğini, Laravel middleware'ini, rota işlemesini, kontrolcü yürütmesini ve veritabanı işlemlerini temsil eden span'lar göreceksiniz.</p>
</li>

İzlerin başarıyla kaydedildiğini doğrulayın.

    <p>Aşağıdakileri kontrol edin:</p>
</li>

*    Service Name  `bookstack` olmalı.


İz başarıyla tamamlanmalı.


İstek için birden fazla span görüntülenmeli.


İstek süresi ve yürütme zaman çizelgesi görünür olmalı.

Tebrikler! OpenTelemetry ile BookStack’ı başarıyla donattınız ve izleri SigNoz’a aktarmak için yapılandırdınız. Artık uygulama isteklerinize dair uçtan uca görünürlük elde ettiniz ve uygulama davranışını anlamak ile performans sorunlarını çözmek daha kolay hale geldi.

Ne Öğrendim

Bu yapılandırmayı oluşturmak bir dizi pratik dersle sonuçlandı:

Özel bir Docker imajı kullanın. OpenTelemetry bileşenlerini imaj oluşturulurken yüklemek, dağıtımın tekrarlanabilir olmasını sağlar ve konteynerler yeniden oluşturulurken değişikliklerin kaybolmasını önler.
Her adımı kontrol ederek ilerleyin. PHP uzantısını, Composer paketlerini ve ortam değişkenlerini kontrol etmek, yapılandırma sorunlarını erken tespit etmeye yardımcı oldu.
Konteynerlerin aynı ağı paylaştığından emin olun. BookStack, izleri yalnızca SigNoz OpenTelemetry Collector’a ulaşabiliyorsa dışa aktarabilir.
SigNoz’u kontrol etmeden önce uygulama trafiği oluşturun. İzler, BookStack isteklere yanıt verirken oluşturulur.

Sonuç

BookStack’ı OpenTelemetry ile başarıyla donattınız ve izleri SigNoz’a aktaracak şekilde yapılandırdınız; bu sayede uygulama isteklerine dair uçtan uca görünürlük sağladınız.

Uygulama gözlemlenebilirliğini keşfetmeye devam etmek için aşağıdaki kaynaklara göz atın:

Kaynak: Orijinal Makale

OpenTelemetry ve SigNoz ile Docker Kullanarak BookStack’i İzleme Yöntemleri

Ne Öğrendim

Sonuç

Sanal Medya

Son Eklenenler

Acil Güncelleme: 7-Zip’teki Kritik RCE Açığına Dikkat!

Waymo San Francisco Hizmetine Elektrik Kesintisiyle Ara Verdi

AMD Ryzen 7 7700X3D, Lansmandan Sonra 279$’a Düştü

Kimi: Tehdit mi, yoksa sorun mu? | TechCrunch Gözüyle

Google Pixel 11a İçin Eski Bir İşlemci Kullanmaya Karar Vermeyecek mi?

Mercedes’teki Antonelli, F1 Belçika GP’de Verstappen’i geride bıraktı!

Siber güvenlik, yapay zeka ve savunma sanayiinden; finans ve sinema dünyasına uzanan geniş bir yelpaze. Teknomers; teknoloji, strateji ve yazılım dünyasını sade bir dille sizlerle buluşturuyor.

Kurumsal

Kategoriler

Populer