filestorage

README

File Storage

Status
Stability	beta
Distributions	contrib
Issues
Code Owners	@djaglowski | Seeking more code owners!

The File Storage extension can persist state to the local file system.

The extension requires read and write access to a directory. A default directory can be used, but it must already exist in order for the extension to operate.

directory is the relative or absolute path to the dedicated data storage directory. The default directory is %ProgramData%\Otelcol\FileStorage on Windows and /var/lib/otelcol/file_storage otherwise.

timeout is the maximum time to wait for a file lock. This value does not need to be modified in most circumstances. The default timeout is 1s.

fsync when set, will force the database to perform an fsync after each write. This helps to ensure database integretity if there is an interruption to the database process, but at the cost of performance. See DB.NoSync for more information.

Compaction

compaction defines how and when files should be compacted. There are two modes of compaction available (both of which can be set concurrently):

• compaction.on_start (default: false), which happens when collector starts
• compaction.on_rebound (default: false), which happens online when certain criteria are met; it's discussed in more detail below

compaction.directory specifies the directory used for compaction (as a midstep).

compaction.max_transaction_size (default: 65536): defines maximum size of the compaction transaction. A value of zero will ignore transaction sizes.

Rebound (online) compaction

For rebound compaction, there are two additional parameters available:

• compaction.rebound_needed_threshold_mib (default: 100) - when allocated data exceeds this amount, the "compaction needed" flag will be enabled
• compaction.rebound_trigger_threshold_mib (default: 10) - if the "compaction needed" flag is set and allocated data drops below this amount, compaction will begin and the "compaction needed" flag will be cleared
• compaction.check_interval (default: 5s) - specifies how frequently the conditions for compaction are being checked

The idea behind rebound compaction is that in certain workloads (e.g. persistent queue) the storage might grow significantly (e.g. when the exporter is unable to send the data due to network problem) after which it is being emptied as the underlying issue is gone (e.g. network connectivity is back). This leaves a significant space that needs to be reclaimed (also, this space is reported in memory usage as mmap() is used underneath). The optimal conditions for this to happen online is after the storage is largely drained, which is being controlled by rebound_trigger_threshold_mib. To make sure this is not too sensitive, there's also rebound_needed_threshold_mib which specifies the total claimed space size that must be met for online compaction to even be considered. Consider following diagram for an example of meeting the rebound (online) compaction conditions.

  ▲
  │
  │             XX.............
m │            XXXX............
e ├───────────XXXXXXX..........────────────  rebound_needed_threshold_mib
m │         XXXXXXXXX..........
o │        XXXXXXXXXXX.........
r │       XXXXXXXXXXXXXXXXX....
y ├─────XXXXXXXXXXXXXXXXXXXXX..────────────  rebound_trigger_threshold_mib
  │   XXXXXXXXXXXXXXXXXXXXXXXXXX.........
  │ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  └──────────────── time ─────────────────►
     │           |            |
     issue       draining     compaction happens
     starts      begins       and reclaims space

 X - actually used space
 . - claimed but no longer used space

Example

extensions:
  file_storage:
  file_storage/all_settings:
    directory: /var/lib/otelcol/mydir
    timeout: 1s
    compaction:
      on_start: true
      directory: /tmp/
      max_transaction_size: 65_536
    fsync: false

service:
  extensions: [file_storage, file_storage/all_settings]
  pipelines:
    traces:
      receivers: [nop]
      processors: [nop]
      exporters: [nop]

# Data pipeline is required to load the config.
receivers:
  nop:
processors:
  nop:
exporters:
  nop:

Feature Gates

See the Collector feature gates for an overview of feature gates in the collector.

extension.filestorage.replaceUnsafeCharacters

When enabled, characters that are not safe in file names are replaced in component name using the extension before creating the file name to store data by the extension.

For example, for a Filelog receiver named filelog/logs/json, the data is stored:

• in path receiver_filelog_logs/json with the feature flag disabled (note that this is a file named json inside directory named receiver_filelog_logs).
• in file receiver_filelog_logs~007Ejson with the feature flag enabled.

This replacement is done to prevent surprising behavior or errors in the File Storage extension.

The feature replaces all usafe characters with a tilde ~ and the character's Unicode number in hex. The only safe characters are: uppercase and lowercase ASCII letters A-Z and a-z, digits 0-9, dot ., hyphen -, underscore _.

Changing the state of this feature gate may change the path to the file that the extension is writing component's data to. This may lead to loss of the data stored in the original path.

Before enabling this feature gate, ideally make sure that all component names that use the File Storage extension have names that only contain safe characters. In case you want to keep using unsafe characters in your component names, you may want to rename the files used for storage before enabling this feature gate. For example, mv ./receiver_filelog_logs/json ./receiver_filelog_logs~007Ejson.

For more details, see the following issues:

• File storage extension - invalid file name characters must be encoded #3148
• [filestorage] receiver name sanitization #20731

The schedule for this feature gate is:

