Entegrasyon desenleri

Orbtrace ürünü gönderir — sunucu, arayüz ve depolama (Apache Doris). Bir OpenTelemetry Collector göndermez. Collector'ı siz çalıştırırsınız ve o telemetrinizi Orbtrace'in Doris'ine yazar.

Bu sayfa Collector'ın mimarinizde nasıl konumlandığı ile ilgilidir. Sadece tek bir servisi içeri almak istiyorsanız Uygulamalarınızı enstrümante edin ile başlayın — kopyala-yapıştır yolu odur. Yerleşime karar verirken buraya dönün.

Zihinsel model

Sayfanın geri kalanını kolaylaştıran üç gerçek:

• Collector, otel/opentelemetry-collector-contrib'tir. Bir fork değil, bizim build'imiz değil. Tek gereksinim contrib dağıtımıdır, çünkü Doris exporter yalnızca orada gelir.
• Exporter, contrib'in kendi doris exporter'ıdır. Batch'leri Stream Load ile Doris'e yazar — Doris'in yüksek verimli HTTP yükleme API'si.
• Şemanın sahibi Orbtrace'tir, Collector değil. Orbtrace başlarken her tabloyu kendisi oluşturur ve migrate eder. Bu yüzden exporter mutlaka create_schema: false ile çalışmalıdır — bu en sık yapılan hatadır, aşağıda ayrıntılı.

Hangi desen size uyar?

İkisi de deploy paketinizde compose/otelcol-config.yaml olarak gelen aynı referans config'ten başlar. Bu sayfada anlatılan batching, kuyruk, sampling ve sinyal başına Doris bağlantısı zaten içindedir — elle yazmak yerine oradan kopyalayın.

Desen A — tek Collector, sıfırdan

1. 1

   Config dosyasını edinin

   Collector'ın bir config dosyasına ihtiyacı var — otelcol-config.yaml. Sıfırdan yazmayın: bu sayfadaki tüm batching, kuyruk, sampling ve sinyal başına Doris bağlantısı zaten yapılmış hazır haliyle Orbtrace deploy paketinizin compose/ dizininde gelir. Paket ücretsiz bir public download'dur.

   Paketi indirin, açın ve compose/ dizinine cd yapın — otelcol-config.yaml oradadır.

2. 2

   Collector'ı çalıştırın

   O compose/ dizininden, Orbtrace yığınının yanında Collector container'ını başlatın:

   docker run -d --name orbtrace-otelcol \
     --network orbtrace-net \
     -p 4317:4317 -p 4318:4318 \
     -v "$PWD/otelcol-config.yaml:/etc/otelcol-contrib/config.yaml" \
     --tmpfs /var/lib/otelcol/queue:rw,mode=1777 \
     otel/opentelemetry-collector-contrib:latest

3. 3

   Uygulamalarınızı ona yönlendirin

   Her servisin OTEL_EXPORTER_OTLP_ENDPOINT değişkenini bu Collector'a yönlendirin — http://orbtrace-host:4317. Servisiniz saniyeler içinde Orbtrace'te görünür. Dile göre SDK kurulumu Uygulamalarınızı enstrümante edin sayfasında.

Desen B — zaten çalıştırdığınız pipeline'a Orbtrace ekleyin

Zaten bir Collector'ınız var, ya da OTLP konuşan bir vendor agent'ınız. Onu değiştirmeyin. Orbtrace'i ikinci bir hedef olarak ekleyin, böylece aynı telemetri Doris'e de düşer. Mevcut backend'iniz her şeyi almaya devam eder; Orbtrace bir kopya alır. Bu, Orbtrace'i denemenin ya da iki sistemi yan yana çalıştırıp başka bir vendor'dan geçiş yapmanın temiz yoludur.

İki kesin gereksinim:

1. Collector'ınız contrib build olmalı. doris exporter yalnızca otel/opentelemetry-collector-contrib içinde gelir.
2. Her Doris exporter create_schema: false ile çalışmalı. Orbtrace tabloları zaten oluşturdu; şema oluşturan bir exporter, Orbtrace migrator'ıyla yarışır ve şemayı böler.

