OpenTelemetry üretimde: Karanlıkta hata ayıklamayı durdurun

spinny:~/writing $ vim opentelemetry-nodejs-observability-guide.md

1~
2Gözlemlenebilirliğe gerçekten ihtiyaç duyduğunuz ilk an, sakin bir şekilde kontrol paneline baktığınız zamanlar değildir. Bir kullanıcı "ödeme yavaş" yazdığında, hata grafiği normal görünüyor ve günlüklerde yalnızca bir dizi bağlantısız mesaj buluyorsunuz.
3~
4OpenTelemetry o anı önlemek için yaratıldı: daha fazla grafiğe sahip olmak için değil, parçaları birleştirmek için. Bir istek API'e girer, bir veritabanını çağırır, harici bir sağlayıcıdan geçer, sıraya alınmış bir işi yayınlar ve belki daha sonra üç hizmette başarısız olur. Dağıtılmış izleme olmadan bu hikayeyi elle yeniden oluşturursunuz. OpenTelemetry ile en azından bir haritanız var.
5~
6## Önemli olan trace değil, hikaye
7~
8Bir trace, span dizisidir. Böyle söylersek kulağa soğuk geliyor. Pratikte her span hikayenin bir parçasıdır: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9~
10Değer, gerçek soruları yanıtlamaya başladığınızda ortaya çıkar:
11~
12- hangi harici hizmet yavaşlıyor?
13- hatalar belirli bir sürümden mi kaynaklanıyor?
14- sorun herkesi mi etkiliyor, yoksa yalnızca bir kiracıyı mı?
15- yeniden deneme bir zaman aşımını mı gizliyor?
16- asenkron iş başlıyor ama sonra başka bir yerde mi ölüyor?
17~
18Bu sorular aceleyle atılan bir `console.log` ile çözülemez. Aslında, acil bir durumda eklenen kütük genellikle bugün size yardımcı olur ve yarın gürültüye dönüşür.
19~
20## Bunu bir uygulamaya nasıl koyarım Node.js
21~
22En sağlıklı kurulum basittir: Uygulama telemetri üretir, Collector bunun nereye gönderileceğine karar verir.
23~
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27~
28Neden doğrudan satıcıya ihracat yapmıyorsunuz? İlk başta daha hızlı göründüğü için, daha sonra her hizmetin farklı yapılandırmalara, farklı yeniden denemelere, farklı filtrelere sahip olduğunu ve hassas verileri kaldıracak veya hedefi değiştirecek merkezi bir noktaya sahip olmadığını fark edersiniz.
29~
30Collector her bakımdan sıkıcıdır. OTLP alır, toplu işlem yapar, filtreleyebilir, örnekleme yapabilir, ortak özellikler ekleyebilir ve birden fazla sisteme aktarım yapabilir.
31~
32## Kişisel enstrümantasyon: iyi ama yeterli değil
33~
34Node.js'da otomatik enstrümantasyonla başlayacaktım. Size HTTP'ye, desteklenen çerçevelere, veritabanlarına ve ortak kitaplıklara anında görünürlük sağlar.
35~
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41~
42Daha sonra uygulamanın geri kalanından önce SDK'yi başlatırsınız:
43~
44```typescript
45import { NodeSDK } from '@opentelemetry/sdk-node';
46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
48~
49const sdk = new NodeSDK({
50  traceExporter: new OTLPTraceExporter({
51    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
52  }),
53  instrumentations: [getNodeAutoInstrumentations()],
54});
55~
56sdk.start();
57```
58~
59Ancak bu, ürününüzü değil çerçeveyi görür. Bir sorgu yaptığınızı biliyor ancak sorgunun "sipariş oluştur" veya "aboneliği yenile" konumunda olduğunu bilmiyor. Bunun için hakimiyetin önemli olduğu noktalarda span kılavuzlara ihtiyacınız var.
60~
61```typescript
62const span = tracer.startSpan('checkout.create_order');
63~
64try {
65  span.setAttribute('cart.items_count', input.items.length);
66  const order = await createOrder(input);
67  span.setAttribute('order.id', order.id);
68  return order;
69} catch (error) {
70  span.recordException(error as Error);
71  throw error;
72} finally {
73  span.end();
74}
75```
76~
77span kılavuzlarını hiçbir yere koymam. Onları sabahın üçte kod tabanının yarısını okumadan ne olduğunu anlamak istediğim yere koyardım.
78~
79## Çok fazla kaosu önleyen üç kural
80~
81İlk kural: her hizmetin `service.name`, ortamı ve sürümü olmalıdır. Önemsiz görünüyor, ancak bu özellikler olmadan trace çok daha az kullanışlıdır. Bir dağıtım bir şeyi bozduğunda iki saniye içinde sürüme göre filtrelemek istersiniz.
82~
83İkinci kural: Niteliklere hassas veriler koymayın. E-postalar, belirteçler, tamsayı verileri ve adresler kazara gözlemlenebilirlik arka ucuna düşmemelidir. Bir kullanıcıyı tanımlamanız gerekiyorsa dahili kimlikleri, karmaları veya daha az hassas alanları göz önünde bulundurun.
84~
85Üçüncü kural: kardinaliteye dikkat edin. `user.id`, trace'nin bir özelliği olarak anlamlı olabilir. Bir metrik etiket olarak maliyetlerinizi ve performansınızı yok edebilir.
86~
87## Metrikler: az ama iyi
88~
89Çok pratik ölçümlerle başlayacağım:
90~
91- taleplerin oranları, hataları ve süreleri;
92- dış bağımlılıkların gecikmesi;
93- zaman aşımı ve yeniden deneme sayısı;
94- kuyrukların derinliği;
95- iş süresi;
96- sürüm başına hata yüzdesi.
97~
98Gerisi ihtiyaç duyulduğunda eklenir. Kimsenin bakmadığı grafiklerle dolu kontrol panelleri gözlemlenebilirlik değil mobilyadır.
99~
100## Günlükler: Hala kullanışlı ancak bağlantılı
101~
102Günlükler kaybolmaz. `trace_id` ve `span_id` taşıdıklarında çok daha kullanışlı hale gelirler. Böylece bir hata günlüğünden başlayıp trace'yi açabilir veya yavaş trace'den başlayıp yalnızca o yolda üretilen günlükleri okuyabilirsiniz.
103~
104Korelasyon olmadan iğne arıyorsunuz. Korelasyonla en azından hangi çekmeceye bakmanız gerektiğini bilirsiniz.
105~
106## "Kapsamdayız" demeden önce kullanacağım kontrol listesi
107~
108- trace aslında birden fazla hizmeti geçiyor.
109- Günlükler `trace_id` ve `span_id`'yi içerir.
110- Collector toplu işlem ve bellek limitleriyle yapılandırılmıştır.
111- Hatalar span'ye kaydedilir.
112- Bir numune alma politikası vardır.
113- Metrikler kontrollü kardinaliteye sahiptir.
114- Hassas veriler filtrelenir.
115- Uyarılar rastgele grafiklerden değil, kullanıcı belirtilerinden başlar.
116~
117## Sonuç
118~
119OpenTelemetryTek başına üretim sorunlarını çözmez. Ancak onlarla başa çıkma şekliniz değişir. Günlükleri körü körüne eklemek yerine, bir isteğin gerçek yolunu izlemeye başlarsınız.
120~
121Benim için bunun işe yaradığının işareti basit: Bir şey olduğunda ekip "nereye bakıyoruz?" diye sormayı bırakıyor. ve "bu parça neden yavaş?" diye sormaya başlıyor. Gözlemlenebilirliğin bir gösterge tablosu koleksiyonu değil, bir araç haline geldiği yer burasıdır.
122~
123## Kaynaklar
124~
125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)
126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)
127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)
128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)
129~

