Technologieaustausch

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

Dies ist eine Fortsetzung des vorherigen Artikels „Elasticsearch: Node.js ECS-Protokollierung – Pino” Fortsetzung von. Wir setzen den vorherigen Artikel fort, um über die Verwendung des Winston-Pakets zum Zielen zu sprechen Node.js Die Anwendung generiert ECS passend zum Tag.Dieses Node.js-Paket istWinston LoggerEin Formatierer wird mitgeliefert ECS-Protokollierung (Elastic Common Schema). kompatibel.kombinierenFilebeat Absender können Sie alle Protokolle von einem Ort im Elastic Stack aus überwachen. Unterstützt Winston 3.x-Version >=3.3.3.

aufstellen

Installieren

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

Aufbau

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') });

• Übergeben Sie den ECS-Formatierer an Winston.

Das Ergebnis der Ausführung des obigen Codes ist:

Konfigurieren Sie 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: ~

1. Verwenden Sie die Filestream-Eingabe, um Zeilen aus einer aktiven Protokolldatei zu lesen.
2. Wenn ein Konflikt auftritt, überschreiben die Werte des dekodierten JSON-Objekts die Felder, die Filebeat normalerweise hinzufügt (Typ, Quelle, Offset usw.).
3. Wenn ein JSON-Unmarshalling-Fehler auftritt, fügt Filebeat die Schlüssel „error.message“ und „error.type: json“ hinzu.
4. Filebeat entfernt rekursiv die Punkttasten aus dem dekodierten JSON und erweitert es in eine hierarchische Objektstruktur.
5. Prozessoren verbessern Ihre Daten.SehenProzessoren um mehr zu lernen.

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: ~

Weitere Informationen finden Sie unter Filebeat-Referenz。

wie benutzt man

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' });

1. Verfügbare Optionen finden Sie weiter unten.

node winston-logging.js | jq .

Führen Sie dieses Skript aus (verfügbar unterHiererhalten) erzeugt eine Protokollausgabe ähnlich der oben genannten.

Der Formatierer ist für die Serialisierung der Daten in JSON verantwortlich, sodass Sie ihn nicht hinzufügen müssen json Formatierer.Darüber hinaus generiert der Formatierer automatisch den Zeitstempel, sodass Sie ihn nicht hinzufügen müssenZeitstempel Formatierer.

Fehlerprotokollierung

Standardmäßig konvertiert der Formatierer das err-Metafeld einer Error-Instanz in ECSError-Feld .Zum BeispielBeispiel：

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 }); 

Die spezielle Behandlung des err-Metafelds kann über die Option „convertErr: false“ deaktiviert werden:

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 }); 

Protokollierung von HTTP-Anfragen und -Antworten

Mit der Option „convertReqRes: true“ konvertiert der Formatierer automatisch den Node.js-Kern, wenn er als req- bzw. res-Metafelder übergeben wird. Anfrage UndAntwort Objekt.

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
}

1. Verwenden Sie die Option „convertReqRes“.
2. Erfassen Sie die Metafelder „req“ und/oder „res“.

Dies wird verwendet ECS-HTTP-Felder Erstellt ein Protokoll mit Anforderungs- und Antwortinformationen.Zum BeispielBeispiel：

Oben müssen wir zugreifen http://localhost:3000 Erst dann können Sie die oben angezeigten Tagesinformationen sehen.

Verwenden Sie APM für die Protokollkorrelation

Das ECS Protokollformatierer mitElastisches APM integriert.Wenn Ihre Node-Anwendung verwendetElastischer APM-Agent von Node.js, werden dem Protokolldatensatz mehrere Felder hinzugefügt, um den APM-Dienst oder die Trace- und Protokolldaten zu korrelieren:

• Protokollanweisungen (z. B. logger.info(...)), die beim aktuellen Verfolgen einer Spanne aufgerufen werden, umfassenTracking-Felder— trace.id, transaction.id, span.id.
• Mehrere Service-ID-Felder, die vom APM-Agenten bestimmt oder konfiguriert werden, ermöglichen die Vernetzung zwischen Services und Protokollen in Kibana – service.name, service.version, service.environment, service.node.name.
• event.dataset ist in Elastic Observability-Anwendungen aktiviertErkennung von Protokollratenanomalien。

Zum Beispiel laufen Beispiele/http-mit-elastic-apm.js Undcurl -i localhost:3000/ Es wird ein Protokollsatz mit folgendem Inhalt erstellt:

% 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"
}

Diese IDs stimmen mit den vom APM-Agenten gemeldeten Tracking-Daten überein.

Die Integration mit Elastic APM kann explizit über die Option apmIntegration: false deaktiviert werden, zum Beispiel:

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

Einschränkungen und Hinweise

