OpenTelemetry 本番環境: 暗闇でのデバッグを停止します

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

1 
2可観測性が本当に必要になるのは、ダッシュボードを冷静に見ているときではありません。ユーザーが「チェックアウトが遅い」と書き込んだとき、エラー グラフは正常に見え、ログには切断されたメッセージの行が見つかるだけです。
3 
4OpenTelemetry はその瞬間を避けるために作成されました。グラフィックスを増やすためではなく、部分を接続するために作成されました。リクエストは API に入り、データベースを呼び出し、外部プロバイダーを経由し、キューに入れられたジョブをポストし、その後 3 つのサービスで失敗する可能性があります。分散トレースを使用しない場合、そのストーリーを手作業で再構築することになります。 OpenTelemetry があれば、少なくとも地図は手に入ります。
5 
6## 重要なのは trace ではなく、ストーリーです
7 
8trace は span のシーケンスです。そう言うと寒く聞こえますね。実際には、それぞれの span は、`POST /checkout`、`SELECT inventory`、`call payment provider`、`publish order.created` という物語の一部です。
9 
10実際の質問に答え始めると価値が生まれます。
11 
12- どの外部サービスが遅くなっているのか?
13- エラーは特定のバージョンから発生しているのでしょうか?
14- 問題は全員に影響しますか、それとも 1 人のテナントだけに影響しますか?
15- 再試行はタイムアウトを隠しますか?
16- 非同期ジョブが開始されましたが、別の場所で終了しましたか?
17 
18これらの質問は、急いで`console.log` を投げても解決できません。実際、緊急時に追加されたログは、今日は役立ちますが、明日にはノイズになることがよくあります。
19 
20## これをアプリに組み込むにはどうすればよいでしょうか Node.js
21 
22最も健全な設定はシンプルです。アプリがテレメトリを生成し、Collector がそれを送信する場所を決定します。
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28なぜベンダーに直接輸出しないのでしょうか?なぜなら、最初は高速なように見えますが、各サービスには異なる構成、異なる再試行、異なるフィルタがあり、機密データを削除したり宛先を変更したりするための中心的なポイントがないことに気づきます。
29 
30Collector はあらゆる意味で退屈です。 OTLP を受信し、バッチ処理を実行し、フィルター処理、サンプリングを実行し、共通属性を追加し、複数のシステムにエクスポートできます。
31 
32## 自己計測: 良いですが十分ではありません
33 
34Node.js では、自動計測から始めます。これにより、HTTP、サポートされているフレームワーク、データベース、および共通ライブラリを即座に確認できます。
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42次に、アプリの残りの部分の前に SDK を初期化します。
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 
59ただし、これは製品ではなくフレームワークを参照します。ユーザーがクエリを作成したことは知っていますが、そのクエリが「注文の作成」または「サブスクリプションの更新」であったことは知りません。そのためには、優位性が重要なポイントでspan のマニュアルが必要です。
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 マニュアルはどこにも置きません。午前 3 時に、コードベースを半分も読まなくても何が起こったのかを理解したい場所に貼り付けます。
78 
79## 混乱を避けるための 3 つのルール
80 
81最初のルール: 各サービスには、`service.name`、環境とバージョンが必要です。些細なことのように思えますが、これらの属性がなければ、trace はあまり役に立ちません。デプロイによって何かが壊れた場合、2 秒以内にバージョンによってフィルタリングする必要があります。
82 
832 番目のルール: 機密データを属性に含めないでください。電子メール、トークン、整数ペイロード、およびアドレスが誤って可観測性バックエンドに入ってはいけません。ユーザーを識別する必要がある場合は、内部 ID、ハッシュ、または機密性の低いフィールドを考慮してください。
84 
853 番目のルール: 基数に注意してください。 trace の属性として `user.id` を使用することは理にかなっています。指標ラベルとしては、コストとパフォーマンスを損なう可能性があります。
86 
87## メトリクス: 少ないが良好
88 
89非常に実用的な指標から始めたいと思います。
90 
91- リクエストのレート、エラー、期間。
92- 外部依存関係のレイテンシー。
93- タイムアウトと再試行の回数。
94- 尾部の深さ。
95- 作業期間。
96- バージョンごとのエラーの割合。
97 
98残りは必要に応じて追加されます。誰も見ないグラフが満載のダッシュボードは家具であり、可観測性ではありません。
99 
100## ログ: まだ役に立ちますが、リンクされています
101 
102ログは消えません。 `trace_id` と `span_id` を持ち歩くと、さらに便利になります。したがって、エラー ログから開始して trace を開くことも、低速の trace から開始して、そのパスで生成されたログのみを読み取ることもできます。
103 
104相関関係がなければ、針を探していることになります。相関関係を使用すると、少なくともどの引き出しを調べるべきかがわかります。
105 
106## 「カバーされています」と言う前に使用するチェックリスト
107 
108- trace は実際には複数のサービスにまたがっています。
109- ログには `trace_id` と `span_id` が含まれます。
110- Collector にはバッチ処理とメモリ制限が設定されています。
111- エラーはspanに記録されます。
112- サンプリングポリシーがあります。
113- メトリックによってカーディナリティが制御されています。
114- 機密データはフィルタリングされます。
115- アラートはランダムなグラフではなく、ユーザーの症状から始まります。
116 
117## 結論
118 
119OpenTelemetry は、それ自体では生産上の問題を解決しません。しかし、それらへの対処方法は変わります。やみくもにログを追加するのではなく、リクエストの実際のパスを追跡し始めます。
120 
121私にとって、それがうまくいっている兆候は単純です。何かが起こったとき、チームは「どこを見ているのか？」と尋ねなくなります。そして「なぜあの作品は遅いのですか?」と尋ね始めます。そこでは可観測性がダッシュボードのコレクションではなくツールになります。
122 
123## ソース
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

