### Install @elastic/ecs-morgan-format

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/README.md

Install the package using npm.

```sh
npm install @elastic/ecs-morgan-format
```

--------------------------------

### Install ECS Pino Formatter

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

Install the necessary package using npm.

```cmd
$ npm install @elastic/ecs-pino-format
```

--------------------------------

### Install @elastic/ecs-pino-format

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-pino-format/README.md

Install the package using npm.

```sh
npm install @elastic/ecs-pino-format
```

--------------------------------

### Install ECS Morgan Formatter

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/morgan.md

Install the @elastic/ecs-morgan-format package using npm.

```bash
$ npm install @elastic/ecs-morgan-format
```

--------------------------------

### Install and Test with Make (Older Node.js)

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/CONTRIBUTING.md

For Node.js versions earlier than v10, use 'make all' to install dependencies and 'make test' to run tests.

```bash
make all
make test
```

--------------------------------

### Install @elastic/ecs-winston-format

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/README.md

Install the package using npm.

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

--------------------------------

### Install @elastic/ecs-helpers

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-helpers/README.md

Install the package using npm.

```sh
npm install @elastic/ecs-helpers
```

--------------------------------

### Install ECS Winston Formatter

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Install the `@elastic/ecs-winston-format` package using npm.

```cmd
$ npm install @elastic/ecs-winston-format
```

--------------------------------

### Winston ECS Format with APM Integration Example

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

This example shows the output of a log record when running with the http-with-elastic-apm.js example and curl. It includes service identifiers and tracing fields for correlation.

```json
{
  "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"
}
```

--------------------------------

### Install Dependencies with npm Workspaces

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/CONTRIBUTING.md

Use this command to install all dependencies for all packages within the 'packages/' directory when using npm workspaces.

```bash
npm --workspaces install
```

--------------------------------

### Basic Usage of ecsFormat with Pino

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-pino-format/README.md

Configure Pino with ecsFormat to enable ECS logging. This example shows basic info and child logger usage.

```js
const { ecsFormat } = require('@elastic/ecs-pino-format')
const pino = require('pino')

const log = pino(ecsFormat(/* options */))
log.info('Hello world')

const child = log.child({ module: 'foo' })
child.warn('From child')
```

--------------------------------

### Example ECS Log Output

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/README.md

Demonstrates the expected JSON output format for logs generated by the ecs-winston-format.

```sh
% node examples/basic.js
{"@timestamp":"2021-01-13T21:32:38.095Z","log.level":"info","message":"hi","ecs":{"version":"8.10.0"}}
{"@timestamp":"2021-01-13T21:32:38.096Z","log.level":"error","message":"oops there is a problem","ecs":{"version":"8.10.0"},"foo":"bar"}
```

--------------------------------

### Basic ECS Pino Format Setup

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Configure Pino to output ECS-compliant JSON logs. Supports Pino 6.x, 7.x, and 8.x. Options like `convertErr`, `convertReqRes`, `apmIntegration`, and service metadata can be set.

```javascript
const { ecsFormat } = require('@elastic/ecs-pino-format')
const pino = require('pino')

// Basic usage
const log = pino(ecsFormat())
log.info('Hello world')
// {"log.level":"info","@timestamp":"2023-10-16T18:08:02.601Z","process.pid":74325,"host.hostname":"pink.local","ecs.version":"8.10.0","message":"Hello world"}
```

```javascript
// Child logger inherits ECS bindings
const child = log.child({ module: 'auth' })
child.warn('invalid token')
// {"log.level":"warn",...,"module":"auth","message":"invalid token"}
```

```javascript
// Error conversion (default on): err field → ECS error.* fields
const log2 = pino(ecsFormat())
log2.error({ err: new RangeError('out of bounds') }, 'caught error')
// { ..., "error": { "type": "RangeError", "message": "out of bounds", "stack_trace": "..." }, "message": "caught error" }
```

```javascript
// HTTP request+response logging
const http = require('http')
const log3 = pino(ecsFormat({ convertReqRes: true }))
http.createServer(function (req, res) {
  res.setHeader('X-Custom', 'yes')
  res.end('ok')
  log3.info({ req, res }, 'handled request')
  // produces full http.*, url.*, client.*, user_agent.* ECS fields
}).listen(3000)
```

```javascript
// With service metadata (overrides APM agent values if present)
const log4 = pino(ecsFormat({
  serviceName: 'my-api',
  serviceVersion: '2.3.1',
  serviceEnvironment: 'production'
}))
log4.info('started')
// { ..., "service.name": "my-api", "service.version": "2.3.1", "service.environment": "production", ... }
```

