Correlation ID

Her istek, loglama ve hata bağlamı için dahili olarak kullanılan bir systemCorrelationId otomatik olarak oluşturur. İsteğe bağlı olarak, dağıtık izlemeyi etkinleştirmek için bunu giden bir HTTP başlığı olarak downstream servislere iletebilirsiniz.

Neden Correlation ID Önemlidir?

Dağıtık bir sistemde, tek bir kullanıcı eylemi düzinelerce servisler arası çağrıyı tetikleyebilir. Paylaşılan bir tanımlayıcı olmadan, bir hatayı teşhis etmek için servisler arasındaki logları ilişkilendirmek manuel yeniden yapılandırma gerektirir. Correlation ID başlığını iletmek, tüm çağrı zincirini log toplayıcınızda anında görünür kılar.

Yayılımı Etkinleştirme

Correlation ID yayılımı isteğe bağlıdır. Adapter üzerinde etkinleştirin:

const adapter = HttpAdapter.builder()
  .withCorrelationId()                   // 'x-correlation-id' olarak iletir (varsayılan)
  .withCorrelationId('x-request-id')     // özel başlık adı kullan
  .build();

Bu adapter üzerinden gönderilen her istek, oluşturulan bir UUID ile başlığı içerecektir.

İstek Bazlı Geçersiz Kılmalar

İstek bazlı yapılandırma, adapter seviyesindeki ayarın önüne geçer:

// Bu istek için farklı bir başlık adıyla etkinleştir
const request = new RequestBuilder('https://api.example.com')
  .setEndpoint('/payments')
  .withCorrelationId('x-trace-id')
  .build();

// Bu istek için tamamen devre dışı bırak (adapter yapılandırması görmezden gelinir)
const internalRequest = new RequestBuilder('https://api.example.com')
  .setEndpoint('/internal/health')
  .withoutCorrelationId()
  .build();

Başlık Çözümleme Sırası

Adapter bir istek gönderdiğinde, correlation ID başlığı şu sırayla çözümlenir:

1. İstek bazlı başlık (builder'da .withCorrelationId('custom-header'))
2. Adapter seviyesi başlık (adapter builder'da .withCorrelationId('custom-header'))
3. Varsayılan başlık — 'x-correlation-id'

İstek üzerinde .withoutCorrelationId() çağrılırsa adapter yapılandırmasından bağımsız olarak hiçbir başlık iletilmez.

Correlation ID'ye Erişim

correlationId, exception'lara eklenen her RequestContext'te mevcuttur:

} catch (error) {
  if (error instanceof BaseAdapterException) {
    logger.error({
      correlationId: error.requestContext?.correlationId,
      ...error.toJSON(),
    });
  }
}

Bu sayede her başarısızlık logu correlation ID'yi içerecektir — tek bir istek zincirine ait tüm olayları log toplayıcınızda aramak son derece kolaylaşır.