Uygulamaları enstrümante et

Bu sayfa "Orbtrace kuruldu" ile "arayüzde kendi servisimi görüyorum" arasındaki köprüdür. Kurulum ve İlk giriş'den sonra okuyun.

Zihinsel model

Uygulamanız bir OpenTelemetry SDK'sını (ya da onun otomatik enstrümantasyon ajanını) kullanarak telemetri yayar. SDK, bu telemetriyi ağ üzerinden Orbtrace'in yanında çalıştırdığınız OpenTelemetry Collector'a gönderir (Orbtrace'in bir parçası değildir). Collector veriyi Orbtrace deposuna yazar. Orbtrace arayüzde size gösterir.

Veri akışı tek cümleyle: SDK span'leri, log'ları ve metrikleri batch'ler ve OTLP üzerinden Collector'a gönderir; Collector zenginleştirir, batch'ler ve (trace'ler için) tail-sample uygular, sonra Stream Load ile Doris'e yazar; Orbtrace hiçbir zaman ingest yolunda durmaz — Doris'ten okur ve gösterir.

Uygulamanızda yalnız bir config bloğunu değiştirirsiniz: veriyi gönderdiğiniz adresi — Collector'ınızın host'u ve OTLP portu. Sonrasında servisiniz birkaç saniye içinde Orbtrace'te belirir.

Peki o Collector nerede yaşamalı — Orbtrace host'unda mı, bir Kubernetes DaemonSet'i olarak mı, hâlihazırda çalıştırdığınız bir pipeline'ın yanında mı? Bu mimari karar, platform başına önerilen yerleşimlerle birlikte (Kubernetes, OpenShift ve service mesh'ler dahil) Entegrasyon desenleri sayfasındadır. Bu sayfa bir Collector adresinin var olduğunu varsayar ve dile özgü SDK kurulumunu anlatır.

Java / Spring Boot

En kolay yol OpenTelemetry Java agent'tır. JVM'e başlangıçta takılır ve Spring, Hibernate, Kafka, JDBC, gRPC ve 80+ kütüphaneyi kod değişikliği gerektirmeden otomatik enstrümante eder.

1. 1

   Agent jar dosyasını indirin

   curl -L -o opentelemetry-javaagent.jar \
     https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

2. 2

   Ortam değişkenlerini ayarlayın

   export OTEL_SERVICE_NAME=checkout-api
   export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment=production
   export OTEL_EXPORTER_OTLP_ENDPOINT=http://orbtrace.internal:4317
   export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
   # İsteğe bağlı, yalnızca .env'de OTLP_AUTH_TOKEN ayarladıysanız:
   export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer\ <token>

3. 3

   Agent'ı başlatma komutuna ekleyin

   java -javaagent:./opentelemetry-javaagent.jar -jar app.jar

   Kod değişikliği yok. Uygulamayı yeniden başlatın. Tamam.

.NET

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Instrumentation.AspNetCore

builder.Services.AddOpenTelemetry()
  .ConfigureResource(r => r.AddService("billing-api"))
  .WithTracing(t => t
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddOtlpExporter(o => o.Endpoint = new Uri("http://orbtrace.internal:4317")));

Go

Go'nun çalışma zamanı ajanı yoktur — SDK'yı içe aktarıp kodunuzu enstrümante edersiniz.

go get go.opentelemetry.io/otel \
       go.opentelemetry.io/otel/sdk \
       go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)
 
func initTracer(ctx context.Context) (*sdktrace.TracerProvider, error) {
    exp, err := otlptracegrpc.New(ctx,
        otlptracegrpc.WithEndpoint("orbtrace.internal:4317"),
        otlptracegrpc.WithInsecure(),
    )
    if err != nil { return nil, err }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),
        sdktrace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceName("inventory-service"),
        )),
    )
    otel.SetTracerProvider(tp)
    return tp, nil
}

HTTP framework'ünüzün OTel middleware'ini kullanarak her isteğe otomatik span eklenmesini sağlayın.

Node.js

npm install @opentelemetry/api @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-grpc

// otel.js — bunu her şeyden önce require edin
const { NodeSDK } = require("@opentelemetry/sdk-node");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
 