ECS-Logging-Spezifikation Es wird empfohlen, dass die ersten drei Felder im Protokolldatensatz @timestamp, log.level und message sein sollten. Ab Version 1.5.0 folgt dieser Formatierer dieser Empfehlung nicht mehr. Dies ist möglich, erfordert jedoch die Erstellung eines neuen Objekts in ecsFields für jeden Protokolldatensatz. Da die Reihenfolge der ECS-Logging-Felder der Lesbarkeit dient und die Interoperabilität nicht beeinträchtigt, wurde beschlossen, der Leistung Priorität einzuräumen.

beziehen auf

ecsFormat([Optionen])

• Optionen {type-object} unterstützt die folgenden Optionen:
  • convertErr {type-boolean} Gibt an, ob das Fehlerfeld des Datensatzes in das ECS-Fehlerfeld konvertiert werden soll.Standardwert:WAHR.
  • ConvertReqRes {type-boolean} Gibt an, ob die HTTP-Anforderungs- und Antwortfelder „req“ und „res“ in den ECS-HTTP-, User-Agent- und URL-Feldern protokolliert werden sollen.Standardwert:FALSCH.
  • apmIntegration {type-boolean} Ob die APM-Agent-Integration aktiviert werden soll.Standardwert:WAHR.
  • serviceName {type-string} „service.name“-Wert. Wenn angegeben, wird jeder Wert des aktiven APM-Agenten überschrieben.
  • serviceVersion {type-string} „service.version“-Wert. Wenn angegeben, wird jeder Wert des aktiven APM-Agenten überschrieben.
  • serviceEnvironment {type-string} „service.environment“-Wert. Wenn angegeben, wird jeder Wert des aktiven APM-Agenten überschrieben.
  • serviceNodeName {type-string} „service.node.name“-Wert. Wenn angegeben, wird jeder Wert vom aktiven APM-Agenten überschrieben.
  • eventDataset {type-string} „event.dataset“-Wert. Wenn angegeben, wird der Standardwert der Verwendung von ${serviceVersion} überschrieben.

Erstellen Sie einen Formatierer für Winston, der das ECS-Protokollierungsformat ausgibt.Dies ist eine BehandlungecsFields([Optionen]) UndecsStringify([Optionen]) Einzelformat. Die folgenden beiden sind gleichwertig:

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([Optionen])

• Optionen {type-object} unterstützt die folgenden Optionen:
  • convertErr {type-boolean} Gibt an, ob das Fehlerfeld des Datensatzes in das ECS-Fehlerfeld konvertiert werden soll.Standardwert:WAHR.
  • ConvertReqRes {type-boolean} Gibt an, ob die HTTP-Anforderungs- und Antwortfelder „req“ und „res“ in den ECS-HTTP-, User-Agent- und URL-Feldern protokolliert werden sollen.Standardwert:FALSCH.
  • apmIntegration {type-boolean} Ob die APM-Agent-Integration aktiviert werden soll.Standardwert:WAHR.
  • serviceName {type-string} „service.name“-Wert. Wenn angegeben, wird jeder Wert des aktiven APM-Agenten überschrieben.
  • serviceVersion {type-string} „service.version“-Wert. Wenn angegeben, wird jeder Wert des aktiven APM-Agenten überschrieben.
  • serviceEnvironment {type-string} „service.environment“-Wert. Wenn angegeben, wird jeder Wert des aktiven APM-Agenten überschrieben.
  • serviceNodeName {type-string} „service.node.name“-Wert. Wenn angegeben, wird jeder Wert vom aktiven APM-Agenten überschrieben.
  • eventDataset {type-string} „event.dataset“-Wert. Wenn angegeben, wird die Standardeinstellung der Verwendung von ${serviceVersion} überschrieben.

Erstellen Sie einen Formatierer für Winston, der die Felder im Protokollierungsinformationsobjekt in das ECS-Protokollierungsformat konvertiert.

ecsStringify([Optionen])

Erstellen Sie einen Formatierer für Winston, um Protokolldatensätze in JSON zu stringifizieren/serialisieren.

Dies ähnelt logform.json(). Beide verwenden das Paket „safe-stable-stringify“, um JSON zu generieren. Einige Unterschiede:

• Dieser Stringifizierer überspringt die Serialisierung des Ebenenfelds, da es sich nicht um ein ECS-Feld handelt.
• Winston stellt einen Ersatz bereit, der Bigint in String umwandelt. Der Grund dafür ist, dass der JavaScript-JSON-Parser beim Parsen von Bigints an Präzision verliert. Der Einwand besteht darin, dass BigInt den Typ in einen String statt in eine Zahl ändert. Derzeit konvertiert dieser Stringifier BitInt nicht in einen String.