Table of Contents
Kurulum #
Bu paketleri yüklüyoruz.
Console Demo #
Console Demo #
OpenTelemetry’deki Temel Kavramlar #
Resource Nedir ve Nasıl Yapılandırılır? #
OpenTelemetry’de Resource, hangi servis veya uygulamanın veri ürettiğini tanımlayan ve telemetri (Trace, Metrics, Logs) verilerine bağlam kazandıran meta bilgileri içerir. Bu sayede, ürettiğiniz verilerin hangi servis tarafından, hangi sürümde, hangi ortamda (örn. dev, preprod, prod) veya hangi instance (kopya) üzerinden geldiğini anlayabilirsiniz.
Resource Üzerinde Tanımlanabilen Bilgiler #
Service Name
- Uygulama veya servisin adı. (Örneğin:
PaymentService
)
- Uygulama veya servisin adı. (Örneğin:
Service Version
- Uygulamanın hangi sürümünün çalıştığını belirtir. (Örneğin:
1.0.0
)
- Uygulamanın hangi sürümünün çalıştığını belirtir. (Örneğin:
Resource Üzerinde Tanımlanabilen Bilgiler #
Namespace
- Bir uygulama veya servis ailesinin/alanının adı olarak düşünebilirsiniz. (Örneğin:
MyCompanyName.PaymentSystem
)
- Bir uygulama veya servis ailesinin/alanının adı olarak düşünebilirsiniz. (Örneğin:
Instance
- Servisin belirli bir kopyası. (Örneğin:
payment-service-instance-2
)
- Servisin belirli bir kopyası. (Örneğin:
Resource Üzerinde Tanımlanabilen Bilgiler #
- Deployment Environment (örn.
dev
,preprod
,prod
)- Static property olarak veya değişken üzerinden tanımlayabilirsiniz. Böylece telemetri verilerinin hangi ortamdan geldiği kolayca anlaşılır.
Örnek Resource Tanımı #
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(
ResourceBuilder.CreateDefault()
.AddService(
serviceName: "PaymentService",
serviceVersion: "1.0.0")
.AddAttributes(new Dictionary<string, object>
{
["deployment.environment"] = "dev", // Ortam bilgisi
["service.instance.id"] = "instance-001" // Instance
})
)
// Exporter vb. diğer ayarlar
.AddConsoleExporter()
.Build();
AgentSource (TraceProvider) #
- Tanım: Uygulamada trace verilerinin üretildiği ana sınıflardır.
- Amaç: Trace verilerini oluşturarak, hangi işlemlerin ne kadar sürdüğünü ve hangi bileşenler arasında gerçekleştiğini izlememizi sağlar.
AgentSource (TraceProvider) #
- Tasarım:
- Static veya Singleton şeklinde tasarlanmalıdır, böylece uygulama içinde merkezi ve tutarlı bir yerden yönetilebilir.
- Benzer şekilde,
namespace
yapısını kullanarak farklı traceleri mantıksal olarak ayırabilir veya gruplandırabilirsiniz.
AgentSource (TraceProvider) #
- Faydalar:
- Uygulamanın belirli kısımlarından veya mikroservislerden üretilen verileri daha düzenli takip etme olanağı sunar.
- Tek noktada konfigüre edildiğinden, kaynak yönetimi (örneğin, tek bir Tracer Provider üzerinden farklı bileşenlerin izlenmesi) kolaylaşır.
- Şeffaf gözlemlenebilirlik elde etmeye yardımcı olur, çünkü tüm izleme (tracing) aktiviteleri ortak bir kayıt noktası üzerinden yönetilir.
Activity (Span) #
- Uygulamadaki her bir operasyon, bir span (örneğin: HTTP isteği, veritabanı çağrısı, dosya yazma) şeklinde temsil edilir.
- Bu span’lerin bir araya gelmesiyle bir trace (işlem bütünlüğü) oluşur.
Span İçeriği #
- Start-end time: Span’in başlama ve bitiş zamanı
- Success-failure: İşlemin başarılı mı yoksa hatalı mı sonuçlandığı
- Span kind: Span’in rolü (client, server, consumer, producer, internal)
- Attributes/Tags: Operasyona dair ek bilgiler (örn. kullanıcı kimliği, sürüm bilgisi vb.)
- Events: Span sürecindeki belirli olaylar veya kontrol noktaları (checkpoints)
Span ve Trace Arasındaki İlişki #
- Span: Tek bir operasyonu temsil eder.
- Trace: Birden fazla span’in birleşerek oluşturduğu, uçtan uca bütün bir işlemi ifade eder.
Activity (Span) Kind #
- Internal: Uygulama içindeki dahili bir işlemi ifade eder.
- Server: İstekleri sunucu tarafında karşılayan veya işleyen taraftır.
- Client: Dış bir kaynağa veya hizmete istek gönderen taraftır.
- Producer: Mesaj veya veri üreterek bir kuyruğa, topic’e veya başka bir yere yayımlayan taraftır.
- Consumer: Yayınlanmış mesajları veya event’leri alan ve işleyen taraftır.
Event #
- Event, bir span’in (Activity) içerisindeki belirli bir olayı veya noktayı temsil eder.
- Log benzeri bir yapısı olsa da in-memory tutulduğu için (doğrudan bellekte saklanır), çok sık kullanılması yüksek maliyet doğurabilir.
- Örneğin, “Bu dosyayı oluşturdum, boyutu 50 KB” şeklindeki bir bilgiyi Event olarak ekleyebilirsiniz.
Activity(Span) Status #
Bir span’in durumunu belirlemek için üç temel Status tipi vardır:
- Ok
- Error
- Unset
Başarısız bir işlem (ör. istisna, hata kodu) oluştuğunda span durumunu Error olarak ayarlayabilirsiniz.
Tag (Attributes) #
- Span’e ek bilgi (metadata) eklemek için kullanılır.
- Örnek: Sipariş ID, kullanıcı ID, işlem türü gibi bilgileri, span ile ilişkilendirerek daha ayrıntılı takip edebiliriz.
- İleride analiz yaparken veya sorun giderirken, bu etiketler sayesinde hangi işlemin hangi kullanıcı veya siparişle ilgili olduğunu hızlıca bulabilirsiniz.
Correlations (In-Process) #
- Bir uygulama içindeki veya farklı servisler arasındaki span’lerin birbirine bağlı olduğu durumu ifade eder.
- İstek, bir servis/uygulamadan diğerine aktarıldığında, traceId paylaşılır ve böylece bütün istek zinciri aynı iz (trace) altında toplanır.
- Bu sayede APM (Application Performance Monitoring) araçlarında tek bir iz (trace) içerisinde, çoklu servis ve işlem adımlarını uçtan uca takip edebilirsiniz.
Activity.Current #
- Tanım: .NET uygulamalarında halihazırda etkin (aktif) olan
Activity
nesnesine (span) erişim sağlar. - Kullanım: Aşağıdaki örnek,
Activity.Current
üzerinden mevcut işlem (span) bilgisini elde etmeye yarar. Örneğin, etiket eklemek veya durum güncellemesi yapmak istediğinizdeActivity.Current?.SetTag("key", "value")
şeklinde çağrı yapabilirsiniz.
Activity.Current #
- Örnek Senaryo:
- Bir HTTP isteği geldiğinde, yeni bir
Activity
başlatılır (veya otomatik başlatılır). - Bu süreçte,
Activity.Current
o anki isteği temsil eden span’i gösterir. - Ek etiketler, event’ler veya hata durumlarıyla ilgili kayıtlar bu aktif
Activity
üzerinden yapılır.
- Bir HTTP isteği geldiğinde, yeni bir
Önemli Not: Activity.Current
, her zaman aktif bir işlem (span) olmayabilir. Bu nedenle, kod yazarken null
durumlarını dikkate almak gereklidir.
ActivityListener #
- Tanım: .NET uygulamalarında, oluşturulan veya bitirilen
Activity
(yani Span) nesnelerini dinlemek (listen) ve yönetmek için kullanılan bir mekanizmadır. - Amaç: Uygulamada hangi
Activity
’lerin (işlemlerin) izlenmesi, örneğin hangilerinin kaydedilmesi veya kaydedilmemesi gerektiğine karar vermenizi sağlar.
ActivityListener #
- Nasıl Çalışır:
- ActivityListener nesnesi oluşturulur.
- İlgili geribildirim (callback) yöntemleri tanımlanır, örneğin:
ShouldListenTo
(hangiActivitySource
’ları dinlemek istediğimizi belirtir)Sample
(hangiActivity
’lerin başlatılıp başlatılmayacağına karar verir)ActivityStarted
/ActivityStopped
(birActivity
başladığında veya bittiğinde çalışacak event metodları)
- Bu listener, ActivitySource nesnesine veya genel
ActivitySource.AddActivityListener(activityListener)
gibi bir API üzerinden eklenir.
Örnek Kullanım #
using System;
using System.Diagnostics;
public class ActivityListenerExample
{
public static void SetupListener()
{
var listener = new ActivityListener
{
// Hangi ActivitySource'ları dinleyeceğimize karar veriyoruz.
ShouldListenTo = (activitySource) =>
{
// Örneğin, "MyCompany.MyApp" adındaki ActivitySource’lara izin ver
return activitySource.Name.Contains("MyCompany.MyApp");
},
// Activity oluşturulmadan önce “örnekleme” kararı veriyoruz (ör. kaydetsin mi kaydetmesin mi).
Sample = (ref ActivityCreationOptions<ActivityContext> options) =>
{
// Belli bir mantığa göre (ör. rastgele yüzdelik, environment bilgisi vb.) karar verebilirsiniz.
// Örnekte tüm Activity'leri kaydediyoruz:
return ActivitySamplingResult.AllDataAndRecorded;
},
// Activity başladığında çalışacak callback
ActivityStarted = activity =>
{
Console.WriteLine($"Activity Started: {activity.DisplayName}");
},
// Activity bittiğinde çalışacak callback
ActivityStopped = activity =>
{
Console.WriteLine($"Activity Stopped: {activity.DisplayName}");
}
};
// Listener'ı default ActivitySource'a ekliyoruz.
ActivitySource.AddActivityListener(listener);
}
}
Bu Örnekte #
- ShouldListenTo: Hangi ActivitySource’ları dinlemek istediğimizi belirtiyoruz.
- Sample: Hangi Activity’lerin gerçekten oluşturulacağını veya kaydedileceğini kontrol edebiliyoruz.
- ActivityStarted ve ActivityStopped: Oluşturulan Activity’lerin başlangıç ve bitiş anlarında özel işlem yapabiliyoruz (örnek olarak konsola yazma).
Neden Önemli? #
- Filtreleme: Çok fazla Activity oluşturulduğunda, dinlemek istediklerimizi kısıtlayarak sistem yükünü azaltabilirsiniz.
- Merkezi Yönetim: Tracing mantığını uygulamanın çeşitli yerlerine serpmek yerine, tek bir noktadan (ActivityListener) yönetebilirsiniz.
Neden Önemli? #
- Esneklik: Gerçek zamanlı olarak hangi span’lerin kaydedilmesi gerektiğini değiştirerek (örneğin, hata modunda tüm tracing’i aktif hale getirerek) sistem davranışını dinamik olarak ayarlayabilirsiniz.
- İnce Ayar: Özel mantıklar (ör. belirli bir kullanıcıya veya siparişe ait Activity’leri kaydetme) tanımlayarak ince düzeyde kontrol sağlayabilirsiniz.