• Introduced in v0.87.0 (October 2023) as alpha - disabled by default.
• Moved to beta in v0.92.0 (January 2024) - enabled by default.
• Moved to stable in v0.99.0 (April 2024) - cannot be disabled.
• Removed in v0.102.0 (three releases after stable).

Troubleshooting

Currently, the File Storage extension uses bbolt to store and read data on disk. The following troubleshooting method works for bbolt-managed files. As such, there is no guarantee that this method will continue to work in the future, particularly if the extension switches away from bbolt.

When troubleshooting components that use the File Storage extension, it is sometimes helpful to read the raw contents of files created by the extension for the component. The simplest way to read files created by the File Storage extension is to use the strings utility (Linux, Windows).

For example, here are the contents of the file created by the File Storage extension when it's configured as the storage for the filelog receiver.

$ strings /tmp/otelcol/file_storage/filelogreceiver/receiver_filelog_
default
file_input.knownFiles2
{"Fingerprint":{"first_bytes":"MzEwNzkKMjE5Cg=="},"Offset":10,"FileAttributes":{"log.file.name":"1.log"},"HeaderFinalized":false,"FlushState":{"LastDataChange":"2024-03-20T18:16:18.164331-07:00","LastDataLength":0}}
{"Fingerprint":{"first_bytes":"MjQ0MDMK"},"Offset":6,"FileAttributes":{"log.file.name":"2.log"},"HeaderFinalized":false,"FlushState":{"LastDataChange":"2024-03-20T18:16:39.96429-07:00","LastDataLength":0}}
default
file_input.knownFiles2
{"Fingerprint":{"first_bytes":"MzEwNzkKMjE5Cg=="},"Offset":10,"FileAttributes":{"log.file.name":"1.log"},"HeaderFinalized":false,"FlushState":{"LastDataChange":"2024-03-20T18:16:18.164331-07:00","LastDataLength":0}}
{"Fingerprint":{"first_bytes":"MjQ0MDMK"},"Offset":6,"FileAttributes":{"log.file.name":"2.log"},"HeaderFinalized":false,"FlushState":{"LastDataChange":"2024-03-20T18:16:39.96429-07:00","LastDataLength":0}}
default
file_input.knownFiles2
{"Fingerprint":{"first_bytes":"MzEwNzkKMjE5Cg=="},"Offset":10,"FileAttributes":{"log.file.name":"1.log"},"HeaderFinalized":false,"FlushState":{"LastDataChange":"2024-03-20T18:16:18.164331-07:00","LastDataLength":0}}
{"Fingerprint":{"first_bytes":"MjQ0MDMK"},"Offset":6,"FileAttributes":{"log.file.name":"2.log"},"HeaderFinalized":false,"FlushState":{"LastDataChange":"2024-03-20T18:16:39.96429-07:00","LastDataLength":0}}

Documentation

Index

• func NewFactory() extension.Factory
• type CompactionConfig
• type Config
  • func (cfg *Config) Validate() error

Functions

func NewFactory

func NewFactory() extension.Factory

NewFactory creates a factory for HostObserver extension.

Types

type CompactionConfig

type CompactionConfig struct {
	// OnStart specifies that compaction is attempted each time on start
	OnStart bool `mapstructure:"on_start,omitempty"`
	// OnRebound specifies that compaction is attempted online, when rebound conditions are met.
	// This typically happens when storage usage has increased, which caused increase in space allocation
	// and afterwards it had most items removed. We want to run the compaction online only when there are
	// not too many elements still being stored (which is an indication that "heavy usage" period is over)
	// so compaction should be relatively fast and at the same time there is relatively large volume of space
	// that might be reclaimed.
	OnRebound bool `mapstructure:"on_rebound,omitempty"`
	// Directory specifies where the temporary files for compaction will be stored
	Directory string `mapstructure:"directory,omitempty"`
	// ReboundNeededThresholdMiB specifies the minimum total allocated size (both used and empty)
	// to mark the need for online compaction
	ReboundNeededThresholdMiB int64 `mapstructure:"rebound_needed_threshold_mib"`
	// ReboundTriggerThresholdMiB is used when compaction is marked as needed. When allocated data size drops
	// below the specified value, the compactions starts and the flag marking need for compaction is cleared
	ReboundTriggerThresholdMiB int64 `mapstructure:"rebound_trigger_threshold_mib"`
	// MaxTransactionSize specifies the maximum number of items that might be present in single compaction iteration
	MaxTransactionSize int64 `mapstructure:"max_transaction_size,omitempty"`
	// CheckInterval specifies frequency of compaction check
	CheckInterval time.Duration `mapstructure:"check_interval,omitempty"`
}

CompactionConfig defines configuration for optional file storage compaction.

type Config

type Config struct {
	Directory string        `mapstructure:"directory,omitempty"`
	Timeout   time.Duration `mapstructure:"timeout,omitempty"`

	Compaction *CompactionConfig `mapstructure:"compaction,omitempty"`

	// FSync specifies that fsync should be called after each database write
	FSync bool `mapstructure:"fsync,omitempty"`
}

Config defines configuration for file storage extension.

func (*Config) Validate

func (cfg *Config) Validate() error