Minimum doğru bağlantı budur. Orbtrace'e özel her şey yorum satırlarında:

exporters:
  doris/traces:
    endpoint: http://orbtrace-host:8030      # Doris FE — HTTP / Stream Load portu
    database: orbtrace
    username: ${env:DORIS_USER}
    password: ${env:DORIS_PASSWORD}
    table: { traces: otel_traces }
    create_schema: false                     # ZORUNLU — şemanın sahibi Orbtrace
 
  doris/logs:
    endpoint: http://orbtrace-host:8030
    database: orbtrace
    username: ${env:DORIS_USER}
    password: ${env:DORIS_PASSWORD}
    table: { logs: otel_logs }
    create_schema: false
 
  doris/metrics:
    endpoint: http://orbtrace-host:8030
    database: orbtrace
    username: ${env:DORIS_USER}
    password: ${env:DORIS_PASSWORD}
    table: { metrics: otel_metrics }         # önek — Doris beş ayrı tabloda tutar
    create_schema: false
 
service:
  pipelines:
    traces:  { exporters: [mevcut_exporter, doris/traces] }
    logs:    { exporters: [mevcut_exporter, doris/logs] }
    metrics: { exporters: [mevcut_exporter, doris/metrics] }

Bu minimum. Onu hızlı ve dayanıklı yapan üretim ayarları — batching, gönderme kuyrukları, retry'lar, Stream Load header'ları — aşağıdaki Önerilen üretim config'i bölümünde, kopyalamaya hazır. Ya da doğrudan bunları zaten içeren compose/otelcol-config.yaml'dan başlayın.

Doris exporter, alan alan