NORMAL · opentelemetry-nodejs-observability-guide.md [readonly]129 lines · :q to close

2Gözlemlenebilirliğe gerçekten ihtiyaç duyduğunuz ilk an, sakin bir şekilde kontrol paneline baktığınız zamanlar değildir. Bir kullanıcı "ödeme yavaş" yazdığında, hata grafiği normal görünüyor ve günlüklerde yalnızca bir dizi bağlantısız mesaj buluyorsunuz.

4OpenTelemetry o anı önlemek için yaratıldı: daha fazla grafiğe sahip olmak için değil, parçaları birleştirmek için. Bir istek API'e girer, bir veritabanını çağırır, harici bir sağlayıcıdan geçer, sıraya alınmış bir işi yayınlar ve belki daha sonra üç hizmette başarısız olur. Dağıtılmış izleme olmadan bu hikayeyi elle yeniden oluşturursunuz. OpenTelemetry ile en azından bir haritanız var.

6## Önemli olan trace değil, hikaye

8Bir trace, span dizisidir. Böyle söylersek kulağa soğuk geliyor. Pratikte her span hikayenin bir parçasıdır: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Değer, gerçek soruları yanıtlamaya başladığınızda ortaya çıkar:

11~

12- hangi harici hizmet yavaşlıyor?

