Elasticsearch: Node.js ECS Logging

Elasticsearch: Node.js ECS Logging - Winston

2024-07-12

Αυτή είναι η συνέχεια του προηγούμενου άρθρου "Elasticsearch: Node.js ECS Logging - PinoΣυνέχεια του Συνεχίζουμε το προηγούμενο άρθρο για να μιλήσουμε για τη χρήση του πακέτου Winston για στόχευση Node.js Η εφαρμογή δημιουργεί ECS για να ταιριάζει με την ημέρα.Αυτό το πακέτο Node.js είναιWinston LoggerΠαρέχεται μορφοποιητής, με Καταγραφή Elastic Common Schema (ECS). σύμφωνος.συνδυασμόςFilebeat Αποστολέας, μπορείτε να παρακολουθείτε όλα τα αρχεία καταγραφής από ένα μέρος στην Elastic Stack. Υποστήριξη έκδοσης winston 3.x >=3.3.3.

στήνω

Εγκαθιστώ


npm install @elastic/ecs-winston-format
npm install winston

Διαμόρφωση

winston-logging.js


const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');
 
const logger = winston.createLogger({
  format: ecsFormat(/* options */),  // 1
  transports: [
    new winston.transports.Console()
  ]
});
 
logger.info('hi');
logger.error('oops there is a problem', { err: new Error('boom') });

Περάστε τον μορφοποιητή ECS στον Winston.

Το αποτέλεσμα της εκτέλεσης του παραπάνω κώδικα είναι:

Ρύθμιση παραμέτρων Filebeat

Filebeat 7.16+

filebeat.yml


filebeat.inputs:
- type: filestream     # 1
  paths: /path/to/logs.json
  parsers:
    - ndjson:
      overwrite_keys: true # 2
      add_error_key: true  # 3
      expand_keys: true    # 4
 
processors: // 5
  - add_host_metadata: ~
  - add_cloud_metadata: ~
  - add_docker_metadata: ~
  - add_kubernetes_metadata: ~

Χρησιμοποιήστε την είσοδο ροής αρχείων για να διαβάσετε γραμμές από ένα ενεργό αρχείο καταγραφής.
Εάν προκύψει διένεξη, οι τιμές του αποκωδικοποιημένου αντικειμένου JSON θα αντικαταστήσουν τα πεδία που προσθέτει κανονικά το Filebeat (τύπος, πηγή, μετατόπιση κ.λπ.).
Εάν παρουσιαστεί σφάλμα κατάργησης JSON, το Filebeat θα προσθέσει τα κλειδιά "error.message" και "error.type: json".
Το Filebeat θα αφαιρέσει αναδρομικά τα πλήκτρα με τελείες από το αποκωδικοποιημένο JSON και θα το επεκτείνει σε μια ιεραρχική δομή αντικειμένου.
Οι επεξεργαστές βελτιώνουν τα δεδομένα σας.Βλέπωεπεξεργαστές να μάθω περισσότερα.

Filebeat < 7.16

filebeat.yml


filebeat.inputs:
- type: log
  paths: /path/to/logs.json
  json.keys_under_root: true
  json.overwrite_keys: true
  json.add_error_key: true
  json.expand_keys: true
 
processors:
- add_host_metadata: ~
- add_cloud_metadata: ~
- add_docker_metadata: ~
- add_kubernetes_metadata: ~

Για περισσότερες πληροφορίες, βλ Αναφορά Filebeat。

πώς να χρησιμοποιήσετε

winston-logging.js


const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');
 
const logger = winston.createLogger({
  level: 'info',
  format: ecsFormat(/* options */), // 1
  transports: [
    new winston.transports.Console()
  ]
});
 
logger.info('hi');
logger.error('oops there is a problem', { foo: 'bar' });

Δείτε παρακάτω τις διαθέσιμες επιλογές.

node winston-logging.js | jq .

Εκτελέστε αυτό το σενάριο (διαθέσιμο στοεδώαποκτηθεί) θα παράγει έξοδο καταγραφής παρόμοια με τα παραπάνω.