:OpenTelemetry 本番環境: 暗闇でのデバッグを停止しますlines 1-129 (END) — press q to close

2可観測性が本当に必要になるのは、ダッシュボードを冷静に見ているときではありません。ユーザーが「チェックアウトが遅い」と書き込んだとき、エラーグラフは正常に見え、ログには切断されたメッセージの行が見つかるだけです。

4OpenTelemetry はその瞬間を避けるために作成されました。グラフィックスを増やすためではなく、部分を接続するために作成されました。リクエストは API に入り、データベースを呼び出し、外部プロバイダーを経由し、キューに入れられたジョブをポストし、その後 3 つのサービスで失敗する可能性があります。分散トレースを使用しない場合、そのストーリーを手作業で再構築することになります。 OpenTelemetry があれば、少なくとも地図は手に入ります。

6## 重要なのは trace ではなく、ストーリーです

8trace は span のシーケンスです。そう言うと寒く聞こえますね。実際には、それぞれの span は、`POST /checkout`、`SELECT inventory`、`call payment provider`、`publish order.created` という物語の一部です。

10実際の質問に答え始めると価値が生まれます。

12- どの外部サービスが遅くなっているのか?

13- エラーは特定のバージョンから発生しているのでしょうか?

14- 問題は全員に影響しますか、それとも 1 人のテナントだけに影響しますか?

15- 再試行はタイムアウトを隠しますか?

16- 非同期ジョブが開始されましたが、別の場所で終了しましたか?

18これらの質問は、急いで`console.log` を投げても解決できません。実際、緊急時に追加されたログは、今日は役立ちますが、明日にはノイズになることがよくあります。

20## これをアプリに組み込むにはどうすればよいでしょうか Node.js

22最も健全な設定はシンプルです。アプリがテレメトリを生成し、Collector がそれを送信する場所を決定します。

24```text

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

26```

28なぜベンダーに直接輸出しないのでしょうか?なぜなら、最初は高速なように見えますが、各サービスには異なる構成、異なる再試行、異なるフィルタがあり、機密データを削除したり宛先を変更したりするための中心的なポイントがないことに気づきます。

