Honeycomb Refinery

Exports logs and traces from a Bindplane pipeline to a 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 Types

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 and for setting up Refinery.

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

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.

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 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

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
• Honeycomb Refinery — vendor setup docs