Ο μορφοποιητής είναι υπεύθυνος για τη σειριοποίηση των δεδομένων σε JSON, επομένως δεν χρειάζεται να προσθέσετε json Μορφοποιητής.Επιπλέον, ο μορφοποιητής δημιουργεί αυτόματα τη χρονική σήμανση, επομένως δεν χρειάζεται να προσθέσετεχρονική σήμανση Μορφοποιητής.

Σφάλμα καταγραφής

Από προεπιλογή, ο μορφοποιητής μετατρέπει το μεταπεδίο err μιας παρουσίας σφάλματος σε Πεδίο σφάλματος ECSE .Για παράδειγμαπαράδειγμα：

winston-logging.js


const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');
const logger = winston.createLogger({
  format: ecsFormat(), 
  transports: [
    new winston.transports.Console()
  ]
});
 
const myErr = new Error('boom');
logger.info('oops', { err: myErr });

Ο ειδικός χειρισμός του μεταπεδίου err μπορεί να απενεργοποιηθεί μέσω της επιλογής convertErr: false:

winston-logging.js


const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');
const logger = winston.createLogger({
  format: ecsFormat({convertErr: false} ), 
  transports: [
    new winston.transports.Console()
  ]
});
 
const myErr = new Error('boom');
logger.info('oops', { err: myErr });

Καταγραφή αιτημάτων και απαντήσεων HTTP

Χρησιμοποιώντας την επιλογή convertReqRes: true, ο μορφοποιητής θα μετατρέψει αυτόματα τον πυρήνα Node.js όταν μεταβιβαστεί ως μεταπεδία req και res αντίστοιχα. αίτηση καιαπάντηση αντικείμενο.

winston-logging.js


const http = require('http');
const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');
 
const logger = winston.createLogger({
  level: 'info',
  format: ecsFormat({ convertReqRes: true }), // 1
  transports: [
    new winston.transports.Console()
  ]
});
 
const server = http.createServer(handler);
server.listen(3000, () => {
  logger.info('listening at http://localhost:3000')
});
 
function handler (req, res) {
  res.setHeader('Foo', 'Bar');
  res.end('ok');
  logger.info('handled request', { req, res }); // 2
}

Χρησιμοποιήστε την επιλογή convertReqRes
Καταγράψτε τα μεταπεδία απαίτησης και/ή res

Αυτό θα χρησιμοποιήσει Πεδία HTTP ECS Δημιουργεί ένα αρχείο καταγραφής που περιέχει πληροφορίες αιτημάτων και απαντήσεων.Για παράδειγμαπαράδειγμα：

Πάνω, πρέπει να έχουμε πρόσβαση http://localhost:3000 Μόνο τότε μπορείτε να δείτε τις πληροφορίες ημέρας που εμφανίζονται παραπάνω.

Χρησιμοποιήστε το APM για συσχέτιση αρχείων καταγραφής

Αυτό ECS μορφοποιητής αρχείων καταγραφής μεΕλαστικό APM ολοκληρωμένο.Εάν η εφαρμογή Node σας χρησιμοποιείNode.js Elastic APM Agent, πολλά πεδία προστίθενται στην εγγραφή αρχείου καταγραφής για να συσχετίσουν την υπηρεσία APM ή τα δεδομένα παρακολούθησης και καταγραφής:

Οι δηλώσεις καταγραφής (όπως το logger.info(...)) που καλούνται κατά την τρέχουσα ανίχνευση ενός εύρους θα περιλαμβάνουνπεδία παρακολούθησης— trace.id,transaction.id,span.id.
Πολλαπλά πεδία αναγνωριστικού υπηρεσίας, που καθορίζονται ή έχουν ρυθμιστεί στον πράκτορα APM, επιτρέπουν τη διασύνδεση μεταξύ υπηρεσιών και αρχείων καταγραφής στο Kibana — service.name, service.version, service.environment, service.node.name.
Το event.dataset είναι ενεργοποιημένο σε εφαρμογές Elastic ObservabilityΑνίχνευση ανωμαλίας ρυθμού καταγραφής。

Για παράδειγμα, τρέξτε παραδείγματα/http-with-elastic-apm.js καιcurl -i localhost:3000/ Παράγεται ένα αρχείο καταγραφής που περιέχει το ακόλουθο περιεχόμενο:


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

