技術共有

Elasticsearch: Node.js ECS ロギング - Winston

2024-07-12

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

前回の記事「」の続きです。Elasticsearch: Node.js ECS ロギング - Pino前回の記事に引き続き、Winston パッケージを使用したターゲットについて説明します。 Node.js アプリケーションはその日に合わせて ECS を生成します。この Node.js パッケージはウィンストン・ロガーフォーマッタが提供されており、 Elastic Common Schema (ECS) のロギング互換性がある。組み合わせる ファイルビート 送信者は、Elastic Stack 内の 1 か所からすべてのログを監視できます。 winston 3.x バージョン >=3.3.3 をサポートします。

設定

インストール

  1. npm install @elastic/ecs-winston-format
  2. npm install winston

構成

ウィンストン・ロギング.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3.  
  4. const logger = winston.createLogger({
  5.   format: ecsFormat(/* options */),  // 1
  6.   transports: [
  7.     new winston.transports.Console()
  8.   ]
  9. });
  10.  
  11. logger.info('hi');
  12. logger.error('oops there is a problem', { err: new Error('boom') });
  • ECS フォーマッタを winston に渡します。

上記のコードを実行した結果は次のようになります。

Filebeat を構成する

ファイルビート 7.16+

ファイルビート.yml

  1. filebeat.inputs:
  2. - type: filestream     # 1
  3.   paths: /path/to/logs.json
  4.   parsers:
  5.     - ndjson:
  6.       overwrite_keys: true # 2
  7.       add_error_key: true  # 3
  8.       expand_keys: true    # 4
  9.  
  10. processors: // 5
  11.   - add_host_metadata: ~
  12.   - add_cloud_metadata: ~
  13.   - add_docker_metadata: ~
  14.   - add_kubernetes_metadata: ~
  1. ファイルストリーム入力を使用して、アクティブなログ ファイルから行を読み取ります。
  2. 競合が発生した場合、デコードされた JSON オブジェクトの値は、Filebeat が通常追加するフィールド (タイプ、ソース、オフセットなど) を上書きします。
  3. JSON アンマーシャリング エラーが発生した場合、Filebeat は「error.message」キーと「error.type: json」キーを追加します。
  4. Filebeat は、デコードされた JSON からドット キーを再帰的に取り除き、階層オブジェクト構造に展開します。
  5. プロセッサーはデータを強化します。見る プロセッサ 詳しく知ることができ。

ファイルビート < 7.16

ファイルビート.yml

  1. filebeat.inputs:
  2. - type: log
  3.   paths: /path/to/logs.json
  4.   json.keys_under_root: true
  5.   json.overwrite_keys: true
  6.   json.add_error_key: true
  7.   json.expand_keys: true
  8.  
  9. processors:
  10. - add_host_metadata: ~
  11. - add_cloud_metadata: ~
  12. - add_docker_metadata: ~
  13. - add_kubernetes_metadata: ~

詳細については、「」を参照してください。 ファイルビートリファレンス。

使い方

ウィンストン・ロギング.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3.  
  4. const logger = winston.createLogger({
  5.   level: 'info',
  6.   format: ecsFormat(/* options */), // 1
  7.   transports: [
  8.     new winston.transports.Console()
  9.   ]
  10. });
  11.  
  12. logger.info('hi');
  13. logger.error('oops there is a problem', { foo: 'bar' });
  1. 以下の利用可能なオプションを参照してください。
node winston-logging.js | jq .

このスクリプトを実行します (次の場所で入手可能)ここ取得したもの) は、上記と同様のログ出力を生成します。

フォーマッタはデータを JSON にシリアル化する役割を担うため、追加する必要はありません。 json フォーマッタ。さらに、フォーマッタはタイムスタンプを自動的に生成するため、追加する必要はありません。タイムスタンプ フォーマッタ。

エラーログ

デフォルトでは、フォーマッタは Error インスタンスの err メタフィールドを次のように変換します。 ECSエラーフィールド 。例えば例：

ウィンストン・ロギング.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3. const logger = winston.createLogger({
  4.   format: ecsFormat(), 
  5.   transports: [
  6.     new winston.transports.Console()
  7.   ]
  8. });
  9.  
  10. const myErr = new Error('boom');
  11. logger.info('oops', { err: myErr });

