> 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/destinations/honeycomb-refinery.md). # Honeycomb Refinery Exports logs and traces from a Bindplane pipeline to a [Honeycomb Refinery](https://docs.honeycomb.io/manage-data-volume/sample/honeycomb-refinery) cluster over OTLP. Refinery is a tail-based sampling proxy that examines whole traces and applies sampling decisions before forwarding the kept data on to Honeycomb. This destination does not send metrics. ### Supported Telemetry | Metrics | Logs | Traces | | ------- | ---- | ------ | | | ✓ | ✓ | ### Prerequisites This destination requires network access to a running Honeycomb Refinery OTLP endpoint, reachable from the collector at the configured hostname and port (gRPC, default `4317`). An API key is required. Refinery forwards the key to Honeycomb as the `x-honeycomb-team` header, so the key must be valid for the destination Honeycomb environment. Grant the key the **Send Events** permission, plus **Create Dataset** if the target dataset(s) do not already exist. See the Honeycomb docs for [managing API keys](https://docs.honeycomb.io/working-with-your-data/settings/api-keys/) and for [setting up Refinery](https://docs.honeycomb.io/manage-data-volume/sample/honeycomb-refinery/set-up). If Refinery is configured to terminate TLS, you will also need the server's CA certificate (and, for mutual TLS, a client certificate and private key) available on the collector host. ### Configuration
Bindplane docs - Honeycomb Refinery - image 1
**Connection** | Parameter | Type | Required | Default | Description | | --------------------- | ------------------ | -------- | ------------ | ------------------------------------------------------------------------------ | | Choose Telemetry Type | Telemetry Selector | No | Logs, Traces | Which signals this destination exports. Valid values are Logs and Traces. | | Hostname | String | Yes | *(empty)* | Hostname or IP address where the exporter sends data to Honeycomb Refinery. | | Port | Integer | No | 4317 | TCP port the exporter sends data to (1–65535). | | API Key | String | Yes | *(empty)* | The Honeycomb API key, sent as the `x-honeycomb-team` header. Sensitive value. | **Advanced** | Parameter | Type | Required | Default | Description | | ------------- | ---------------- | -------- | ------- | --------------------------------------------------------------------------------------- | | Compression | Enum: none, gzip | No | gzip | Compression algorithm used when sending data. | | Drop Raw Copy | Boolean | No | true | When enabled, drops the raw copy of the log stored in `log.record.original`. Logs only. | **TLS** | Parameter | Type | Required | Default | Description | | --------------------------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Enable TLS | Boolean | No | false | Whether to connect to Refinery over TLS. When disabled, the connection is insecure (plaintext). | | Skip TLS Certificate Verification | Boolean | No | false | Skip verification of the server's certificate. Shown when Enable TLS is true. | | TLS Certificate Authority File | String | No | *(empty)* | Path to a CA certificate file used to validate the server's certificate. Shown when Enable TLS is true. | | Server Name Override | String | No | *(empty)* | Optional virtual hostname indicating the server name requested by the client. Generally not required. Shown when Enable TLS is true. | | Mutual TLS | Boolean | No | false | Whether to use client TLS authentication (mTLS). Shown when Enable TLS is true. | | TLS Client Certificate File | String | Yes | *(empty)* | Path to the client certificate for mutual TLS. Required and shown when Enable TLS and Mutual TLS are both true. | | TLS Client Private Key | String | Yes | *(empty)* | Path to the client private key for mutual TLS. Required and shown when Enable TLS and Mutual TLS are both true. | **Retry on Failure** | Parameter | Type | Required | Default | Description | | ----------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------- | | Enable Retry on Failure | Boolean | No | true | Attempt to resend telemetry that failed to transmit. | | Initial interval | Integer | No | 5 | Time in seconds to wait after the first failure before retrying. Shown when retry is enabled. | | Max interval | Integer | No | 30 | Upper bound in seconds on backoff. Shown when retry is enabled. | | Max elapsed time | Integer | No | 300 | Maximum time in seconds spent trying to send a batch before giving up. Shown when retry is enabled. | **Sending Queue** | Parameter | Type | Required | Default | Description | | ------------------------- | --------- | -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Enable Sending Queue | Boolean | No | true | Buffer telemetry temporarily before sending to avoid loss during a temporary network outage. | | Number of Consumers | Integer | No | 10 | Number of consumers that dequeue batches. Shown when the sending queue is enabled. | | Queue Size | Integer | No | 5000 | Maximum number of batches kept in memory before dropping. Shown when the sending queue is enabled. | | Enable Persistent Queuing | Boolean | No | true | Buffer telemetry to disk so data survives network outages or collector restarts. Shown when the sending queue is enabled. | | Persistent Queue Storage | Extension | Yes | `file_storage_persistent_queue` | Storage extension used for the persistent queue. Shown when the sending queue and persistent queuing are both enabled. | ### Examples Export both logs and traces to a Refinery cluster running in-cluster, with gzip compression and the default queueing behavior. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: honeycomb-refinery spec: type: honeycomb_refinery_otlp parameters: - name: telemetry_types value: - Logs - Traces - name: hostname value: refinery.default.svc.cluster.local - name: grpc_port value: 4317 - name: api_key value: YOUR_HONEYCOMB_API_KEY - name: compression value: gzip ``` ### Configuration Tips * **TLS:** Refinery accepts plaintext OTLP by default, so Enable TLS is off out of the box. Turn it on when Refinery terminates TLS or sits behind a TLS-terminating load balancer. Supply the server's CA in TLS Certificate Authority File when the certificate is not signed by a CA already trusted on the collector host. Use Skip TLS Certificate Verification only for testing, since it disables certificate validation entirely. * **mTLS:** When Refinery requires client authentication, enable Mutual TLS and provide both TLS Client Certificate File and TLS Client Private Key (both become required). Set Server Name Override only when the certificate's SAN does not match the hostname the collector dials. * **Routing to datasets:** Refinery respects the `service.name` resource attribute when choosing the Honeycomb dataset. Use an [Add Fields](/integrations/processors/add-fields.md) processor to set `service.name` if you need to route telemetry to specific datasets. * **Durability:** The persistent queue is enabled by default and writes to disk, so batches survive collector restarts. Keep it enabled in production to avoid dropping data during outages. ### Troubleshooting #### Authentication or dataset errors Symptoms: Refinery or Honeycomb rejects events, or datasets are not created. Solutions: 1. Confirm the API Key is valid for the target Honeycomb environment and has the **Send Events** permission. 2. If the destination dataset does not already exist, grant the key the **Create Dataset** permission as well. #### Connection refused or timeouts Symptoms: the exporter cannot reach Refinery. Solutions: 1. Verify Hostname and Port point at the Refinery OTLP gRPC endpoint (default `4317`) and that the collector has network access to it. 2. If Refinery terminates TLS, enable TLS. If it does not, leave TLS disabled so the connection uses plaintext. #### TLS handshake failures Symptoms: errors mentioning certificate verification or an unknown authority. Solutions: 1. Provide the server's CA in TLS Certificate Authority File when the certificate is privately signed. 2. If the certificate's name does not match the dialed hostname, set Server Name Override to the expected name rather than enabling Skip TLS Certificate Verification. #### Dropped data during outages Symptoms: telemetry is lost when Refinery is unreachable. Solutions: 1. Keep the sending queue and persistent queue enabled so batches buffer to disk. 2. Increase Queue Size if bursts overflow the in-memory queue before the persistent queue absorbs them. ### Standalone Destination ```yaml apiVersion: bindplane.observiq.com/v1 kind: Destination metadata: name: honeycomb-refinery spec: type: honeycomb_refinery_otlp parameters: - name: telemetry_types value: - Logs - Traces - name: hostname value: refinery.default.svc.cluster.local - name: grpc_port value: 4317 - name: api_key value: YOUR_HONEYCOMB_API_KEY ``` ### Related Resources * [OTLP exporter — OpenTelemetry Collector reference](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README.md) * [Honeycomb Refinery — vendor setup docs](https://docs.honeycomb.io/manage-data-volume/sample/honeycomb-refinery/set-up) --- # 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, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/destinations/honeycomb-refinery.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.