Her doris/* bloğu aynı bağlantı alanlarını paylaşır. Her birinin ne işe yaradığı:

Şemanın sahibi neden Orbtrace

Orbtrace tabloları, hazır exporter tabloları değildir. İlk migration'ı temel tabloları exporter'ın beklediği tam DDL ile oluşturur — aynı tablo modeli, aynı dağıtım, aynı kolon tipleri — sonra üzerine Orbtrace'in kendi kolonlarını ekler: birleştirilmiş iz kenarları, anomali skorları, sampling kararları. Span stitching, RCA ve replay'i çalıştıran budur. Şemayı exporter oluştursaydı düz tabloları alır, bu özellikleri kaybederdiniz. İkisi birden denerse iki yarım şema elde edersiniz. Bu yüzden create_schema: false, her yerde, her zaman.

Sinyal başına bir exporter: izler, loglar, metrikler

Üç sinyal Doris'te farklı saklanır, bu yüzden farklı yüklenir. Üç exporter'ın sebebi budur.

Bu yerleşim Orbtrace icadı değildir — Apache Doris'in gözlemlenebilirlik verisi için kendi gözlemlenebilirlik dokümanlarında önerdiği tam yapıdır: sadece-ekleme DUPLICATE KEY modeli, RANDOM dağıtım, time_series compaction, attribute demetleri için VARIANT kolonlar ve sorgulanan alanlarda inverted index. Orbtrace o şemayı gönderir ve üzerine kendi kolonlarını ekler.

İzler

En ağır sinyal ve en çok işlenen. İzler tail sampling'den geçer (her hata ve yavaş izi tut, geri kalanı örnekle), sonra otel_traces'e düşer.

otel_traces, DISTRIBUTED BY RANDOM'dır; bu da load_to_single_tablet: "true"'yu geçerli ve değerli kılar — her batch tüm tablet'lere yayılmak yerine tek bir tablet'e gider, bu da yazma amplifikasyonunu ve compaction baskısını azaltır, etkin yazma eşzamanlılığını artırır. Bu, izler ve loglar için en büyük tek Stream Load verim kaldıracıdır.

Loglar

İzlerle aynı depolama şekli — RANDOM, tek-tablet yükleme açık. Loglar, tutmanız gereken iki ekstra processor alır:

• Bir zaman damgası düzeltmesi. Bazı SDK'lar logları sıfır zaman damgasıyla üretir. Doris'in 1970-01-01 için partition'ı yoktur, bu yüzden Stream Load tüm batch'i reddeder, retry kuyruğu dolar ve sağlıklı servislerin logları da başarısız olmaya başlar. Düzeltme, alım-anı zaman damgasını doldurur. Desen B müşterileri bunu kopyalamalı, yoksa filodaki tek bir bozuk SDK log alımını çökertir.
• Bir severity filtresi. INFO altı log gürültüsü, Doris'e ulaşmadan Collector'da düşürülür. Eşiği ORBTRACE_LOG_DROP_BELOW ile ayarlayın (bir OTTL severity sabiti, varsayılan SEVERITY_NUMBER_INFO); bir kaçış-kapısı attribute'u tek tek kayıtları eşiğin ötesinde tutar.

Metrikler

table: { metrics: otel_metrics } bir önektir: OpenTelemetry'nin beş metrik şekli vardır (gauge, sum, histogram, exponential histogram, summary) ve Doris her birini kendi tablosunda tutar — otel_metrics_gauge, otel_metrics_sum vb. Yine tek bir doris/metrics exporter tanımlarsınız; o, her datapoint'i doğru tabloya yönlendirir.

Metrikler, kardinalitenin acıttığı tek sinyaldir. İstek başına taze değer taşıyan tek bir user_id etiketi, kullanıcı başına yeni bir zaman serisi yaratır ve metrik tabloları sınırsız büyür. İki processor buna karşı korur — biri bilinen kötü etiket adlarını siler, biri UUID biçimli değerleri tek bir kovaya katlar. Yalnızca metriklerde çalışırlar; izler ve loglar tam değerlerini korur, çünkü orada ayrıntı zaten esas noktadır.

Metrikler load_to_single_tablet: "false" kullanır. Doris'in genel tavsiyesi herhangi bir RANDOM tablo için "true"'dur, ama Nivorbit'in benchmark'ında metrik tabloları için bu flip hiçbir kazanç sağlamadı ve kuyruğu hafif kötüleştirdi, bu yüzden kapalı kalıyor. Değiştirmeden önce kendi donanımınızda ölçün.

Önerilen üretim config'i

Minimum Desen B bloğu bağlanır ama küçük, tamponsuz yükler gönderir. Aşağıda tam önerilen kurulum var — üç sinyalin hepsi, her biri kendi exporter'ı ve kendi pipeline'ıyla. Bu sinyal-başına ayrım, üç exporter'ın tüm sebebidir; loglar ve metrikler opsiyonel eklenti değil, her biri bir blok gerektirir. Üç exporter neredeyse aynıdır: yalnızca aşağıdaki sinyal-başına tablodaki değerler farklıdır.

extensions:
  file_storage:                       # tek paylaşımlı disk üstü kuyruk; Doris kesintisini/restart'ı atlatır
    directory: /var/lib/otelcol/queue
    timeout: 1s
    compaction:                       # bbolt dosyaları bu olmadan asla küçülmez
      directory: /var/lib/otelcol/queue
      on_start: true
      on_rebound: true
      rebound_needed_threshold_mib: 100
      rebound_trigger_threshold_mib: 10
 
processors:
  batch:
    send_batch_size: 100000           # sık küçük yükler değil, büyük yükler hedefleyin
    send_batch_max_size: 200000
    timeout: 5s
  # memory_limiter, kardinalite koruması, log-zaman-damgası düzeltmesi ve tail_sampling
  # referans config'te tanımlıdır — aşağıdaki "Atmamanız gereken processor'lar"a bakın.
 
exporters:
  # ── İZLER — en ağır sinyal → en çok consumer, en derin kuyruk ──
  doris/traces:
    endpoint: http://orbtrace-host:8030
    database: orbtrace
    username: ${env:DORIS_USER}
    password: ${env:DORIS_PASSWORD}
    table: { traces: otel_traces }
    create_schema: false              # zorunlu — şemanın sahibi Orbtrace
    timeout: 300s
    log_response: true                # düşen-satır sayısının göründüğü tek yer
    headers: { load_to_single_tablet: "true", max_filter_ratio: "0.01" }
    sending_queue: { enabled: true, storage: file_storage, num_consumers: 20, queue_size: 1000 }
    retry_on_failure: { enabled: true, initial_interval: 5s, max_interval: 30s, max_elapsed_time: 30s, randomization_factor: 0.5 }
 
  # ── LOGLAR — aynı blok; yalnızca num_consumers / queue_size değişir ──
  doris/logs:
    endpoint: http://orbtrace-host:8030
    database: orbtrace
    username: ${env:DORIS_USER}
    password: ${env:DORIS_PASSWORD}
    table: { logs: otel_logs }
    create_schema: false
    timeout: 300s
    log_response: true
    headers: { load_to_single_tablet: "true", max_filter_ratio: "0.01" }
    sending_queue: { enabled: true, storage: file_storage, num_consumers: 10, queue_size: 500 }
    retry_on_failure: { enabled: true, initial_interval: 5s, max_interval: 30s, max_elapsed_time: 30s, randomization_factor: 0.5 }
 
  # ── METRİKLER — single-tablet KAPALI (ölçülmüş kazanç-yok); daha küçük kuyruk ──
  doris/metrics:
    endpoint: http://orbtrace-host:8030
    database: orbtrace
    username: ${env:DORIS_USER}
    password: ${env:DORIS_PASSWORD}
    table: { metrics: otel_metrics }
    create_schema: false
    timeout: 300s
    log_response: true
    headers: { load_to_single_tablet: "false", max_filter_ratio: "0.01" }
    sending_queue: { enabled: true, storage: file_storage, num_consumers: 5, queue_size: 200 }
    retry_on_failure: { enabled: true, initial_interval: 5s, max_interval: 30s, max_elapsed_time: 30s, randomization_factor: 0.5 }
 
service:
  extensions: [file_storage]
  pipelines:
    # Her sinyal KENDİ exporter'ını besleyen KENDİ pipeline'ıdır — mesele bu.
    # Aşağıdaki processor zincirleri önerilen settir (referans config'te tanımlı).
    traces:  { receivers: [otlp], processors: [memory_limiter, transform/instance_id, attributes/cardinality_denylist, transform/cardinality_safety, tail_sampling, batch], exporters: [doris/traces] }
    logs:    { receivers: [otlp], processors: [memory_limiter, transform/instance_id, attributes/cardinality_denylist, transform/cardinality_safety, transform/log_timestamp_fix, filter/logs, batch], exporters: [doris/logs] }
    metrics: { receivers: [otlp], processors: [memory_limiter, transform/instance_id, attributes/cardinality_denylist, transform/cardinality_safety, batch], exporters: [doris/metrics] }

Sinyal başına değişen tek üç değer:

Her ayar ne yapar ve ne zaman değiştirilir

İleri seviye tuning (opt-in)

Bunlara yalnızca bir sinyal söylediğinde uzanın. Varsayılanlar çoğu dağıtım için doğrudur.

• Doris Group Commit. Sunucu-tarafı batching: Doris birçok eşzamanlı Stream Load'ı tek bir iç commit'te birleştirir (group commit kılavuzu), böylece daha az tablet versiyonu ve çok daha az compaction baskısı üretir. Gözlemlenebilirliğin ürettiği tam log/yüksek-eşzamanlılık-küçük-yük şekli için Doris'in önerdiği yanıttır — yayınlanmış bir benchmark 1 MB yüklerde ~16× verim gösterir. Bir sinyalin headers'ına group_commit: "async_mode" ekleyin (varsayılanlar: her 10 sn veya 64 MB'da flush, tablo başına ayarlanabilir). İki uyarı: (1) Stream Load + Group Commit, Doris 4.0.2–4.1.0'da aralıklı satır kaybı bildirdi (apache/doris#63160) — önce kendi build'inizde tam satır-sayısı eşitliğini doğrulayın. (2) async_mode bir WAL'a yazar ve WAL diski azalırsa sessizce normal yüklemeye düşer, bu yüzden WAL boyutunu izleyin. Yalnızca tablet-versiyon sayıları hafta-hafta tırmanıyorsa VE tek-tablet ile kuyruk kaldıraçları zaten devredeyse açın.
• Metrikler için load_to_single_tablet. Varsayılan kapalı (ölçülmüş kazanç-yok). Donanımınız bizimkinden farklıysa, flip'ten önce A/B test edin.
• Batch boyutu vs BE sınırı. Daha fazla verim için send_batch_size'ı yükseltin, ama yukarıda anlatılan streaming_load_json_max_mb tavanının altında tutun.
• Kuyruk derinliği ve consumer'lar. Daha derin queue_size daha uzun Doris kesintilerini tamponlar; daha fazla num_consumers yazma paralelliğini artırır. İkisini de alım hızıyla ölçekleyin ve volume'u ona göre boyutlandırın.
• Ağ egress'i. Doris exporter Stream Load gövdelerini sıkıştırmadan gönderir. Bir ağ sınırını aşan yüksek-hacimli bir pipeline'da, hattı ham olay byte'larına göre boyutlandırın ve Collector'ı Doris'e yakın tutun.

Dağıtım mimarileri

Desen A ve B Doris'e neyin bağlandığını yanıtlar. Bu bölüm Collector katmanının nerede yaşadığını yanıtlar. Bunlar OpenTelemetry topluluğunun standart yerleşimleridir — agent ve gateway — Orbtrace'e uygulanmış hali.

Tek host veya VM'ler

Orbtrace yığınının yanındaki tek bir Collector, mimarinin tamamıdır. Her servis — o host'ta ya da başka VM'lerde — OTEL_EXPORTER_OTLP_ENDPOINT'ini ona yönlendirir. Tek bir contrib Collector, yardıma ihtiyaç duymadan önce saniyede on binlerce olayı taşır.

Kubernetes — node agent'ları artı bir gateway

Endüstri-standardı Kubernetes yerleşimi iki katmanlıdır ve önerdiğimiz budur.

• Agent katmanı — bir DaemonSet. Node başına bir Collector; pod'lar yerel node agent'ına gönderir. Agent, k8sattributes processor'ı ile pod, namespace, deployment ve node etiketlerini ekler — Orbtrace'te tam da filtrelediğiniz metadata. Yerel teslimat, SDK gecikmesini ve node'lar arası trafiği düşük tutar.
• Gateway katmanı — küçük bir Deployment. İki veya daha fazla replika pahalı, durumlu işi yapar: tail sampling ve dayanıklı kuyruklu Doris exporter'lar. Doris kimlik bilgilerini tek katmanda tutmak güvenlik incelemenizi de küçültür.
• Tek aşikâr olmayan kural. Tail sampling, bir izin tüm span'lerini aynı replikada görmelidir. Birden fazla gateway varsa, agent'lar routing_key: traceID ile loadbalancing yaparak export etmelidir. Düz round-robin veya client-IP yapışkanlığı, bir izi replikalar arasında böler ve her çok-servisli sampling kararını bozar.
• Kod-sız enstrümantasyon. OpenTelemetry Operator'ü çalıştırın ve iş yüklerini Instrumentation CRD'siyle işaretleyerek imajlarınıza dokunmadan otomatik-enstrümantasyon enjekte edin. Collector katmanlarını da yönetebilir.

Küçük başlayın: tek bir gateway Deployment yeterlidir. Node başına metadata istediğinizde DaemonSet'i ekleyin; tek replika doyduğunda tail sampling'i ölçekli gateway'lere bölün.

OpenShift

Aynı iki katman, iki platform notuyla:

• Operator: OperatorHub'dan Red Hat build of OpenTelemetry'i kullanın — OpenShift için paketlenmiş aynı OpenTelemetry Operator'dır.
• Güvenlik: contrib imajı non-root çalışır, bu yüzden katmanlar hiçbir grant olmadan varsayılan restricted-v2 SCC altında çalışır. Gateway'in kuyruk volume'una securityContext.fsGroup: 10001 ile yazma erişimi verin.

Orbtrace'in kendi OpenShift kurulumu OpenShift sayfasında; bu bölüm yalnızca pipeline ile ilgilidir.

Service mesh (Istio, Linkerd)

Bir mesh, SDK enstrümantasyonunun yerini almaz — ikisi farklı sorulara yanıt verir.

• Uygulamalarınızı enstrümante etmeye devam edin. Envoy sidecar'lar yalnızca pod'lar arasındaki trafiği görür. Bir isteği handler'ınıza, DB çağrınıza ve kuyruk publish'inize ayrıştıramazlar ve trace bağlamını kodunuz boyunca taşıyamazlar. Mesh içindeki enstrümante edilmemiş bir uygulama yine de kopuk tek-atlamalı span'ler üretir.
• W3C traceparent üzerinde anlaşın. Mesh ve SDK'larınız tek bir bağlam-yayma formatını paylaşmalı. W3C Trace Context standarttır ve her OTel SDK'nın varsayılanıdır; eski B3 yerine onu tercih edin.
• Mesh span'leri opsiyonel bir eklentidir. Istio'nun Telemetry API'si Envoy span'lerini OTLP ile export edebilir — başlangıçta düşük bir sampling yüzdesiyle ya da hiç, agent/gateway katmanınıza yönlendirin. Enstrümante uygulamalarla, Envoy span'leri çoğunlukla tabloyu tekrarlarken hacmi katlar.
• Tek egress. Uygulama SDK'ları, mesh telemetrisi ve node agent'ları hepsi aynı Collector katmanından Doris'e akar. Orbtrace'e güvenceye alınacak ya da hata ayıklanacak ikinci bir yol asla yoktur.

Maliyet-farkında sampling

Tail sampling her hata izini, her yavaş izi, her SLO-ihlali ve anomali-etiketli izi tutar, geri kalanını örnekler. "Geri kalan" için olasılıksal taban Orbtrace'ten sürülür: operatörler /admin/sampling'de servis başına aylık iz üst-sınırı belirler ve Orbtrace çözülmüş politikayı /api/sampling/policy.yaml'da YAML olarak yayınlar. Bu, Collector config'ini servis başına düzenlemeden Doris diskini savunur ve sinyal-gürültü oranını yüksek tutar.

Statik politika (varsayılan). Referans config sabit politikalar gönderir — hataları tut, yavaş izleri tut, force-etiketli izleri tut, geri kalanını örnekle. Tek host veya ilk dağıtım için iyidir.

Dinamik politika (üretim). Gateway canlı servis-başına politikayı çeker ve değiştiğinde hot-reload eder:

processors:
  tail_sampling:
    decision_wait: 30s            # tutmayı vaat ettiğiniz en uzun izi aşmalı
    num_traces: 100000            # ≥ iz hızı × decision_wait
    decision_cache:
      sampled_cache_size: 500000
      non_sampled_cache_size: 1000000
    policies: ${httppoll://orbtrace:8080/api/sampling/policy.yaml?interval=5m&auth_env=ORBTRACE_INGEST_TOKEN}

Atmamanız gereken processor'lar

Desen A kullanıcıları bunları referans config'ten bedava alır. Kendi Collector'ını yöneten Desen B kullanıcıları onları kopyalamalıdır — bozuk veriyi Doris'ten uzak tutarlar:

• memory_limiter — her pipeline'da ilk. Heap ısındığında yeni veriyi reddeder, böylece Collector çökmek yerine yükü boşaltır.
• transform/instance_id — service.instance.id'yi k8s.pod.name veya host.name'den doldurur, böylece Orbtrace'in instance-başına kırılımı "(bilinmiyor)"e çökmek yerine çözülür.
• attributes/cardinality_denylist + transform/cardinality_safety — kullanıcı-başına etiket adlarını siler ve UUID-biçimli değerleri katlar, böylece metrikler sınırsız zaman serisine patlamaz.
• transform/log_timestamp_fix — bozuk SDK'lardan gelen sıfır zaman damgalarını doldurur, böylece tek bir bozuk SDK tüm log batch'lerini reddedemez.

Orbtrace'in dokunmadığı şeyler

Orbtrace Doris'ten okur. Uygulamalarınızı veya Collector'ınızı sizin için asla yeniden yapılandırmaz — pipeline sizindir. Bu referans config'in ötesindeki tuning (özel processor'lar, çok-gateway fan-out) ayrı bir hizmettir, ön koşul değil.