Αυτά τα αναγνωριστικά ταιριάζουν με τα δεδομένα παρακολούθησης που αναφέρονται από τον πράκτορα APM.

Η ενσωμάτωση με το Elastic APM μπορεί να απενεργοποιηθεί ρητά μέσω της επιλογής apmIntegration: false, για παράδειγμα:


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

Περιορισμοί και Σημειώσεις

προδιαγραφή ecs-logging Συνιστάται τα τρία πρώτα πεδία στην εγγραφή καταγραφής να είναι @timestamp, log.level και message. Ξεκινώντας με την έκδοση 1.5.0, αυτός ο μορφοποιητής δεν ακολουθεί αυτήν τη σύσταση. Αυτό είναι δυνατό, αλλά απαιτεί τη δημιουργία ενός νέου αντικειμένου στο ecsFields για κάθε εγγραφή καταγραφής. Δεδομένου ότι η σειρά των πεδίων ecs-logging είναι για αναγνωσιμότητα και δεν επηρεάζει τη διαλειτουργικότητα, αποφασίστηκε να δοθεί προτεραιότητα στην απόδοση.

αναφέρομαι σε

ecsFormat([επιλογές])

επιλογές {type-object} υποστηρίζει τις ακόλουθες επιλογές:
- convertErr {type-boolean} Εάν θα μετατραπεί το πεδίο err της εγγραφής στο πεδίο σφάλματος ECS.Προεπιλεγμένη τιμή:αληθής.
- convertReqRes {type-boolean} Εάν θα καταγραφούν τα πεδία αιτήματος και απάντησης HTTP req και res στα πεδία 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} θα παρακαμφθεί.

Δημιουργήστε έναν μορφοποιητή για το winston που εκπέμπει μορφή καταγραφής ECS.Αυτή είναι μια θεραπείαecsFields([επιλογές]) καιecsStringify([επιλογές]) ενιαία μορφή. Τα ακόλουθα δύο είναι ισοδύναμα:


const { ecsFormat, ecsFields, ecsStringify } = require('@elastic/ecs-winston-format');
const winston = require('winston');
 
const logger = winston.createLogger({
  format: ecsFormat(/* options */),
  // ...
});
 
const logger = winston.createLogger({
  format: winston.format.combine(
    ecsFields(/* options */),
    ecsStringify()
  ),
  // ...
});

ecsFields([επιλογές])

επιλογές {type-object} υποστηρίζει τις ακόλουθες επιλογές:
- convertErr {type-boolean} Εάν θα μετατραπεί το πεδίο err της εγγραφής στο πεδίο σφάλματος ECS.Προεπιλεγμένη τιμή:αληθής.
- convertReqRes {type-boolean} Εάν θα καταγραφούν τα πεδία αιτήματος και απάντησης HTTP req και res στα πεδία 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} θα παρακαμφθεί.

Δημιουργήστε έναν μορφοποιητή για το winston που μετατρέπει τα πεδία στο αντικείμενο πληροφοριών καταγραφής σε μορφή καταγραφής ECS.

ecsStringify([επιλογές])

Δημιουργήστε έναν μορφοποιητή για το winston για τη συμβολοσειοποίηση/σειριοποίηση εγγραφών καταγραφής σε JSON.

Αυτό είναι παρόμοιο με το logform.json(). Και οι δύο χρησιμοποιούν το πακέτο safe-stable-stringify για να δημιουργήσουν JSON. Μερικές διαφορές:

Αυτός ο συμβολοσειριστής παραλείπει τη σειριοποίηση του πεδίου επιπέδου επειδή δεν είναι πεδίο ECS.
Η Winston παρέχει έναν αντικαταστάτη που μετατρέπει το bigint σε συμβολοσειρά. Ο λόγος για αυτό είναι ότι ο αναλυτής JSON JavaScript χάνει την ακρίβεια κατά την ανάλυση bigints. Η ένσταση είναι ότι το BigInt αλλάζει τον τύπο σε συμβολοσειρά αντί για αριθμό. Επί του παρόντος, αυτός ο συμβολοσειρωτής δεν μετατρέπει το BitInt σε συμβολοσειρά.

Κοινή χρήση τεχνολογίας