> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/logstash.md).

# Logstash

The Logstash source receives logs forwarded from [Logstash](https://www.elastic.co/logstash) over TCP. Bindplane runs a TCP listener that accepts newline-delimited JSON events from a Logstash `tcp` output, parses the standard Logstash fields (`@timestamp`, `host.name`, `log.file.path`, `message`), and maps them onto the OpenTelemetry log record.

### Supported Telemetry Types

| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| Linux    |         | ✓    |        |
| Windows  |         | ✓    |        |
| macOS    |         | ✓    |        |

### Prerequisites

* A running Logstash instance with a [`tcp` output](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-tcp.html) configured to send JSON-encoded events to the collector.
* The collector reachable from Logstash on the configured TCP port.
* When TLS is enabled, a TLS certificate and private key available on the collector host.

### Configuration

<figure><img src="/files/GVr6rnSIUlC5ZIogVGa8" alt="Bindplane docs - Logstash - image 1"><figcaption></figcaption></figure>

#### Logs

| Parameter      | Type    | Default    | Description                                                                             |
| -------------- | ------- | ---------- | --------------------------------------------------------------------------------------- |
| Listen Address | String  | `0.0.0.0`  | IP address to listen on.                                                                |
| Listen Port    | Integer | `2255`     | TCP port to listen on. Required.                                                        |
| Log Type       | String  | `logstash` | Value for the `log_type` attribute. Useful for filtering between many Logstash sources. |

#### Advanced (TLS)

| Parameter            | Type    | Default | Description                                                                                                                                         |
| -------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable TLS           | Boolean | `false` | Whether or not to use TLS.                                                                                                                          |
| TLS Certificate File | String  |         | Path to the TLS certificate to use for TLS-required connections. Applies when TLS is enabled.                                                       |
| TLS Private Key File | String  |         | Path to the TLS private key to use for TLS-required connections. Applies when TLS is enabled.                                                       |
| Minimum TLS Version  | Enum    | `1.2`   | Minimum TLS version to support. Valid values: `1.3`, `1.2`, `1.1`, `1.0`. 1.0 and 1.1 should not be considered secure. Applies when TLS is enabled. |

### Example Configuration

#### Standalone Source

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: logstash
  name: logstash
spec:
  type: logstash
  parameters:
    - name: listen_ip
      value: '0.0.0.0'
    - name: listen_port
      value: '2255'
    - name: log_type
      value: 'logstash'
    - name: enable_tls
      value: 'false'
```

With TLS enabled:

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: logstash
  name: logstash
spec:
  type: logstash
  parameters:
    - name: listen_ip
      value: '0.0.0.0'
    - name: listen_port
      value: '2255'
    - name: log_type
      value: 'logstash'
    - name: enable_tls
      value: 'true'
    - name: tls_certificate_path
      value: '/opt/observiq-otel-collector/logstash.crt'
    - name: tls_private_key_path
      value: '/opt/observiq-otel-collector/logstash.key'
    - name: tls_min_version
      value: '1.2'
```

### Configuring Logstash to forward to the collector

The Logstash source expects newline-delimited JSON events. On the Logstash side, configure a [`tcp` output](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-tcp.html) with the `json_lines` codec pointed at the collector's host and listen port:

```ruby
output {
  tcp {
    host => "<collector-host>"
    port => 2255
    codec => json_lines
  }
}
```

* `<collector-host>` is the address of the collector running the Logstash source.
* `port` must match the `listen_port` configured on the source (`2255` by default).
* The `json_lines` codec is required so each event is delivered as a single JSON object per line.

The source parses the standard Logstash fields automatically: `@timestamp` is promoted to the log record timestamp, `host.name` becomes a resource attribute, `log.file.path` becomes a log record attribute, and the `@timestamp`, `event.original`, and `@version` fields are removed after parsing.

### Configuration Tips

#### Distinguishing multiple Logstash sources

* Set `log_type` to a distinct value per source so downstream pipelines can filter events by their origin. The value is written to the `log_type` attribute on every record.

#### Enabling TLS

* Set `enable_tls` to `true` and provide `tls_certificate_path` and `tls_private_key_path` on the collector host.
* Configure a matching [`ssl_enable`](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-tcp.html) block on the Logstash `tcp` output so the two ends agree on TLS.
* Leave `tls_min_version` at `1.2` or higher; 1.0 and 1.1 are not considered secure.

### Troubleshooting

**Symptom:** No logs arrive from Logstash. **Solution:** Confirm the Logstash `tcp` output `host` and `port` match the collector address and the source `listen_port` (`2255` by default), and that the collector is reachable from Logstash on that port. Verify the output uses the `json_lines` codec.

**Symptom:** Logs arrive but the message body is a single unparsed JSON string instead of structured fields. **Solution:** The source parses JSON events. Make sure the Logstash `tcp` output uses the `json_lines` codec so each event is sent as one JSON object per line. Plain-text or `line` codecs will not parse correctly.

**Symptom:** The log record timestamp does not match event time. **Solution:** Ensure the events include an `@timestamp` field in the format `%Y-%m-%dT%H:%M:%S.%fZ` (the Logstash default). When `@timestamp` is absent, the receiver falls back to ingestion time.

### Related Resources

* [Logstash documentation](https://www.elastic.co/guide/en/logstash/current/introduction.html)
* [Logstash TCP output plugin](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-tcp.html)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/logstash.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.