const sdk = new NodeSDK({
  serviceName: "orders-api",
  traceExporter: new OTLPTraceExporter({
    url: "http://orbtrace.internal:4317",
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

node --require ./otel.js index.js ile çalıştırın.

Python

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install   # kullandığınız kütüphaneler için enstrümantasyon paketleri kurar

export OTEL_SERVICE_NAME=payments-worker
export OTEL_EXPORTER_OTLP_ENDPOINT=http://orbtrace.internal:4317
opentelemetry-instrument python worker.py

PHP

PHP, bir C uzantısı ve framework başına paketler (Laravel, Symfony, Slim, WordPress ve daha fazlası) aracılığıyla otomatik enstrümante olur. :4318 üzerinden OTLP/HTTP ile dışa aktarır — PHP'nin yerleşik gRPC'si yoktur, bu yüzden önerilen yol HTTP'dir ve ek bir uzantı gerektirmez.

pecl install opentelemetry        # otomatik enstrümantasyon uzantısı
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  open-telemetry/opentelemetry-auto-laravel   # ya da -symfony, -slim, -psr15, …

export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_SERVICE_NAME=storefront
export OTEL_EXPORTER_OTLP_ENDPOINT=http://orbtrace.internal:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Kod değişikliği yok — uzantı, istek başlangıcında framework'e takılır. (FPM ve CLI'nin ikisi de çalışır; kısa CLI scriptleri için OTEL_PHP_TRACES_PROCESSOR=simple ekleyin, böylece span'ler süreç sonlanmadan önce flush edilir.)

Ruby

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all

# config/initializers/opentelemetry.rb — uygulamanız yüklenmeden önce gerekli
require "opentelemetry/sdk"
require "opentelemetry/instrumentation/all"
require "opentelemetry/exporter/otlp"
 
OpenTelemetry::SDK.configure do |c|
  c.service_name = "notifications"
  c.use_all   # mevcut her enstrümantasyonu etkinleştir (Rails, Sidekiq, pg, redis, …)
end

Ruby OTLP exporter'ı varsayılan olarak :4318 üzerinde HTTP/protobuf kullanır; OTEL_EXPORTER_OTLP_ENDPOINT=http://orbtrace.internal:4318 ayarlayın.

Rust

Rust'ın çalışma zamanı ajanı yoktur — SDK'yı tracing yığınınıza bağlarsınız:

cargo add opentelemetry opentelemetry_sdk opentelemetry-otlp \
          tracing-opentelemetry tracing-subscriber

use opentelemetry_otlp::WithExportConfig;
 
let exporter = opentelemetry_otlp::SpanExporter::builder()
    .with_tonic()                                  // gRPC :4317
    .with_endpoint("http://orbtrace.internal:4317")
    .build()?;
let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
    .with_batch_exporter(exporter)
    .with_resource(opentelemetry_sdk::Resource::builder()
        .with_service_name("edge-router").build())
    .build();

tracing_opentelemetry::layer() ile tracing'e köprüleyin, böylece her #[tracing::instrument] span'i dışa aktarılır.

Diğer diller

OpenTelemetry'nin 11'den fazla dil için SDK'sı vardır (C++, Erlang/Elixir, Swift ve daha fazlası) — hepsi aynı OTLP'yi konuşur, bu yüzden hepsi Orbtrace'e değişmeden ulaşır. Kural her yerde aynıdır: service.name'i ayarlayın ve exporter'ı Collector'ınızın :4317 (gRPC) ya da :4318 (HTTP) adresine yönlendirin. SDK'sı olmayan her şey için doğrudan OTLP/HTTP JSON gönderin:

"Doğrudan HTTP üzerinden JSON göndereyim"

Tek seferlik scriptler ve egzotik diller için OTLP/HTTP, 4318 portunda JSON kabul eder:

curl -X POST http://orbtrace.internal:4318/v1/logs \
  -H 'Content-Type: application/json' \
  -d '{
    "resourceLogs": [{
      "resource": { "attributes": [{"key":"service.name","value":{"stringValue":"crontab"}}] },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "1715600000000000000",
          "severityText": "INFO",
          "body": { "stringValue": "Gecelik temizlik tamamlandı" }
        }]
      }]
    }]
  }'

Veritabanları, cache'ler ve mesaj kuyrukları

PostgreSQL, Redis ya da Kafka'nızı enstrümante etmezsiniz — telemetrilerini iki yönden alırsınız ve ikisi de büyük ölçüde otomatiktir.

1. İstemci tarafı span'ler — zaten bedava. Uygulamalarınızdaki otomatik enstrümantasyon (yukarıdaki her dil), her giden çağrıyı çağıran servis üzerinde bir span olarak yakalar: SQL sorgusu (db.system=postgresql, db.statement), Redis GET/SET, Kafka publish/consume — standart OTel semantic-convention öznitelikleriyle. Yani "veritabanımı nasıl görürüm" sorusunun cevabı, onunla konuşan servisleri enstrümante etmektir; sorgu süreleri, yavaş ifadeler ve N+1 desenleri hep bu servislerin trace'lerinde belirir. Yaygın istemciler için ekstra kurulacak bir şey yok.