```javascript
// Disable APM integration explicitly
const log5 = pino(ecsFormat({ apmIntegration: false }))
```

--------------------------------

### Basic Morgan ECS Integration

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/morgan.md

Use `morgan` with `ecsFormat` to log HTTP requests in ECS format. Ensure `morgan` and `@elastic/ecs-morgan-format` are installed. Available options for `ecsFormat` can be found in the reference section.

```javascript
const app = require('express')();
const morgan = require('morgan');
const { ecsFormat } = require('@elastic/ecs-morgan-format');

app.use(morgan(ecsFormat(/* options */))); 

app.get('/', function (req, res) {
  res.send('hello, world!');
})
app.get('/error', function (req, res, next) {
  next(new Error('boom'));
})

app.listen(3000)
```

--------------------------------

### Example ECS Log Output

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-pino-format/README.md

Demonstrates the typical JSON output format generated by ecsFormat for different log levels and contexts.

```json
{"log.level":"info","@timestamp":"2023-10-16T18:08:02.601Z","process.pid":74325,"host.hostname":"pink.local","ecs.version":"8.10.0","message":"Hello world"}
{"log.level":"warn","@timestamp":"2023-10-16T18:08:02.602Z","process.pid":74325,"host.hostname":"pink.local","ecs.version":"8.10.0","module":"foo","message":"From child"}
```

--------------------------------

### Basic Usage with Express

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/README.md

Integrate the ecsFormat formatter with the morgan middleware in an Express application. This setup will log requests in ECS format.

```js
const app = require('express')()
const morgan = require('morgan')
const { ecsFormat } = require('@elastic/ecs-morgan-format')

app.use(morgan(ecsFormat(/* options */)))

app.get('/', function (req, res) {
  res.send('hello, world!')
})

app.listen(3000)
```

--------------------------------

### Minimal ECS Log Record Example

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/index.md

A basic example of a log record formatted according to the ECS specification. This structure is essential for consistent log analysis across different systems.

```json
{
  "@timestamp": "2021-01-13T21:32:38.095Z",
  "log.level": "info",
  "message": "hi",
  "ecs.version": "8.10.0"
}
```

--------------------------------

### Example ECS Log Output

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/README.md

This is an example of the structured log output generated by the ecsFormat formatter when a request is made to the Express application. It is piped to `jq` for pretty-printing.

```sh
% node examples/express.js | jq .  # piping to jq for pretty-printing
{
  "@timestamp": "2023-10-16T22:00:33.782Z",
  "log.level": "info",
  "message": "::ffff:127.0.0.1 - - [16/Oct/2023:22:00:33 +0000] \"GET / HTTP/1.1\" 200 13 \"-\" \"curl/8.1.2\"",
  "http": {
    "version": "1.1",
    "request": {
      "method": "GET",
      "headers": {
        "host": "localhost:3000",
        "user-agent": "curl/8.1.2",
        "accept": "*/*"
      }
    },
    "response": {
      "status_code": 200,
      "headers": {
        "x-powered-by": "Express",
        "content-type": "text/html; charset=utf-8",
        "content-length": "13",
        "etag": "W/\"d-HwnTDHB9U/PRbFMN1z1wps51lqk\""
      },
      "body": {
        "bytes": 13
      }
    }
  },
  "url": {
    "path": "/",
    "domain": "localhost",
    "full": "http://localhost:3000/"
  },
  "client": {
    "address": "::ffff:127.0.0.1",
    "ip": "::ffff:127.0.0.1",
    "port": 60455
  },
  "user_agent": {
    "original": "curl/8.1.2"
  },
  "ecs.version": "8.10.0"
}
```

--------------------------------

### ECS Winston Format with APM Integration

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

This example shows how to create a Winston logger that formats logs in ECS format and integrates with Elastic APM. When APM is active, tracing and service fields are automatically added to log records.