13- hatalar belirli bir sürümden mi kaynaklanıyor?

14- sorun herkesi mi etkiliyor, yoksa yalnızca bir kiracıyı mı?

15- yeniden deneme bir zaman aşımını mı gizliyor?

16- asenkron iş başlıyor ama sonra başka bir yerde mi ölüyor?

17~

18Bu sorular aceleyle atılan bir `console.log` ile çözülemez. Aslında, acil bir durumda eklenen kütük genellikle bugün size yardımcı olur ve yarın gürültüye dönüşür.

19~

20## Bunu bir uygulamaya nasıl koyarım Node.js

21~

22En sağlıklı kurulum basittir: Uygulama telemetri üretir, Collector bunun nereye gönderileceğine karar verir.

23~

24```text

25Node.js app -> OpenTelemetry Collector -> backend di observability

26```

27~

28Neden doğrudan satıcıya ihracat yapmıyorsunuz? İlk başta daha hızlı göründüğü için, daha sonra her hizmetin farklı yapılandırmalara, farklı yeniden denemelere, farklı filtrelere sahip olduğunu ve hassas verileri kaldıracak veya hedefi değiştirecek merkezi bir noktaya sahip olmadığını fark edersiniz.

29~

30Collector her bakımdan sıkıcıdır. OTLP alır, toplu işlem yapar, filtreleyebilir, örnekleme yapabilir, ortak özellikler ekleyebilir ve birden fazla sisteme aktarım yapabilir.

31~

32## Kişisel enstrümantasyon: iyi ama yeterli değil

33~

34Node.js'da otomatik enstrümantasyonla başlayacaktım. Size HTTP'ye, desteklenen çerçevelere, veritabanlarına ve ortak kitaplıklara anında görünürlük sağlar.

35~

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

41~

42Daha sonra uygulamanın geri kalanından önce SDK'yi başlatırsınız:

43~

44```typescript

45import { NodeSDK } from '@opentelemetry/sdk-node';

46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

48~

49const sdk = new NodeSDK({

50 traceExporter: new OTLPTraceExporter({

51 url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,

52 }),

53 instrumentations: [getNodeAutoInstrumentations()],

54});

55~

56sdk.start();

57```

58~

59Ancak bu, ürününüzü değil çerçeveyi görür. Bir sorgu yaptığınızı biliyor ancak sorgunun "sipariş oluştur" veya "aboneliği yenile" konumunda olduğunu bilmiyor. Bunun için hakimiyetin önemli olduğu noktalarda span kılavuzlara ihtiyacınız var.

60~