2. Bir kuyruk boyunca trace bağlamı — Kafka/RabbitMQ üzerinden uçtan uca trace'ler. A servisindeki bir producer ile B servisindeki bir consumer, ancak trace bağlamı mesajda taşınırsa tek bir trace'e katılır. OTel'in messaging enstrümantasyonu, publish'te mesaj başlıklarına W3C traceparent enjekte eder ve consume'da çıkarır — böylece iki taraf da enstrümante edildiğinde Orbtrace, broker boyunca kesintisiz trace'i otomatik gösterir. Eski bir producer'ın başlıkları taşımadığı yerde ise Orbtrace'in asenkron dikiş motoru, producer→consumer bağlantısını sezgisel olarak yeniden kurar (bir zaman penceresi içinde mesaj ID'lerini eşleştirerek), böylece kuyruklar arası trace'ler güncellenemez servislere karşı bile bağlı kalır.

3. Altyapı seviyesinde metrikler — Collector'ınıza bir receiver ekleyin. Veri deposunu altyapı olarak izlemek için — bağlantı havuzu doygunluğu, replikasyon gecikmesi, Kafka consumer-group gecikmesi, cache isabet oranı, buffer kullanımı — standart OTel yolu, sunucuya yönlendirilmiş, Collector'ınız üzerinde bir scraper receiver'dır. Contrib Collector, yaygın sistemler için receiver'lar içerir: postgresqlreceiver, mysqlreceiver, redisreceiver, kafkametricsreceiver, mongodbreceiver, rabbitmqreceiver, elasticsearchreceiver ve daha fazlası. Bunları Collector config'inize ekleyin, metrikleri de her şey gibi Orbtrace'e aksın:

receivers:
  postgresql:
    endpoint: db.internal:5432
    username: monitor
    password: ${env:PG_MONITOR_PASSWORD}
    tls: { insecure: true }
  redis:
    endpoint: cache.internal:6379
    collection_interval: 30s
  kafkametrics:
    brokers: [kafka.internal:9092]
    scrapers: [brokers, topics, consumers]   # consumer-group gecikmesi burada yaşar
 
service:
  pipelines:
    metrics:
      receivers: [otlp, postgresql, redis, kafkametrics]   # otlp = uygulamalarınız; gerisi = altyapı
      exporters: [doris]

Her receiver'a hedef sistemde salt okunur bir izleme kullanıcısı verin — hiçbiri yazma erişimine ihtiyaç duymaz. Kubernetes'te bu receiver'lar genellikle gateway katmanında yaşar (bkz. Entegrasyon desenleri → Önerilen mimariler), node başına değil küme başına bir scrape.

Çalıştığını nasıl doğrularım?

1. Orbtrace'te Servisler (kenar menü, servis ikonu) açın. service.name'iniz uygulama veri göndermeye başladıktan ~10 sn içinde belirir.
2. Servise tıklayın. Detay ekranı son saatin istek hızını (istek/sn) ve p99 gecikmesini gösterir.
3. Keşfet → İzler açıp service:<servis-adınız> ile süzün. Trace'leri görmelisiniz.

60 saniyede servis görünmüyorsa:

• Uygulama sunucusundan nc -zv orbtrace.internal 4317 çalıştırıp ağın Collector'a ulaştığını doğrulayın.
• Collector'ınızın loglarını kontrol edin: docker logs orbtrace-otelcol | tail -100 (Entegrasyon desenleri'nde başlattığınız Collector). Bağlantı reddi ya da yetkilendirme hataları burada görünür.
• Sorun giderme → Veri gelmiyor bölümünü okuyun.

Otomatik ne geliyor, ne eklemelisiniz?

Otomatik enstrümantasyon size tüm "iskelet" span'leri bedava verir: HTTP istek işleyicileri, veritabanı çağrıları, kuyruk tüketicileri, giden HTTP çağrıları. Zamanın nereye harcandığını görmeniz için bu genelde yeterlidir.

Orbtrace'i gerçekten güçlü yapmak için iş mantığınızın önemli noktalarına birkaç özel span ekleyin:

// Java
Span span = tracer.spanBuilder("pricing.calculateDiscount").startSpan();
try (Scope s = span.makeCurrent()) {
    span.setAttribute("customer.tier", tier);
    span.setAttribute("cart.size", cart.size());
    return calculate(tier, cart);
} finally {
    span.end();
}

Bu öznitelikler Trace'ler ekranında süzülebilir sütunlar ve Arama söz dizimi'nde sorgulanabilir boyutlar olarak görünür.

Loglar ve metrikler ne olacak?

Otomatik enstrümantasyon kutudan trace'leri halleder. Log'lar için çoğu SDK standart logger'a (Java'da SLF4J, Python'da logging, vs.) köprü kurar — OTEL_LOGS_EXPORTER=otlp ayarlayın, akmaya başlar. Metrik'ler için SDK, JVM / çalışma zamanı / HTTP metriklerini otomatik yayar; iş metrikleri için Meter.counterBuilder(...) çağrıları ekleyin.

Her dil için örnekler resmi OpenTelemetry belgelerinde: opentelemetry.io/docs/languages. Geçerli her OTel verisi Orbtrace Collector'ı tarafından kabul edilir — protokolü değiştirmiyoruz.