```APIDOC
## Log Correlation with APM [winston-apm]

This ECS log formatter integrates with [Elastic APM](https://www.elastic.co/apm). If your Node app is using the [Node.js Elastic APM Agent](apm-agent-nodejs://reference/index.md), then a number of fields are added to log records to correlate between APM services or traces and logging data:

* Log statements (e.g. `logger.info(...)`) called when there is a current tracing span will include [tracing fields](ecs://reference/ecs-tracing.md) — `trace.id`, `transaction.id`, `span.id`.
* A number of service identifier fields determined by or configured on the APM agent allow cross-linking between services and logs in Kibana — `service.name`, `service.version`, `service.environment`, `service.node.name`.
* `event.dataset` enables [log rate anomaly detection](docs-content://solutions/observability/logs/inspect-log-anomalies.md) in the Elastic Observability app.

For example, running [examples/http-with-elastic-apm.js](https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/examples/http-with-elastic-apm.js) and `curl -i localhost:3000/` results in a log record with the following:

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

These IDs match trace data reported by the APM agent.

Integration with Elastic APM can be explicitly disabled via the `apmIntegration: false` option, for example:

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

--------------------------------

### Configure Pino with ECS Formatter

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

Configure Pino to use the ecs-pino-format package. This sets up Pino's formatters, messageKey, and timestamp options for ECS compliance. Example logs demonstrate basic info and error logging.

```js
const { ecsFormat } = require('@elastic/ecs-pino-format');
const pino = require('pino');

const log = pino(ecsFormat(/* options */)); 
log.info('hi');
log.error({ err: new Error('boom') }, 'oops there is a problem');
// ...
```

--------------------------------

### Basic Winston Logger with ECS Format

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/README.md

Configure a Winston logger to use the ecsFormat for structured logging. This setup is suitable for general application logging.

```js
const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');

const logger = winston.createLogger({
  level: 'info',
  format: ecsFormat(/* options */),
  transports: [
    new winston.transports.Console()
  ]
});

logger.info('hi');
logger.error('oops there is a problem', { foo: 'bar' });
```

--------------------------------

### Filebeat Configuration for ECS Logs (< 7.16)

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

Configure Filebeat's log input for ECS-formatted JSON logs. This setup uses `json_keys_under_root`, `json.overwrite_keys`, `json.add_error_key`, and `json.expand_keys` for parsing.

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

--------------------------------

### Example Log Output with APM Integration

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

When Elastic APM is integrated, log records include tracing and service identifier fields for correlation. These fields match data reported by the APM agent.

```cmd
% 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": "9f338eae7211b7993b98929046aed21d",
  "transaction.id": "2afbef5642cc7a3f",
...
```

--------------------------------

### Configure Winston Logger with ECS Format

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Configure a Winston logger to use the ECS formatter. Pass the `ecsFormat` function to the logger's format option. This setup is for Node.js applications.

```js
const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston-format');

const logger = winston.createLogger({
  format: ecsFormat(/* options */),
  transports: [
    new winston.transports.Console()
  ]
});

logger.info('hi');
logger.error('oops there is a problem', { err: new Error('boom') });
```

--------------------------------

### Express Request/Response Logging with ecsFormat

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Integrate ECS logging into an Express application using `ecsFormat({ convertReqRes: true })`. This setup includes middleware for logging requests and errors, ensuring that request and response details are captured in ECS format.

```javascript
const { ecsFormat } = require('@elastic/ecs-winston-format')
const express = require('express')
const winston = require('winston')

const logger = winston.createLogger({
  format: ecsFormat({ convertReqRes: true }),
  transports: [new winston.transports.Console()]
})

function requestLogger (opts) {
  return function (req, res, next) {
    function onResDone (err) {
      this.removeListener('finish', onResDone)
      this.removeListener('error', onResDone)
      opts.logger.info(`handled ${req.method} ${req.path}`, { req, res, err })
    }
    res.on('finish', onResDone)
    res.on('error', onResDone)
    next()
  }
}

function errorLogger (opts) {
  return function (err, req, _res, next) {
    opts.logger.warn(`error on ${req.method} ${req.path}`, { err })
    next(err)
  }
}

const app = express()
app.use(requestLogger({ logger }))

app.get('/', (req, res) => { res.setHeader('Foo', 'Bar'); res.end('hi') })
app.get('/error', (req, res, next) => next(new Error('boom')))

app.use(errorLogger({ logger }))   // error loggers must come last
app.listen(3000, () => logger.info('listening at http://localhost:3000'))
```

--------------------------------

### ecsFormat([options])

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/morgan.md

Create a formatter for morgan that emits in ECS Logging format. This function takes an optional `options` object to customize the ECS log output.

```APIDOC
## `ecsFormat([options])`

### Description
Create a formatter for morgan that emits in ECS Logging format.