30Collector はあらゆる意味で退屈です。 OTLP を受信し、バッチ処理を実行し、フィルター処理、サンプリングを実行し、共通属性を追加し、複数のシステムにエクスポートできます。

32## 自己計測: 良いですが十分ではありません

34Node.js では、自動計測から始めます。これにより、HTTP、サポートされているフレームワーク、データベース、および共通ライブラリを即座に確認できます。

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

42次に、アプリの残りの部分の前に SDK を初期化します。

44```typescript

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

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

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

49const sdk = new NodeSDK({

50 traceExporter: new OTLPTraceExporter({

51 url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,

52 }),

53 instrumentations: [getNodeAutoInstrumentations()],

54});

56sdk.start();

57```

59ただし、これは製品ではなくフレームワークを参照します。ユーザーがクエリを作成したことは知っていますが、そのクエリが「注文の作成」または「サブスクリプションの更新」であったことは知りません。そのためには、優位性が重要なポイントでspan のマニュアルが必要です。

61```typescript

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

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```

77span マニュアルはどこにも置きません。午前 3 時に、コードベースを半分も読まなくても何が起こったのかを理解したい場所に貼り付けます。

79## 混乱を避けるための 3 つのルール

81最初のルール: 各サービスには、`service.name`、環境とバージョンが必要です。些細なことのように思えますが、これらの属性がなければ、trace はあまり役に立ちません。デプロイによって何かが壊れた場合、2 秒以内にバージョンによってフィルタリングする必要があります。

832 番目のルール: 機密データを属性に含めないでください。電子メール、トークン、整数ペイロード、およびアドレスが誤って可観測性バックエンドに入ってはいけません。ユーザーを識別する必要がある場合は、内部 ID、ハッシュ、または機密性の低いフィールドを考慮してください。

853 番目のルール: 基数に注意してください。 trace の属性として `user.id` を使用することは理にかなっています。指標ラベルとしては、コストとパフォーマンスを損なう可能性があります。

87## メトリクス: 少ないが良好

89非常に実用的な指標から始めたいと思います。

91- リクエストのレート、エラー、期間。

92- 外部依存関係のレイテンシー。

93- タイムアウトと再試行の回数。

94- 尾部の深さ。

95- 作業期間。

96- バージョンごとのエラーの割合。

98残りは必要に応じて追加されます。誰も見ないグラフが満載のダッシュボードは家具であり、可観測性ではありません。

100## ログ: まだ役に立ちますが、リンクされています

101

102ログは消えません。 `trace_id` と `span_id` を持ち歩くと、さらに便利になります。したがって、エラーログから開始して trace を開くことも、低速の trace から開始して、そのパスで生成されたログのみを読み取ることもできます。

103

104相関関係がなければ、針を探していることになります。相関関係を使用すると、少なくともどの引き出しを調べるべきかがわかります。

105

106## 「カバーされています」と言う前に使用するチェックリスト

107

108- trace は実際には複数のサービスにまたがっています。

109- ログには `trace_id` と `span_id` が含まれます。

110- Collector にはバッチ処理とメモリ制限が設定されています。

111- エラーはspanに記録されます。

112- サンプリングポリシーがあります。

113- メトリックによってカーディナリティが制御されています。

114- 機密データはフィルタリングされます。

115- アラートはランダムなグラフではなく、ユーザーの症状から始まります。

116

117## 結論

118

119OpenTelemetry は、それ自体では生産上の問題を解決しません。しかし、それらへの対処方法は変わります。やみくもにログを追加するのではなく、リクエストの実際のパスを追跡し始めます。

120

121私にとって、それがうまくいっている兆候は単純です。何かが起こったとき、チームは「どこを見ているのか？」と尋ねなくなります。そして「なぜあの作品は遅いのですか?」と尋ね始めます。そこでは可観測性がダッシュボードのコレクションではなくツールになります。

122

123## ソース

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