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 and Badger are now recommended for new Bindplane OTel Collector deployments due to better performance and resiliency.

Bolt is currently the default persistent queue storage backend, but this may change in the future.

Under the hood, Bolt Persistent Queue storage is the OpenTelemetry filestorage extension.

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 or Badger if you observe:

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

Upgrading from Bolt

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

1. Identify your deployment type

2. Choose the appropriate replacement:

   • Pebble for most cases

   • Badger for large-scale gateways

3. Switch the persistent queue in Bindplane

4. Restart the collector

Troubleshooting Bolt Issues

System is slow

• This is expected as load increases due to lock contention

• Consider upgrading to Pebble or Badger

• Or reduce concurrent batch processors if possible

Lock timeout errors

• Bolt cannot handle your concurrency level

• Upgrade to Pebble (or Badger if 5+ collectors)

• 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 or Badger 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 with less complexity than Badger.

Next Steps

If using Bolt successfully:

• No action required

• Consider upgrading when scaling or experiencing performance issues

• See Persistent Queue and Switching Queues if upgrading

If upgrading from Bolt:

• See Pebble for recommended option

• See Badger if highest throughput is needed