### Parameters
#### Options Object
- **format** (string) - Optional - A format **name** (e.g. *combined*), format function (e.g. `morgan.combined`), or a format string (e.g. *:method :url :status*). This is used to format the "message" field. Defaults to `morgan.combined`.
- **convertErr** (boolean) - Optional - Whether to convert a logged `err` field to ECS error fields. **Default:** `true`.
- **apmIntegration** (boolean) - Optional - Whether to enable APM agent integration. **Default:** `true`.
- **serviceName** (string) - Optional - A "service.name" value. If specified this overrides any value from an active APM agent.
- **serviceVersion** (string) - Optional - A "service.version" value. If specified this overrides any value from an active APM agent.
- **serviceEnvironment** (string) - Optional - A "service.environment" value. If specified this overrides any value from an active APM agent.
- **serviceNodeName** (string) - Optional - A "service.node.name" value. If specified this overrides any value from an active APM agent.
- **eventDataset** (string) - Optional - A "event.dataset" value. If specified this overrides the default of using `${serviceVersion}`.
```

--------------------------------

### Create Winston Logger with ecsFormat

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Shows how to create a Winston logger instance using the ecsFormat function, which handles both ecsFields and ecsStringify.

```javascript
const { ecsFormat } = require('@elastic/ecs-winston-format');
const winston = require('winston');

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

```

--------------------------------

### Manual npm Publish for Format Packages

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/RELEASING.md

Manually publish one or more format packages to npm. Ensure the working tree is clean before proceeding. This is a fallback if automation fails.

```bash
git status              # this should show "working tree clean"

# for each of the packages being released:
cd packages/ecs-...-format
npm publish
```

--------------------------------

### Get ECS Version from @elastic/ecs-helpers

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Access the supported ECS specification version as a string constant. This is used internally to stamp `ecs.version` on log records.

```javascript
const { version } = require('@elastic/ecs-helpers')
console.log(version) // '8.10.0'
```

--------------------------------

### Integration with pino-http and Express

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Shows how to combine ecsFormat with pino-http for automatic per-request logging in Express applications.

```APIDOC
## Integration with `pino-http` and Express

