# Bolt

### Overview

Bolt is the original persistent queue storage backend for OpenTelemetry Collector. It provides basic data buffering through a simple, log-based approach. While proven and still fully supported, Pebble is now recommended for new Bindplane OTel Collector deployments due to better performance and resiliency.

{% hint style="warning" %}
Bolt is currently the default persistent queue storage backend, but this may change in the future.
{% endhint %}

{% hint style="info" %}
Under the hood, Bolt Persistent Queue storage is the [OpenTelemetry filestorage extension](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/storage/filestorage).
{% endhint %}

### Configuration

The following parameters control Bolt behavior:

| Parameter                              | Type    | Default  | Description                                                                                                                                                                       |
| -------------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Persistent Queue Directory`           | string  | Required | Directory where Bolt stores data                                                                                                                                                  |
| `Synchronize Persistent Queue to Disk` | boolean | true     | Whether to synchronize the persistent queue to disk. This helps to ensure database integrity if there is an interruption to the database process, but at the cost of performance. |
| `Timeout`                              | string  | `1s`     | The timeout for storage operations (in seconds)                                                                                                                                   |

### When to Use Bolt

Use Bolt for:

* Existing deployments already using it successfully
* Development and testing only
* Simple single-collector agent deployments
* When evaluating Bindplane before committing to new infrastructure

Do **not** use Bolt for:

* New production gateway deployments
* Deployments requiring high throughput
* Multi-collector setups
* Scaling beyond a single collector

### Historical Context

Bolt is the **original persistent storage backend** for OpenTelemetry Collector. For many years, it was the default and only option, serving organizations well across countless deployments. Many production systems successfully use Bolt today.

As Bindplane and the broader OpenTelemetry ecosystem evolved, deployment requirements changed:

**Then (when Bolt was created):**

* Primarily agent deployments on individual machines
* Minimal batching and buffering needs
* Simple, straightforward data processing

**Now (modern Bindplane deployments):**

* Multi-collector gateways for reliability and scale
* Complex batch processing with many concurrent workers
* High-throughput, multi-source data handling
* Need for efficient per-collector performance

Bolt wasn't designed with these modern patterns in mind. Its lock-based design becomes a bottleneck under concurrent load.

### File Storage Limitations

**Lock-Based Design**

* Uses mutual exclusion to prevent concurrent access
* Only one operation can proceed at a time
* Performance degrades when multiple sources send data simultaneously

**Inefficient Under Concurrency**

* Collectors with multiple batch processors experience slowdowns
* Gateway deployments with multiple concurrent processors become bottlenecked
* Not optimized for multi-consumer patterns in modern Bindplane gateways

**Disk Space Management**

* Deleted data remains in the file until compaction
* Disk space can become fragmented
* Compaction is a complete file rewrite

### When to Upgrade from Bolt

Consider upgrading to Pebble if you observe:

| Symptom                             | Indicator                            | Recommended Action |
| ----------------------------------- | ------------------------------------ | ------------------ |
| **Performance degrading**           | System slows under sustained load    | Switch to Pebble   |
| **Lock contention errors**          | Lock timeout messages in logs        | Switch to Pebble   |
| **Queue not draining**              | Queue size telemetry never decreases | Switch to Pebble   |
| **Scaling beyond single collector** | Building 2+ collector gateways       | Switch to Pebble   |

### Upgrading from Bolt

If you're using Bolt and want to improve performance:

1. Identify your deployment type
2. [Switch](/configuration/bindplane-otel-collector/persistent-queue/switching-queues.md) the persistent queue in Bindplane
3. Restart the collector

### Troubleshooting Bolt Issues

**System is slow**

* This is expected as load increases due to lock contention
* Consider upgrading to Pebble
* Or reduce concurrent batch processors if possible

**Lock timeout errors**

* Bolt cannot handle your concurrency level
* Upgrade to Pebble
* Sign that Bolt has reached its design limits for your use case

**Disk space growing constantly**

* Compaction cannot keep up with data churn
* Or switch to Pebble for better garbage collection

### Status

* **Supported**: Yes, fully supported and functional
* **Recommended for new deployments**: No
* **OK to stay on if working well**: Yes
* **Urgent to upgrade**: Only if experiencing issues

Bolt remains a proven choice. However, Pebble provides better performance for modern deployments.

### Next Steps

**If using Bolt successfully:**

* No action required
* Consider upgrading when scaling or experiencing performance issues
* See [Persistent Queue](/configuration/bindplane-otel-collector/persistent-queue.md) and [Switching Queues](/configuration/bindplane-otel-collector/persistent-queue/switching-queues.md) if upgrading

**If upgrading from Bolt:**

* See [Pebble](/configuration/bindplane-otel-collector/persistent-queue/pebble.md) for recommended option


---

# Agent Instructions: 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/configuration/bindplane-otel-collector/persistent-queue/bolt.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.