61```typescript

62const span = tracer.startSpan('checkout.create_order');

63~

64try {

65 span.setAttribute('cart.items_count', input.items.length);

66 const order = await createOrder(input);

67 span.setAttribute('order.id', order.id);

68 return order;

69} catch (error) {

70 span.recordException(error as Error);

71 throw error;

72} finally {

73 span.end();

74}

75```

76~

77span kılavuzlarını hiçbir yere koymam. Onları sabahın üçte kod tabanının yarısını okumadan ne olduğunu anlamak istediğim yere koyardım.

78~

79## Çok fazla kaosu önleyen üç kural

80~

81İlk kural: her hizmetin `service.name`, ortamı ve sürümü olmalıdır. Önemsiz görünüyor, ancak bu özellikler olmadan trace çok daha az kullanışlıdır. Bir dağıtım bir şeyi bozduğunda iki saniye içinde sürüme göre filtrelemek istersiniz.

82~

83İkinci kural: Niteliklere hassas veriler koymayın. E-postalar, belirteçler, tamsayı verileri ve adresler kazara gözlemlenebilirlik arka ucuna düşmemelidir. Bir kullanıcıyı tanımlamanız gerekiyorsa dahili kimlikleri, karmaları veya daha az hassas alanları göz önünde bulundurun.

84~

85Üçüncü kural: kardinaliteye dikkat edin. `user.id`, trace'nin bir özelliği olarak anlamlı olabilir. Bir metrik etiket olarak maliyetlerinizi ve performansınızı yok edebilir.

86~

87## Metrikler: az ama iyi

88~

89Çok pratik ölçümlerle başlayacağım:

90~

91- taleplerin oranları, hataları ve süreleri;

92- dış bağımlılıkların gecikmesi;

93- zaman aşımı ve yeniden deneme sayısı;

94- kuyrukların derinliği;

95- iş süresi;

96- sürüm başına hata yüzdesi.

97~

98Gerisi ihtiyaç duyulduğunda eklenir. Kimsenin bakmadığı grafiklerle dolu kontrol panelleri gözlemlenebilirlik değil mobilyadır.

99~

100## Günlükler: Hala kullanışlı ancak bağlantılı

101~

102Günlükler kaybolmaz. `trace_id` ve `span_id` taşıdıklarında çok daha kullanışlı hale gelirler. Böylece bir hata günlüğünden başlayıp trace'yi açabilir veya yavaş trace'den başlayıp yalnızca o yolda üretilen günlükleri okuyabilirsiniz.

103~

104Korelasyon olmadan iğne arıyorsunuz. Korelasyonla en azından hangi çekmeceye bakmanız gerektiğini bilirsiniz.

105~

106## "Kapsamdayız" demeden önce kullanacağım kontrol listesi

107~

108- trace aslında birden fazla hizmeti geçiyor.

109- Günlükler `trace_id` ve `span_id`'yi içerir.

110- Collector toplu işlem ve bellek limitleriyle yapılandırılmıştır.

111- Hatalar span'ye kaydedilir.

112- Bir numune alma politikası vardır.

113- Metrikler kontrollü kardinaliteye sahiptir.

114- Hassas veriler filtrelenir.

115- Uyarılar rastgele grafiklerden değil, kullanıcı belirtilerinden başlar.

116~

117## Sonuç

118~

119OpenTelemetryTek başına üretim sorunlarını çözmez. Ancak onlarla başa çıkma şekliniz değişir. Günlükleri körü körüne eklemek yerine, bir isteğin gerçek yolunu izlemeye başlarsınız.

120~

121Benim için bunun işe yaradığının işareti basit: Bir şey olduğunda ekip "nereye bakıyoruz?" diye sormayı bırakıyor. ve "bu parça neden yavaş?" diye sormaya başlıyor. Gözlemlenebilirliğin bir gösterge tablosu koleksiyonu değil, bir araç haline geldiği yer burasıdır.

122~

123## Kaynaklar

124~

125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)

126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)

127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)

128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)

129~