err メタフィールドの特別な処理は、convertErr: false オプションを使用して無効にできます。

ウィンストン・ロギング.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3. const logger = winston.createLogger({
  4.   format: ecsFormat({convertErr: false} ), 
  5.   transports: [
  6.     new winston.transports.Console()
  7.   ]
  8. });
  9.  
  10. const myErr = new Error('boom');
  11. logger.info('oops', { err: myErr });

HTTPリクエストとレスポンスのログ記録

ConvertReqRes: true オプションを使用すると、フォーマッタはそれぞれ req および res メタフィールドとして渡されたときに Node.js コアを自動的に変換します。 リクエスト そして応答 物体。

ウィンストン・ロギング.js

  1. const http = require('http');
  2. const winston = require('winston');
  3. const { ecsFormat } = require('@elastic/ecs-winston-format');
  4.  
  5. const logger = winston.createLogger({
  6.   level: 'info',
  7.   format: ecsFormat({ convertReqRes: true }), // 1
  8.   transports: [
  9.     new winston.transports.Console()
  10.   ]
  11. });
  12.  
  13. const server = http.createServer(handler);
  14. server.listen(3000, () => {
  15.   logger.info('listening at http://localhost:3000')
  16. });
  17.  
  18. function handler (req, res) {
  19.   res.setHeader('Foo', 'Bar');
  20.   res.end('ok');
  21.   logger.info('handled request', { req, res }); // 2
  22. }
  1. ConvertReqRes オプションを使用する
  2. レコード req および/または res メタフィールド

これは使用します ECS HTTP フィールドリクエストとレスポンスの情報を含むログを生成します。例えば例：

上記にアクセスする必要があります http://ローカルホスト:3000 そうすることでのみ、上記の日の情報を確認できます。

ログの関連付けに APM を使用する

これ ECCS ログフォーマッタ付きエラスティックAPM 統合された。Node アプリケーションが使用している場合Node.js エラスティック APM エージェント、APM サービスまたはトレース データとログ データを関連付けるために、いくつかのフィールドがログ レコードに追加されます。

  • 現在スパンをトレースしているときに呼び出されるログ ステートメント (logger.info(...) など) には次のものが含まれます。追跡フィールド— trace.id、transaction.id、span.id。
  • APM エージェントによって決定または構成された複数のサービス識別子フィールド (service.name、service.version、service.environment、service.node.name) により、Kibana のサービスとログ間の相互リンクが可能になります。
  • event.dataset は Elastic Observability アプリケーションで有効になりますログレート異常検出。

たとえば、実行します 例/http-with-elastic-apm.js そしてカール -i ローカルホスト:3000/ 次の内容を含むログ レコードが生成されます。

  1. % node examples/http-with-elastic-apm.js | jq .
  2. ...
  3.   "service.name": "http-with-elastic-apm",
  4.   "service.version": "1.4.0",
  5.   "service.environment": "development",
  6.   "event.dataset": "http-with-elastic-apm"
  7.   "trace.id": "7fd75f0f33ff49aba85d060b46dcad7e",
  8.   "transaction.id": "6c97c7c1b468fa05"
  9. }

これらの ID は、APM エージェントによって報告された追跡データと一致します。

Elastic APM との統合は、apmIntegration: false オプションを使用して明示的に無効にすることができます。次に例を示します。

  1. const logger = winston.createLogger({
  2.   format: ecsFormat({ apmIntegration: false }),
  3.   // ...
  4. })

制限事項と注意事項

ecs-logging の仕様ログ レコードの最初の 3 つのフィールドは、@timestamp、log.level、および message にすることをお勧めします。バージョン 1.5.0 以降、このフォーマッタはこの推奨事項に従っていません。これは可能ですが、ログ レコードごとに ecsFields に新しいオブジェクトを作成する必要があります。 ecs-logging フィールドの順序は読みやすさを目的としたものであり、相互運用性に影響を与えないことを考慮して、パフォーマンスを優先することが決定されました。

参照する

