OpenTelemetry nedir, nasıl kullanılır?

Kısaca OpenTelemetry

OpenTelemetry (kısaca OTel), trace, metrik ve log için ortak API'ler, SDK'lar, OTLP adlı bir iletim protokolü ve Collector adlı bir ara bileşen sunan açık kaynak bir projedir. Veriyi saklamaz, görselleştirmez. Bunlar için seçtiğiniz bir arka uca yönlendirirsiniz.

Pratik kazancı şudur: uygulamaları bir kez enstrümante edersiniz, sonra arka ucu ayar değiştirerek değiştirebilirsiniz. Türkiye'de özellikle uzun ihale ve geçiş süreçlerinden geçen kurumlar için bu, izleme ürünü değiştiğinde yüzlerce servise yeniden dokunmamak anlamına gelir.

Olgunluk dile ve sinyale göre değişir. Kendi yığınınız için opentelemetry.io üzerindeki durum tablolarına bakın.

1. adım: Python servisine sıfır kodla enstrümantasyon

Bir sanal ortam açıp gerekli paketleri kurun. opentelemetry-distro, programınızı saran bir başlatıcı getirir. opentelemetry-bootstrap da kurulu kütüphanelerinizi tespit edip eşleşen enstrümantasyon paketlerini ekler.

python3 -m venv .venv
source .venv/bin/activate
pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install

Bu sırayı, uygulamanızın bağımlılıkları kurulduktan sonra çalıştırın. Yeni bir kütüphane eklediğinizde bootstrap komutunu yeniden çalıştırmanız gerekir.

Yaygın bir web çatısı kullanan uygulamanızı önce konsol çıktısıyla başlatın. Böylece arka uç olmadan neyin üretildiğini görürsünüz.

export OTEL_SERVICE_NAME=basvuru-demo
export OTEL_TRACES_EXPORTER=console
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
opentelemetry-instrument python app.py

Başka bir terminalden isteği gönderin; uygulamanızda gerçekten var olan bir uç noktayı kullanın:

curl http://localhost:8000/basvuru/abc

Servisin terminalinde JSON biçiminde span'ler görmelisiniz. Uygulamanız başka bir servisi de çağırıyorsa, gelen istek için bir server span ve giden çağrı için bir client span arayın. İkisi aynı trace_id değerini taşımalı, parent_id çağıranı göstermelidir. Standart kütüphanenin yerleşik WSGI sunucusu gibi çatısız bir kurulumda server span otomatik gelmez; bunun için sunucu tarafı ara katmanı eklemeniz gerekir.

2. adım: OTLP ile gerçek arka uca gönderin

OTLP, gRPC (varsayılan 4317) veya HTTP (varsayılan 4318) üzerinden çalışır. HTTP çoğu zaman vekil sunuculardan ve güvenlik duvarlarından daha kolay geçer. Kurumsal ağlarda bir kural talebini yazarken tek port, tek hedef söyleyebilmek iş kolaylaştırır. Temel uç nokta değişkenini verdiğinizde SDK trace'ler için sona /v1/traces ekler.

export OTEL_SERVICE_NAME=basvuru-demo
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.0.0,deployment.environment.name=test
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
opentelemetry-instrument python app.py

Arka uç kimlik doğrulaması istiyorsa OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20<token> başlığı ayarlar. Değerler URL kodlamalı olmalıdır, %20 bu yüzden var. Jetonu Dockerfile içine değil, bir secret'a koyun.

Bu değişkenler OpenTelemetry belirtiminden gelir ve dillerin çoğunda aynı çalışır, öğrenmeye değer:

3. adım: Gereken yere elle span ekleyin

Otomatik span'ler çatının kenarlarını kapsar, kodunuzun indirim uyguladığını bilmez. Ekibin o görünüme ihtiyacı olan yerlerde API ile span ekleyin.

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer("basvuru-demo.skor")


def skor_hesapla(dosya, segment):
    with tracer.start_as_current_span("skor-hesapla") as span:
        span.set_attribute("app.musteri.segment", segment)
        try:
            return hesapla(dosya, segment)
        except ValueError as hata:
            span.record_exception(hata)
            span.set_status(Status(StatusCode.ERROR))
            raise

opentelemetry-instrument başlatıcısı SDK'yı sizin yerinize ayarlar, bu kod yalnızca API'yi kullanır. Baştan edinilecek birkaç alışkanlık:

• Span adlarını işleme göre ve düşük çeşitlilikte verin: skor-hesapla, skor-hesapla-musteri-88213 değil. Kimlikler özniteliğe gider.
• Varsa semantik kural adlarını kullanın: http.request.method, http.response.status_code, url.path, http.route. İş öznitelikleri için app. gibi kendi önekinizi seçin.
• Gerekçesi ve politikası yoksa özniteliklere kişisel veri koymayın. T.C. kimlik numarası, IBAN ve telefon numarası için bunu en baştan kural yapın. Bkz. KVKK ve veri yerelliği.
• Sıcak döngüleri span ile sarmayın.

