Skip to content

Latest commit

 

History

History
275 lines (209 loc) · 9.99 KB

CHANGELOG.md

File metadata and controls

275 lines (209 loc) · 9.99 KB
Raw

@elastic/ecs-winston-format Changelog

v1.5.3

  • Fix format handling for the log record emitted by Winston for unhandledRejection events (when configured to handle them) as of [email protected]. In that version the log record changed slightly to set record.rejection rather than record.exception.

v1.5.2

v1.5.0

  • Add ecsFields and ecsStringify exports that are winston formatters that separate the gathering of ECS fields (ecsFields) and the stringification of a log record to an ecs-logging JSON object (ecsStringify). This allows for better composability using winston.format.combine.

    The preferred way to import now changes to:

    const { ecsFormat } = require('@elastic/ecs-winston-format'); // CommonJS
import { ecsFormat } from '@elastic/ecs-winston-format'; // ESM

    The old way will be deprecated and removed in the future:

    const ecsFormat = require('@elastic/ecs-winston-format'); // OLD

    Typical usage of ecsFormat is unchanged:

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

    However, one can now use the separated formatters as follows:

    const { ecsFields, ecsStringify } = require('@elastic/ecs-winston-format');
const log = winston.createLogger({
    format: winston.format.combine(
        ecsFields(/* options */),
        // Add any custom formatters, e.g. one to redact added ECS fields.
        ecsStringify()
    ),
    // ...

    One good use case is for redaction of sensitive fields in the log record as in #57. See a complete example at examples/redact-fields.js.

  • Fix/improve serialization of error details to error.* fields for the various ways a Winston logger handles Error instances.

    const aCause = new Error('the cause');
const anErr = new Error('boom', {cause: aCause});
anErr.code = 42;

log.debug("some message", anErr); // Form 1
log.info(anErr, {foo: "bar"}); // Form 2
log.warn("some message", {err: anErr, foo: "bar"}); // Form 3
    1. Winston will add a stack field for an error passed this way.
    2. If the logform.errors(...) format is configured, Winston will serialize anErr passed this way.
    3. Passing an error via the err meta field is specific to @elastic/ecs-winston-format and is discouraged. If possible, use style 1. It will remain for now for backward compatibility.

    With this change, all three cases above will result in anErr details being serialized to ECS error.* fields, as well as error.cause and other properties on the error instance. Forms 2 and 3 are enabled via the convertErr: true configuration option. See examples/basic.js.

    In addition, if your Winston logger is configured to handle uncaughtException and/or unhandledRejection (https://github.com/winstonjs/winston#exceptions), then the Error instance included in this log record will be serialized to error.* fields. See test/uncaught-exception.js and test/unhandled-rejection.js for examples. (#128)

  • Switch to safe-stable-stringify for JSON serialization. This library protects against circular references and bigints. (#155)

  • Explicitly depend on triple-beam (>=1.1.0 when MESSAGE was added). Before this change, this package was assuming that it would be installed by the user. This worked for npm's flat install -- npm install winston will install a node_modules/triple-beam/... -- but not for Yarn 2's PnP install mechanism. (#108)

  • Set http.request.id field (see ecs-helpers CHANGELOG).

  • Add support for default import in TypeScript, with or without the esModuleInterop setting:

    import ecsFormat from '@elastic/ecs-pino-format';

    However, note that using named imports is now preferred.

v1.4.0

  • Add service.version, service.environment, and service.node.name log correlation fields, automatically inferred from an active APM agent. As well, the following ecsFormat configuration options have been added for overriding these and existing correlation fields: serviceName, serviceVersion, serviceEnvironment, serviceNodeName. (elastic/apm-agent-nodejs#3195, #121, #87)

  • Change to adding dotted field names ("ecs.version": "1.6.0"), rather than namespaced fields ("ecs": {"version": "1.6.0"}) for most fields. This is supported by the ecs-logging spec, and arguably preferred in the ECS logging docs. It is also what the ecs-logging-java libraries do. The resulting output is slightly shorter, and accidental collisions with user fields is less likely.

  • Stop adding ".log" suffix to event.dataset field. (#95)

v1.3.1

  • Fix types expression in ambient context error. (#93)

v1.3.0

  • TypeScript types. (#88)

v1.1.0

  • Fix a crash (#58) when using APM integration and logging a record with an "event" or "service" top-level field that isn't an object. The "fix" here is to silently discard that "event" or "service" field because a non-object conflicts with the ECS spec for those fields. (See #68 for a discussion of the general ECS type conflict issue.)

  • Fix a crash (#59) when using convertReqRes: true and logging a res field that is not an HTTP response object.

  • Add apmIntegration: false option to all ecs-logging formatters to enable explicitly disabling Elastic APM integration. (#62)

  • Fix "elasticApm.isStarted is not a function" crash on startup. (#60)

v1.0.0

  • Update to @elastic/[email protected]: ecs.version is now "1.6.0", http.request.method is no longer lower-cased, improvements to HTTP serialization.

  • Add error logging feature. By default if an Error instance is passed as the err meta field, then it will be converted to ECS Error fields, e.g.:

    logger.info('oops', { err: new Error('boom') })

    yields:

    {
  "@timestamp": "2021-01-26T17:25:07.983Z",
  "log.level": "info",
  "message": "oops",
  "ecs": {
    "version": "1.5.0"
  },
  "error": {
    "type": "Error",
    "message": "boom",
    "stack_trace": "Error: boom\n    at Object.<anonymous> (..."
  }
}

    This special handling of the err meta field can be disabled via the convertErr: false formatter option.

  • Set "service.name" and "event.dataset" log fields if Elastic APM is started. This helps to filter for different log streams in the same pod and the latter is required for log anomaly detection. (#41)

  • Add support for ECS tracing fields. If it is detected that Elastic APM is in use and there is an active trace, then tracing fields will be added to log records. This enables linking between traces and log records in Kibana. (#35)

  • Fix guarding of the top-level 'log' and 'log.level' fields. A log statement can now set 'log' fields e.g.:

    log.info('hi', { log: { logger: 'myService' } })

    Also 'log.level' can now not accidentally be overwritten in a log statement.

  • BREAKING CHANGE: Conversion of HTTP request and response objects is no longer done by default. One must use the new convertReqRes: true formatter option. As well, only the meta keys req and res will be handled. Before this change the meta keys req, res, request, and response would all be handled. (#32)

    Before (no longer works):

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

http.createServer(function handler (request, response) {
  // ...
  logger.info('handled request', { request, response })
})

    After:

    const logger = winston.createLogger({
  format: ecsFormat({convertReqRes: true}),  // <-- specify convertReqRes option
  // ...
})

http.createServer(function handler (req, res) {
  // ...
  logger.info('handled request', { req, res })  // <-- only `req` and `res` are special
})

v0.3.0

v0.2.0

  • Use the version number provided by ecs-helpers - #13

v0.1.0

Initial release.