ecsFormat([オプション])

  • options {type-object} は次のオプションをサポートしています。
    • ConvertErr {type-boolean} レコードの err フィールドを ECS エラー フィールドに変換するかどうか。デフォルト値：真実。
    • ConvertReqRes {type-boolean} req および res HTTP リクエストおよびレスポンス フィールドを ECS HTTP、User-Agent、および URL フィールドに記録するかどうか。デフォルト値：間違い。
    • apmIntegration {type-boolean} APM エージェント統合を有効にするかどうか。デフォルト値：真実。
    • serviceName {type-string} 「service.name」の値。指定した場合、アクティブな APM エージェントの値をオーバーライドします。
    • serviceVersion {type-string} 「service.version」の値。指定した場合、アクティブな APM エージェントの値をオーバーライドします。
    • serviceEnvironment {type-string} 「service.environment」の値。指定した場合、アクティブな APM エージェントの値をオーバーライドします。
    • serviceNodeName {type-string} 「service.node.name」の値。指定した場合、アクティブな APM エージェントの値はすべて上書きされます。
    • eventDataset {type-string} 「event.dataset」の値。指定した場合、${serviceVersion} を使用するデフォルト値はオーバーライドされます。

ECS ログ形式を出力する winston 用のフォーマッタを作成します。これは治療法ですecsFields([オプション]) そしてecsStringify([オプション]) シングルフォーマット。次の 2 つは同等です。

  1. const { ecsFormat, ecsFields, ecsStringify } = require('@elastic/ecs-winston-format');
  2. const winston = require('winston');
  3.  
  4. const logger = winston.createLogger({
  5.   format: ecsFormat(/* options */),
  6.   // ...
  7. });
  8.  
  9. const logger = winston.createLogger({
  10.   format: winston.format.combine(
  11.     ecsFields(/* options */),
  12.     ecsStringify()
  13.   ),
  14.   // ...
  15. });

ecsFields([オプション])

  • options {type-object} は次のオプションをサポートしています。
    • ConvertErr {type-boolean} レコードの err フィールドを ECS エラー フィールドに変換するかどうか。デフォルト値：真実。
    • ConvertReqRes {type-boolean} req および res HTTP リクエストおよびレスポンス フィールドを ECS HTTP、User-Agent、および URL フィールドに記録するかどうか。デフォルト値：間違い。
    • apmIntegration {type-boolean} APM エージェント統合を有効にするかどうか。デフォルト値：真実。
    • serviceName {type-string} 「service.name」の値。指定した場合、アクティブな APM エージェントの値をオーバーライドします。
    • serviceVersion {type-string} 「service.version」の値。指定した場合、アクティブな APM エージェントの値をオーバーライドします。
    • serviceEnvironment {type-string} 「service.environment」の値。指定した場合、アクティブな APM エージェントの値をオーバーライドします。
    • serviceNodeName {type-string} 「service.node.name」の値。指定した場合、アクティブな APM エージェントの値はすべて上書きされます。
    • eventDataset {type-string} 「event.dataset」の値。指定した場合、${serviceVersion} を使用するデフォルト設定はオーバーライドされます。

ログ情報オブジェクトのフィールドを ECS ログ形式に変換する winston 用のフォーマッタを作成します。

ecsStringify([オプション])

ログ レコードを JSON に文字列化/シリアル化するための winston 用のフォーマッタを作成します。

これは logform.json() に似ています。どちらも、safe-stable-stringify パッケージを使用して JSON を生成します。いくつかの違い:

  • この文字列指定子は、ECS フィールドではないため、レベル フィールドのシリアル化をスキップします。
  • Winston は、bigint を文字列に変換する置換機能を提供します。その理由は、JavaScript JSON パーサーが bigint を解析するときに精度が失われるためです。反対意見は、BigInt が型を数値ではなく文字列に変更することです。現在、この文字列化子は BitInt を文字列に変換しません。

個人プロフィール

彼は 30 年以上テクノロジーの研究に専念しており、java、linux、javascript、php、css などのさまざまな言語に堪能であり、オープンソース分野で多くの貢献を行っています。将来の参考のために技術開発におけるいくつかの問題を共有する開発者ドキュメント ステーション。

私の連絡先情報

郵便