## Configuration

### Automatic Formatting

The transport automatically handles the following formatting:

* **ANSI Color Stripping**: ANSI escape codes (from `winston.format.colorize()` etc.) are automatically removed before sending to Logstash.
* **Circular Reference Handling**: Circular object references are replaced with `"[Circular]"` to prevent JSON serialization errors.
* **Shared References**: Objects referenced multiple times are fully serialized at each location (no data loss).

### Connection Options

* `host`
  * The host location of the logstash server.
  * Default: `127.0.0.1`
* `port`
  * The host port to connect.
  * Default: `28777`
* `socket_timeout_ms`
  * Idle socket timeout in milliseconds. When set to a positive value, an idle socket emits a timeout and the transport retries the connection (same path as other connection errors).
  * Default: unset / `0` (disabled)

### Retry Options

* `max_connect_retries`
  * Max number of attempts to reconnect to logstash before going into silence.
  * `-1` means retry forever.
  * Default: `4`
* `timeout_connect_retries`
  * The number of ms between each retry for a reconnect to logstash.
  * Default: `100`
* `retry_transient_errors_only`
  * When `true`, only retry **transient** network errors and fail-fast on permanent TLS/certificate failures (transport goes silent immediately).
  * When `false` or unset (default), **all** connection errors are retried until `max_connect_retries` — this is the historical behavior and must stay the default for existing users.
  * Transient examples: `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `ESOCKETTIMEDOUT`, `EPIPE`, `ENOTFOUND`, `EAI_AGAIN`, `ECONNABORTED`, and socket idle timeouts.
  * Permanent examples: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`, `CERT_HAS_EXPIRED`, `ERR_TLS_CERT_ALTNAME_INVALID`, `DEPTH_ZERO_SELF_SIGNED_CERT`, `SELF_SIGNED_CERT_IN_CHAIN`, and other `ERR_TLS_*` / `ERR_SSL_*` failures.
  * Unknown errors are still retried (safe default when the flag is on).
  * Default: `false`
* `retryStrategy`
  * Advanced retry configuration. If provided, takes precedence over `max_connect_retries` and `timeout_connect_retries`.
  * Two strategies are available:
    * **Fixed delay** (default behavior): retry with a constant delay between attempts.
      ```js
      retryStrategy: {
        strategy: 'fixedDelay',
        maxConnectRetries: 4,      // -1 for unlimited
        delayBeforeRetryMs: 100
      }
      ```
    * **Exponential backoff**: start with a short delay, double it each time (recommended for production).
      ```js
      retryStrategy: {
        strategy: 'exponentialBackoff',
        maxConnectRetries: -1,     // -1 for unlimited
        initialDelayMs: 100,       // optional, default 100
        maxDelayBeforeRetryMs: 120000  // cap delay at 2 minutes
      }
      ```
  * For production services, exponential backoff with unlimited retries is recommended to handle temporary outages gracefully.

### SSL Options

* `ssl_enable`
  * Enable SSL/TLS transfer of logs to logstash.
  * Default: `false`
* `ssl_key`
  * Path location of client private key.
  * Only needed if SSL client authentication is required on logstash.
  * No default
* `ssl_cert`
  * Path location of client public certificate.
  * Only needed if SSL client authentication is required on logstash.
  * No default
* `ca`
  * Path location of certificate authority (CA) certificate.
  * **Required for self-signed certificates** - provide the CA that signed the server certificate.
  * If not provided, the system's trusted CAs are used for verification.
  * No default
* `ssl_passphrase`
  * Passphrase for the SSL key.
  * Only needed if the private key has a passphrase.
  * No default
* `rejectUnauthorized`
  * If true, the connection will reject any server certificate that is not authorized with the list of supplied CAs.
  * Default: `true`

#### SSL with Self-Signed Certificates

If your Logstash server uses a self-signed certificate, you have two options:

1. **Recommended:** Provide the CA certificate that signed the server certificate:
   ```js
   {
     ssl_enable: true,
     ca: '/path/to/ca.cert'
   }
   ```

2. **Not recommended for production:** Disable certificate verification:
   ```js
   {
     ssl_enable: true,
     rejectUnauthorized: false  // Security risk - disables verification
   }
   ```

### Winston 2.x Specific Options

These options are only applicable when using Winston 2.x:

* `node_name`
  * The name of the node/application.
  * Default: `process.title`
* `meta`
  * Default metadata to include with every log entry.
  * No default
* `label`
  * Label for the transport.
  * Default: value of `node_name`