4. adım: Diğer dillerde aynı fikir

Komutlar değişir, ortam değişkenleri aynı kalır.

Java. OpenTelemetry Java instrumentation sürümlerinden ajan JAR dosyasını indirip bağlayın:

export OTEL_SERVICE_NAME=basvuru-api
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
java -javaagent:./opentelemetry-javaagent.jar -jar basvuru-api.jar

Node.js. Otomatik enstrümantasyon paketini kurup uygulamadan önce yükleyin:

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node
export OTEL_SERVICE_NAME=basvuru-web
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
node --require @opentelemetry/auto-instrumentations-node/register app.js

.NET. OpenTelemetry .NET Automatic Instrumentation, kendi sürüm sayfasındaki bir betikle kurulur ve profil API'si ortam değişkenlerini ayarlar. Kubernetes üzerinde OpenTelemetry operatörü bu işi sizin yerinize yapabilir.

5. adım: Büyük ihtimalle karşılaşacağınız sorunlar

Sonraki adımlar

• Collector ekleyin. Öğrenirken SDK'dan doğrudan göndermek yeterlidir. Üretimde Collector; toplu gönderim, yeniden deneme, süzme ve yönlendirme için yer sağlar. Ağ bölgeleri olan kurumlarda bölge başına bir Collector, güvenlik duvarı kurallarını da sadeleştirir.
• Örneklemeye karar verin. Test ortamında yüzde 100 ile başlayın, üretimde gerçek hacmi görünce karar verin. Seçenekleri dağıtık izleme nedir yazısında anlattık.
• Logları bağlayın. Log biçiminize trace kimliğini ekleyin.
• Öznitelikleri standartlaştırın. service.name, service.namespace ve ortam değerlerinde ekiplerle anlaşın, sonradan düzeltmesi zordur.

Wrentrix'e göndermek

Wrentrix, HTTP üzerinden protobuf veya JSON, gzip destekli OTLP trace ve log kabul eder, dolayısıyla yukarıdaki değişkenler doğrudan geçerlidir. Var olan collector'larla birlikte çalışır ve Kubernetes'te otomatik enstrümantasyon için OpenTelemetry operatörünü kullanır. OTLP üzerinden gRPC veya OTLP metriklerine bağımlıysanız bize sorun. Wrentrix'in bu veriyle neler yaptığını APM nedir yazısının sonunda ve canlı demoda görebilirsiniz.

Sık sorulan sorular

OpenTelemetry bir izleme aracı mı?

Hayır. Telemetri üretmek ve taşımak için API, SDK, Collector ve OTLP protokolünden oluşan bir settir. Veriyi saklamak, sorgulamak ve alarm üretmek için yine bir arka uca ihtiyacınız vardır. Enstrümantasyonu taşınabilir yapan da bu ayrımdır.

OTLP için gRPC mi HTTP mi kullanmalıyım?

Çoğu sistem için ikisi de uygundur. 4318 portundaki HTTP vekil sunuculardan ve yük dengeleyicilerden genellikle daha rahat geçer, 4317 portundaki gRPC ise kalıcı bağlantılarda biraz daha verimli olabilir. Arka ucunuzun veya collector'ınızın ne kabul ettiğine bakıp ona uyun.

OpenTelemetry API ile SDK arasındaki fark nedir?

API, kodunuzun ve kütüphanelerin yaptığı çağrıları tanımlar ve kendi başına bir şey yapmaz. SDK ise veriyi örnekleyen, işleyen ve dışa aktaran uygulamadır. Kütüphaneler yalnızca API'ye bağımlı olur, uygulama SDK'yı ayarlar veya bu işi bir ajana bırakır.

OpenTelemetry kod değiştirmeden kullanılabilir mi?

Evet, Java, .NET, Python, Node.js ve başka dillerdeki birçok çatı için kullanılabilir. Bir başlatıcı, ajan veya Kubernetes operatörü yaygın kütüphaneleri otomatik enstrümante eder. Çatının göremediği iş operasyonları için ileride büyük ihtimalle birkaç elle span eklersiniz.

OpenTelemetry Collector şart mı?

Başlamak için değil, çünkü SDK'lar OTLP konuşan bir arka uca doğrudan gönderebilir. Üretimde çoğu ekip toplu gönderim, yeniden deneme, süzme ve örnekleme için Collector ekler. Bu aynı zamanda arka uç kimlik bilgilerini ve yönlendirmeyi uygulama ayarlarının dışında tutar.