OpenTelemetry ile Gözlemlenebilirlik: Başlangıç Rehberi
Aziz Özdemiroğlu

Bir istek yavaşladığında ya da hata verdiğinde sorunun hangi serviste, hangi veritabanı sorgusunda olduğunu dakikalar içinde bulmak, modern sistemlerde gözlemlenebilirlik (observability) altyapısına bağlıdır. Bu yazıda tedarikçiden bağımsız açık standart OpenTelemetry'nin temel kavramlarını, Node.js ve Python uygulamalarına kod değiştirmeden izleme eklemeyi, OpenTelemetry Collector yapılandırmasını ve üretime geçmeden önce dikkat edilmesi gereken maliyet ve güvenlik noktalarını adım adım öğreneceksiniz.
Kısaca
- OpenTelemetry (OTel), CNCF bünyesinde geliştirilen; iz (trace), metrik ve kayıt (log) verilerini üretmek, toplamak ve iletmek için ortak API, SDK ve protokol (OTLP) sunan açık standarttır.
- Uygulamayı bir kez OTel ile enstrümante edersiniz; verinin hangi arka uca (Jaeger, Prometheus, Grafana, ticari APM) gideceğini Collector yapılandırmasıyla değiştirirsiniz.
- Node.js ve Python için otomatik enstrümantasyon, HTTP, veritabanı ve mesaj kuyruğu çağrılarını kod değiştirmeden izler.
- Standart OTLP portları: 4317 (gRPC) ve 4318 (HTTP).
- Üretimde örnekleme (sampling), hassas veri filtreleme ve kaynak sınırları zorunludur.
Temel kavramlar
| Kavram | Açıklama | Örnek |
|---|---|---|
| Trace (iz) | Bir isteğin sistemdeki tüm yolculuğu | Kullanıcının "sipariş ver" isteği |
| Span | İzin içindeki tek bir işlem; başlangıç/bitiş zamanı ve öznitelikleri vardır | POST /orders, SELECT * FROM stock |
| Context propagation | İz kimliğinin servisler arasında taşınması (W3C traceparent başlığı) |
API → sipariş servisi → stok servisi |
| Metric | Zaman içinde toplanan sayısal ölçüm | İstek sayısı, gecikme histogramı |
| Log | Olay kaydı; iz kimliğiyle ilişkilendirilebilir | Hata mesajı + trace_id |
| Resource | Veriyi üreten varlığın tanımı | service.name=siparis-api, deployment.environment=prod |
| Semantic conventions | Öznitelik adları için ortak sözlük | http.request.method, db.system |
| Collector | Telemetriyi alan, işleyen ve dışa aktaran ara katman | Ajan veya merkezi ağ geçidi modu |
| OTLP | OpenTelemetry Protocol | gRPC 4317 / HTTP 4318 |
Mimari: önerilen başlangıç düzeni
[Uygulama + OTel SDK] --OTLP--> [OTel Collector] --> Jaeger / Tempo (izler)
|-------> Prometheus (metrikler)
|-------> Loki / Elasticsearch (kayıtlar)
Uygulamaların doğrudan arka uca değil, Collector'a göndermesi; arka uç değişikliği, filtreleme, örnekleme ve yeniden deneme mantığını tek yerde toplar.
Adım 1 — Yerel deneme ortamı
Tek komutla izleri görebileceğiniz bir Jaeger örneği (Jaeger OTLP'yi doğrudan kabul eder):
docker run --rm -d --name jaeger \
-p 16686:16686 -p 4317:4317 -p 4318:4318 \
jaegertracing/all-in-one:latest
# Arayüz: http://localhost:16686
Adım 2 — Node.js: kod değiştirmeden enstrümantasyon
npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node
export OTEL_SERVICE_NAME="siparis-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=dev,service.version=1.4.0"
node --require @opentelemetry/auto-instrumentations-node/register app.js
Express, HTTP istemcisi, pg, mysql2, redis gibi yaygın kütüphanelerin çağrıları otomatik olarak span'e dönüşür.
Elle span ekleme (iş mantığı için)
const { trace, SpanStatusCode } = require("@opentelemetry/api");
const tracer = trace.getTracer("siparis-api");
async function fiyatHesapla(sepet) {
return tracer.startActiveSpan("fiyat.hesapla", async (span) => {
try {
span.setAttribute("sepet.urun_sayisi", sepet.urunler.length);
const toplam = await indirimleriUygula(sepet);
return toplam;
} catch (err) {
span.recordException(err);
span.setStatus({ code: SpanStatusCode.ERROR });
throw err;
} finally {
span.end();
}
});
}
Adım 3 — Python: otomatik enstrümantasyon
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install # yüklü kütüphanelere uygun enstrümantasyonları kurar
export OTEL_SERVICE_NAME="stok-servisi"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
opentelemetry-instrument python app.py
Flask, Django, FastAPI, requests, psycopg gibi kütüphaneler desteklenir. Servisler arası HTTP çağrılarında traceparent başlığı otomatik taşındığı için Node.js ve Python servisleri tek bir izde birleşir.
Adım 4 — OpenTelemetry Collector yapılandırması
otel-collector.yaml:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_percentage: 80
spike_limit_percentage: 20
batch: {}
attributes/temizle:
actions:
- key: http.request.header.authorization
action: delete
- key: user.email
action: hash
probabilistic_sampler:
sampling_percentage: 20
exporters:
otlp/jaeger:
endpoint: jaeger:4317
tls:
insecure: true # yalnızca aynı iç ağdaki test ortamı için
prometheus:
endpoint: 0.0.0.0:8889
debug:
verbosity: basic
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, attributes/temizle, probabilistic_sampler, batch]
exporters: [otlp/jaeger]
metrics:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [prometheus]
docker run --rm -d --name otelcol -p 4317:4317 -p 4318:4318 -p 8889:8889 \
-v "$PWD/otel-collector.yaml:/etc/otelcol-contrib/config.yaml:ro" \
otel/opentelemetry-collector-contrib:latest
İşlemci sırası önemlidir: memory_limiter ilk, batch son sırada olmalıdır.
Örnekleme stratejileri
| Strateji | Nerede? | Artı | Eksi |
|---|---|---|---|
| Baş tabanlı, olasılıksal (head sampling) | SDK veya Collector | Basit, düşük maliyet | Nadir hataları kaçırabilir |
Ebeveyne bağlı (parentbased_traceidratio) |
SDK | İz bütünlüğü korunur | Oran sabit |
| Kuyruk tabanlı (tail sampling) | Collector | Hatalı/yavaş izleri her zaman tutabilir | Bellek ve yapılandırma maliyeti |
SDK'da basit oran örneklemesi:
export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1" # %10
Üretim kontrol listesi
- Her serviste
service.name,service.version,deployment.environmenttanımlı. - Uygulamalar Collector'a, Collector arka uca gönderiyor; arka uç kimlik bilgileri yalnızca Collector'da.
- Collector'da
memory_limitervebatchişlemcileri etkin. - Hassas veri filtresi:
Authorizationbaşlıkları, oturum çerezleri, kişisel veriler (e-posta, TC kimlik no, telefon) span özniteliklerinden siliniyor veya özetleniyor (KVKK). - Veritabanı sorgularında parametre değerleri kaydedilmiyor.
- OTLP alıcıları internete açık değil; ağlar arası iletimde TLS ve kimlik doğrulama var.
- Örnekleme oranı ve saklama süresi maliyet bütçesiyle uyumlu.
- Kayıtlarda
trace_idalanı var; kayıt ve iz arasında tek tıkla geçiş mümkün. - Collector'un kendi metrikleri (düşen veri, kuyruk doluluğu) izleniyor.
Sık yapılan hatalar
- Her şeyi %100 örneklemek: Trafik büyüdükçe depolama maliyeti patlar. Hatalı izleri tutan kuyruk tabanlı örneklemeyi değerlendirin.
- Yüksek kardinaliteli metrik etiketleri: Kullanıcı kimliği veya tam URL'yi metrik etiketi yapmak, zaman serisi sayısını kontrolsüz artırır. Bu bilgiler span özniteliğinde kalmalı.
service.nameunutmak: Tüm servislerunknown_serviceolarak görünür.- Enstrümantasyonu en sona bırakmak: Bağımlılıkların yüklenmesinden önce başlatılmalı;
--require/opentelemetry-instrumentbu yüzden kullanılır.
Sonuç
OpenTelemetry, gözlemlenebilirliği belirli bir tedarikçiye bağlı olmaktan çıkarıp uygulamanın kalıcı bir özelliği hâline getiriyor. Otomatik enstrümantasyonla bir öğleden sonra içinde servisler arası izleri görmeye başlayabilir, Collector ile hangi veriyi nereye, ne oranda gönderdiğinizi merkezi olarak yönetebilirsiniz. Üretime geçerken örnekleme, hassas veri filtresi ve kaynak sınırlarını ilk günden yapılandırmak, hem maliyeti hem de KVKK riskini kontrol altında tutar.
Kaynaklar
- OpenTelemetry belgeleri: https://opentelemetry.io/docs/
- OpenTelemetry — Node.js zero-code instrumentation: https://opentelemetry.io/docs/zero-code/js/
- OpenTelemetry — Python zero-code instrumentation: https://opentelemetry.io/docs/zero-code/python/
- OpenTelemetry Collector yapılandırması: https://opentelemetry.io/docs/collector/configuration/
- OpenTelemetry — SDK ortam değişkenleri: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
- W3C Trace Context: https://www.w3.org/TR/trace-context/
#OpenTelemetry#Observability#Tracing#OTel Collector#Jaeger#Prometheus