Combining `ecsFormat` with [pino-http](https://github.com/pinojs/pino-http) gives automatic per-request logging in Express while keeping full ECS HTTP fields.

```js
const { ecsFormat } = require('@elastic/ecs-pino-format')
const express = require('express')
const pino = require('pino')
const pinoHttp = require('pino-http')

const log = pino(ecsFormat({ convertReqRes: true }))
const app = express()

app.use(pinoHttp({ logger: log }))

app.get('/', function (req, res) {
  res.setHeader('Foo', 'Bar')
  res.end('hi')
  req.log.info('handled GET /')  // per-request child logger
})

app.get('/error', function (req, res, next) {
  next(new Error('boom'))
})

app.listen(3000, () => log.info('listening at http://localhost:3000'))
// curl http://localhost:3000/ → ECS record with http.*, url.*, client.* fields
```
```

--------------------------------

### Run Tests with npm Workspaces

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/CONTRIBUTING.md

Execute all tests across all packages in the repository using this command with npm workspaces.

```bash
npm --workspaces test
```

--------------------------------

### ecsFormat([options])

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Returns a Pino options object that configures formatters, messageKey, and timestamp to produce ECS-compliant JSON log records. Supports Pino 6.x, 7.x, and 8.x.

```APIDOC
## ecsFormat([options])

### Description
Returns a Pino options object that configures `formatters`, `messageKey`, and `timestamp` to produce ECS-compliant JSON log records. Pino 6.x, 7.x, and 8.x are supported.

### Options
- `convertErr` (default `true`): Whether to convert error objects to ECS `error.*` fields.
- `convertReqRes` (default `false`): Whether to log HTTP request and response objects, populating ECS `http.*`, `url.*`, `client.*`, and `user_agent.*` fields.
- `apmIntegration` (default `true`): Whether to integrate with the Elastic APM agent.
- `serviceName`: The name of the service.
- `serviceVersion`: The version of the service.
- `serviceEnvironment`: The environment the service is running in.
- `serviceNodeName`: The name of the node the service is running on.
- `eventDataset`: The dataset name for the log events.

### Usage Examples

**Basic usage:**
```js
const { ecsFormat } = require('@elastic/ecs-pino-format')
const pino = require('pino')

const log = pino(ecsFormat())
log.info('Hello world')
// {"log.level":"info","@timestamp":"2023-10-16T18:08:02.601Z","process.pid":74325,"host.hostname":"pink.local","ecs.version":"8.10.0","message":"Hello world"}
```

**Child logger inherits ECS bindings:**
```js
const child = log.child({ module: 'auth' })
child.warn('invalid token')
// {"log.level":"warn",...,"module":"auth","message":"invalid token"}
```

**Error conversion (default on):**
```js
const log2 = pino(ecsFormat())
log2.error({ err: new RangeError('out of bounds') }, 'caught error')
// { ..., "error": { "type": "RangeError", "message": "out of bounds", "stack_trace": "..." }, "message": "caught error" }
```

**HTTP request+response logging:**
```js
const http = require('http')
const log3 = pino(ecsFormat({ convertReqRes: true }))
http.createServer(function (req, res) {
  res.setHeader('X-Custom', 'yes')
  res.end('ok')
  log3.info({ req, res }, 'handled request')
  // produces full http.*, url.*, client.*, user_agent.* ECS fields
}).listen(3000)
```

**With service metadata:**
```js
const log4 = pino(ecsFormat({
  serviceName: 'my-api',
  serviceVersion: '2.3.1',
  serviceEnvironment: 'production'
}))
log4.info('started')
// { ..., "service.name": "my-api", "service.version": "2.3.1", "service.environment": "production", ... }
```

**Disable APM integration explicitly:**
```js
const log5 = pino(ecsFormat({ apmIntegration: false }))
```
```

--------------------------------

### Configure Pino ECS Format Options

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

Create Pino logger options to configure the ECS Logging format output. Supported options include `convertErr`, `convertReqRes`, `apmIntegration`, and service-specific fields.

```js
const log = pino(ecsFormat({
  apmIntegration: true,
  serviceName: 'my-service',
  serviceVersion: '1.0.0',
  serviceEnvironment: 'production',
  serviceNodeName: 'node-1',
  eventDataset: 'my-app-logs'
}));
```

--------------------------------

### ecsFormat([options])

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Creates a composite Winston format that handles ECS field mapping and JSON serialization. Supports Winston 3.x (>=3.3.3). Options include convertErr, convertReqRes, apmIntegration, serviceName, serviceVersion, serviceEnvironment, serviceNodeName, eventDataset.

```APIDOC
## ecsFormat([options])

Creates a single composite Winston format that handles both ECS field mapping and JSON serialization. It is equivalent to `winston.format.combine(ecsFields(opts), ecsStringify())`. Winston 3.x (>=3.3.3) is supported. Options are identical to the Pino formatter: `convertErr`, `convertReqRes`, `apmIntegration`, `serviceName`, `serviceVersion`, `serviceEnvironment`, `serviceNodeName`, `eventDataset`.

```js
const winston = require('winston')
const { ecsFormat } = require('@elastic/ecs-winston-format')

const logger = winston.createLogger({
  level: 'info',
  format: ecsFormat(),
  transports: [
    new winston.transports.Console({
      handleExceptions: true,
      handleRejections: true
    })
  ]
})

logger.info('hi')
// {"@timestamp":"2023-10-14T02:14:17.302Z","log.level":"info","message":"hi","ecs.version":"8.10.0"}

logger.warn('look out', { foo: 'bar' })
// {"@timestamp":"...","log.level":"warn","message":"look out","ecs.version":"8.10.0","foo":"bar"}

// Error serialization — multiple calling styles all produce error.* ECS fields
const err = new Error('boom', { cause: new Error('the cause') })
err.code = 42
logger.error('here is an exception', err)
// { ..., "error": { "type": "Error", "message": "boom", "stack_trace": "...", "cause": "Error: the cause\n...", "code": 42 } }

// err meta field style
logger.info('oops', { err: new TypeError('bad value') })
// { ..., "error": { "type": "TypeError", "message": "bad value", "stack_trace": "..." } }

// HTTP request/response logging with Express
const { ecsFormat: ecsFmt } = require('@elastic/ecs-winston-format')
const expressLogger = winston.createLogger({
  format: ecsFmt({ convertReqRes: true }),
  transports: [new winston.transports.Console()]
})
// then: expressLogger.info('handled request', { req, res })
```
```

--------------------------------

### Filebeat Configuration for Log Files (7.16+)

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Configure Filebeat's filestream input to read ECS-formatted JSON logs from a file. This setup enables overwriting keys, adding error information on JSON unmarshalling errors, and expanding nested keys.

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

--------------------------------

### ecsStringify([options])

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Creates a formatter for Winston that stringifies/serializes the log record to JSON. This is similar to `logform.json()` but with specific differences for ECS compatibility.

```APIDOC
## `ecsStringify([options])`

### Description
Create a formatter for winston that stringifies/serializes the log record to JSON. This is similar to `logform.json()`. They both use the `safe-stable-stringify` package to produce the JSON.

Some differences:

* This stringifier skips serializing the `level` field, because it is not an ECS field.
* Winston provides a `replacer` that converts bigints to strings The argument **for** doing so is that a **JavaScript** JSON parser looses precision when parsing a bigint. The argument against is that a BigInt changes type to a string rather than a number. For now this stringifier does not convert BitInts to strings.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `options` `{type-object}` Options for the stringifier. (Specific options not detailed in source)

### Request Example
```javascript
const winston = require('winston');
const { ecsStringify } = require('@elastic/ecs-winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.errors({ stack: true }),
    ecsStringify()
  ),
  transports: [
    new winston.transports.Console()
  ]
});

logger.info('Application started');
logger.error(new Error('Something went wrong'));
```

### Response
#### Success Response (200)
Not applicable as this is a formatter function.

#### Response Example
Not applicable.
```

--------------------------------

### ecsFields([options])

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Creates a formatter for Winston that converts fields on the log record info object to ECS Logging format. It supports various options to customize the conversion process.

```APIDOC
## `ecsFields([options])`

### Description
Create a formatter for winston that converts fields on the log record info object to ECS Logging format.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `options` `{type-object}` The following options are supported:
    * `convertErr` `{type-boolean}` Whether to convert a logged `err` field to ECS error fields. **Default:** `true`.
    * `convertReqRes` `{type-boolean}` Whether to logged `req` and `res` HTTP request and response fields to ECS HTTP, User agent, and URL fields. **Default:** `false`.
    * `apmIntegration` `{type-boolean}` Whether to enable APM agent integration. **Default:** `true`.
    * `serviceName` `{type-string}` A "service.name" value. If specified this overrides any value from an active APM agent.
    * `serviceVersion` `{type-string}` A "service.version" value. If specified this overrides any value from an active APM agent.
    * `serviceEnvironment` `{type-string}` A "service.environment" value. If specified this overrides any value from an active APM agent.
    * `serviceNodeName` `{type-string}` A "service.node.name" value. If specified this overrides any value from an active APM agent.
    * `eventDataset` `{type-string}` A "event.dataset" value. If specified this overrides the default of using `${serviceVersion}`.

### Request Example
```javascript
const winston = require('winston');
const { ecsFormat } = require('@elastic/ecs-winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    ecsFormat({
      serviceName: 'my-app',
      serviceVersion: '1.0.0'
    }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console()
  ]
});

logger.info('User logged in', { userId: 123 });
```

### Response
#### Success Response (200)
Not applicable as this is a formatter function.

#### Response Example
Not applicable.
```

--------------------------------

### Lint Code with npm Workspaces

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/CONTRIBUTING.md

Run the linter on all packages in the repository using npm workspaces.

```bash
npm --workspaces lint
```

--------------------------------

### Basic Pino Usage with ECS Format

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

Configure Pino with ecsFormat to generate ECS-compliant logs. Child loggers can be created for scoped logging.

```javascript
const { ecsFormat } = require('@elastic/ecs-pino-format');
const pino = require('pino');

const log = pino(ecsFormat(/* options */)); 
log.info('Hello world');

const child = log.child({ module: 'foo' });
child.warn('From child');
```

--------------------------------

### Basic ECS Logging with ecsFormat

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Use `ecsFormat()` to create a composite Winston format for ECS field mapping and JSON serialization. Supports Winston 3.x (>=3.3.3). Options include `convertErr`, `convertReqRes`, `apmIntegration`, and service metadata.

```javascript
const winston = require('winston')
const { ecsFormat } = require('@elastic/ecs-winston-format')

const logger = winston.createLogger({
  level: 'info',
  format: ecsFormat(),
  transports: [
    new winston.transports.Console({
      handleExceptions: true,
      handleRejections: true
    })
  ]
})

logger.info('hi')
// {"@timestamp":"2023-10-14T02:14:17.302Z","log.level":"info","message":"hi","ecs.version":"8.10.0"}

logger.warn('look out', { foo: 'bar' })
// {"@timestamp":"...","log.level":"warn","message":"look out","ecs.version":"8.10.0","foo":"bar"}

// Error serialization — multiple calling styles all produce error.* ECS fields
const err = new Error('boom', { cause: new Error('the cause') })
err.code = 42
logger.error('here is an exception', err)
// { ..., "error": { "type": "Error", "message": "boom", "stack_trace": "...", "cause": "Error: the cause\n...", "code": 42 } }

// err meta field style
logger.info('oops', { err: new TypeError('bad value') })
// { ..., "error": { "type": "TypeError", "message": "bad value", "stack_trace": "..." } }

// HTTP request/response logging with Express
const { ecsFormat: ecsFmt } = require('@elastic/ecs-winston-format')
const expressLogger = winston.createLogger({
  format: ecsFmt({ convertReqRes: true }),
  transports: [new winston.transports.Console()]
})
// then: expressLogger.info('handled request', { req, res })
```

--------------------------------

### ecsFormat([options])

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Creates a formatter for winston that emits logs in ECS Logging format. This function can be used directly or combined with `ecsFields` and `ecsStringify`.

```APIDOC
### `ecsFormat([options])` [winston-ref-ecsFormat]

* `options` `{type-object}` The following options are supported:

    * `convertErr` `{type-boolean}` Whether to convert a logged `err` field to ECS error fields. **Default:** `true`.
    * `convertReqRes` `{type-boolean}` Whether to logged `req` and `res` HTTP request and response fields to ECS HTTP, User agent, and URL fields. **Default:** `false`.
    * `apmIntegration` `{type-boolean}` Whether to enable APM agent integration. **Default:** `true`.
    * `serviceName` `{type-string}` A "service.name" value. If specified this overrides any value from an active APM agent.
    * `serviceVersion` `{type-string}` A "service.version" value. If specified this overrides any value from an active APM agent.
    * `serviceEnvironment` `{type-string}` A "service.environment" value. If specified this overrides any value from an active APM agent.
    * `serviceNodeName` `{type-string}` A "service.node.name" value. If specified this overrides any value from an active APM agent.
    * `eventDataset` `{type-string}` A "event.dataset" value. If specified this overrides the default of using `${serviceVersion}`.


Create a formatter for winston that emits in ECS Logging format. This is a single format that handles both [`ecsFields([options])`](#winston-ref-ecsFields) and [`ecsStringify([options])`](#winston-ref-ecsStringify). The following two are equivalent:

```js
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()
  ),
  // ...
});
```
```

--------------------------------

### Express request/response logging with ecsFormat

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Demonstrates how to use `ecsFormat` with Express applications to log HTTP requests and responses in ECS format. Includes custom middleware for request logging and error logging.

```APIDOC
## Express request/response logging with `ecsFormat`

```js
const { ecsFormat } = require('@elastic/ecs-winston-format')
const express = require('express')
const winston = require('winston')

const logger = winston.createLogger({
  format: ecsFormat({ convertReqRes: true }),
  transports: [new winston.transports.Console()]
})

function requestLogger (opts) {
  return function (req, res, next) {
    function onResDone (err) {
      this.removeListener('finish', onResDone)
      this.removeListener('error', onResDone)
      opts.logger.info(`handled ${req.method} ${req.path}`, { req, res, err })
    }
    res.on('finish', onResDone)
    res.on('error', onResDone)
    next()
  }
}

function errorLogger (opts) {
  return function (err, req, _res, next) {
    opts.logger.warn(`error on ${req.method} ${req.path}`, { err })
    next(err)
  }
}

const app = express()
app.use(requestLogger({ logger }))

app.get('/', (req, res) => { res.setHeader('Foo', 'Bar'); res.end('hi') })
app.get('/error', (req, res, next) => next(new Error('boom')))

app.use(errorLogger({ logger }))   // error loggers must come last
app.listen(3000, () => logger.info('listening at http://localhost:3000'))
```
```

--------------------------------

### ESM / TypeScript import

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Demonstrates how to import the ecsFormat function using CommonJS, ESM, and TypeScript.

```APIDOC
## ESM / TypeScript import

The package supports CommonJS `require`, ESM `import`, and TypeScript named imports. The preferred style is the named export.

```ts
// CommonJS (preferred)
const { ecsFormat } = require('@elastic/ecs-pino-format')

// ESM / TypeScript named import (preferred for TS)
import { ecsFormat } from '@elastic/ecs-pino-format'

// Default import (deprecated but supported)
import ecsFormat from '@elastic/ecs-pino-format'

// Namespace import (TypeScript)
import * as EcsPinoFormat from '@elastic/ecs-pino-format'
const opts = EcsPinoFormat.ecsFormat()
```
```

--------------------------------

### Configure Morgan with ECS Formatter

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/morgan.md

Configure the Express application to use the ecsFormat function from the @elastic/ecs-morgan-format package with the Morgan middleware.

```javascript
const app = require('express')();
const morgan = require('morgan');
const { ecsFormat } = require('@elastic/ecs-morgan-format');

app.use(morgan(ecsFormat(/* options */))); 

// ...
app.get('/', function (req, res) {
  res.send('hello, world!');
})
app.listen(3000);
```

--------------------------------

### ecsFormat([options])

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/pino.md

Configures Pino to output logs in the Elastic Common Schema (ECS) format. This function can be used to set up logging with various options, including APM integration and custom service details.

```APIDOC
## ecsFormat([options])

* `options` {type-object} The following options are supported:

    * `convertErr` {type-boolean} Whether to convert a logged `err` field to ECS error fields. **Default:** `true`.
    * `convertReqRes` {type-boolean} Whether to logged `req` and `res` HTTP request and response fields to ECS HTTP, User agent, and URL fields. **Default:** `false`.
    * `apmIntegration` {type-boolean} Whether to enable APM agent integration. **Default:** `true`.
    * `serviceName` {type-string} A "service.name" value. If specified this overrides any value from an active APM agent.
    * `serviceVersion` {type-string} A "service.version" value. If specified this overrides any value from an active APM agent.
    * `serviceEnvironment` {type-string} A "service.environment" value. If specified this overrides any value from an active APM agent.
    * `serviceNodeName` {type-string} A "service.node.name" value. If specified this overrides any value from an active APM agent.
    * `eventDataset` {type-string} A "event.dataset" value. If specified this overrides the default of using `${serviceVersion}`.

Create options for `pino(...)` that configures ECS Logging format output.
```

--------------------------------

### Equivalent Winston Logger using ecsFields and ecsStringify

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/winston.md

Provides an alternative way to configure the Winston logger by combining ecsFields and ecsStringify, achieving the same result as using ecsFormat directly.

```javascript
const { ecsFields, ecsStringify } = require('@elastic/ecs-winston-format');
const winston = require('winston');

const logger = winston.createLogger({
  format: winston.format.combine(
    ecsFields(/* options */),
    ecsStringify()
  ),
  // ...
});

```

--------------------------------

### Manual npm Publish for ecs-helpers

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/RELEASING.md

Manually publish the ecs-helpers package to npm. Ensure the working tree is clean before proceeding. This is a fallback if automation fails.

```bash
git status              # this should show "working tree clean"

cd packages/ecs-helpers
npm publish
```

--------------------------------

### Integration with pino-http and Express

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Combines `ecsFormat` with `pino-http` for automatic per-request ECS logging in Express applications. Uses a per-request child logger for context.

```javascript
const { ecsFormat } = require('@elastic/ecs-pino-format')
const express = require('express')
const pino = require('pino')
const pinoHttp = require('pino-http')

const log = pino(ecsFormat({ convertReqRes: true }))
const app = express()

app.use(pinoHttp({ logger: log }))

app.get('/', function (req, res) {
  res.setHeader('Foo', 'Bar')
  res.end('hi')
  req.log.info('handled GET /')  // per-request child logger
})

app.get('/error', function (req, res, next) {
  next(new Error('boom'))
})

app.listen(3000, () => log.info('listening at http://localhost:3000'))
// curl http://localhost:3000/ → ECS record with http.*, url.*, client.* fields
```

--------------------------------

### ESM / TypeScript Import Styles for ecsFormat

Source: https://context7.com/elastic/ecs-logging-nodejs/llms.txt

Demonstrates various ways to import `ecsFormat` in Node.js projects, including CommonJS, ESM, and TypeScript.

```javascript
// CommonJS (preferred)
const { ecsFormat } = require('@elastic/ecs-pino-format')
```

```typescript
// ESM / TypeScript named import (preferred for TS)
import { ecsFormat } from '@elastic/ecs-pino-format'
```

```javascript
// Default import (deprecated but supported)
import ecsFormat from '@elastic/ecs-pino-format'
```

```typescript
// Namespace import (TypeScript)
import * as EcsPinoFormat from '@elastic/ecs-pino-format'
const opts = EcsPinoFormat.ecsFormat()
```

--------------------------------

### Tagging and Pushing General Format Package Release

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/RELEASING.md

Tag a specific commit for a general format package release and push the tag to origin. This triggers the GitHub Actions 'release' workflow for automated publishing of format packages.

```bash
git tag vx.y.z
git push origin vx.y.z
```

--------------------------------

### Customizing Log Format with Morgan ECS

Source: https://github.com/elastic/ecs-logging-nodejs/blob/main/docs/reference/morgan.md

Configure the log message format using the `format` option within `ecsFormat`. The default format is 'combined'. You can pass a format string directly or as an option.

```javascript
const app = require('express')();
const morgan = require('morgan');
const { ecsFormat } = require('@elastic/ecs-morgan-format');

app.use(morgan(ecsFormat({ format: 'tiny' }))); 
// ...
```