> ## Documentation Index > Fetch the complete documentation index at: https://docs.odigos.io/llms.txt > Use this file to discover all available pages before exploring further. # Local File Archive > Configuring the Local File Archive backend (Self-Hosted) ### Getting Started ![localfilearchive](https://d15jtxgb40qetw.cloudfront.net/localfilearchive.svg) ### Persistent storage Local File Archive writes OTLP traces, metrics, and logs to disk using the bundled [file exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.159.0/exporter/fileexporter). No cloud account, API key, network authentication, or TLS settings are needed for local writes. Profiles are not supported by this named destination. **VMs:** set `FILE_ARCHIVE_PATH` to an absolute persistent directory writable by the collector service account, and leave `FILE_ARCHIVE_PVC` empty. The collector creates subdirectories with permissions `0750`; provision ownership and filesystem permissions before enabling the destination. Files are written to `//.json`. Use a separate path for each collector process; this exporter does not coordinate concurrent writers. **Kubernetes:** create a Filesystem PVC in the Odigos namespace and set `FILE_ARCHIVE_PVC` to its name. The existing gateway deployment configuration mounts it read-write at `FILE_ARCHIVE_PATH`, using the gateway's existing UID/GID and fsGroup `65534`. The PVC must provide `ReadWriteMany` to support scaling and rolling updates. The storage driver must honor fsGroup or have appropriate permissions provisioned. Each pod writes to `///.json`. A container restart appends to the same files; a replacement pod creates a new directory while previous archives remain on the PVC. Do not run multiple processes with the same pod name and archive path. Mount paths must not overlap existing gateway volumes. ### Formats, rotation, and delivery limits The default is newline-delimited OTLP JSON with no compression. Resource and scope metadata, structured log bodies, and metric types are preserved. `proto` uses OTLP protobuf with a 4-byte unsigned big-endian length before each batch. In the bundled collector's default feature-gate configuration, `zstd` compresses each batch and adds that same length framing, including for JSON; these are not ordinary standalone `.zst` streams. Decode each length-prefixed frame before replay. If you explicitly enable the upstream `exporter.file.nativeCompression` feature gate, its file format changes; follow that version's upstream documentation when decoding. Rotation defaults to 100 MiB, 10 backups, and 7 days of retention per signal and writer directory. Rotation is triggered by size; retention removes rotated files. A single batch larger than the configured file size is rejected. Set size to `0` to disable rotation and append across restarts, with unbounded disk use. Rotation also preserves the active file across collector restarts. Retention does not remove directories belonging to deleted pods: arrange external lifecycle cleanup and disk monitoring. The file exporter has no destination-level retry queue or transactional partial-success protocol. Writes can fail when storage is full or unwritable; monitor collector export errors. Buffered writes without rotation may discover an I/O error only during flush or shutdown, so an accepted batch is not a crash-durability guarantee. Recovery can leave a partial final record or duplicates; downstream readers must handle these. Filesystem access controls protect the archive. TLS/authentication and retries belong to the downstream replay exporter when forwarding files to a network backend. ### Replay persisted JSON Stop the archive writer or copy a stable snapshot first. An OpenTelemetry contrib collector with the `otlpjsonfile` receiver can replay **uncompressed JSON** for all three supported signals; the Odigos distribution does not bundle this replay receiver. For example, mount the archived files read-only and use: ```yaml theme={null} receivers: otlp_json_file: include: [/archive/snapshot/*.json] start_at: beginning include_file_name: false fingerprint_size: 64KiB max_log_size: 128MiB exporters: debug: verbosity: detailed service: pipelines: traces: receivers: [otlp_json_file] exporters: [debug] metrics: receivers: [otlp_json_file] exporters: [debug] logs: receivers: [otlp_json_file] exporters: [debug] ``` Include both active and rotated files when reading a snapshot. Disable filename enrichment to preserve original attributes. Use a fingerprint large enough to reach batch-specific content: files with identical fingerprints may be treated as the same file. Set `max_log_size` above the largest encoded batch to avoid splitting JSON records. For a network replay backend replace `debug` with an OTLP exporter and configure its TLS, credentials, compression, and retry policy. Direct replay of protobuf or framed zstd archives is not supported by `otlpjsonfile`; convert them to newline-delimited OTLP JSON first. ### Configuring Destination Fields > [accordion] Supported Signals: > > ✅ Traces > ✅ Metrics > ✅ Logs > ❌ Profiles * **FILE\_ARCHIVE\_PATH** `string` : Persistent Archive Directory. Absolute writable persistent directory. Files are separated by destination and signal; Kubernetes also separates pods. * This field is required * Example: `/var/lib/odigos/archive` * **FILE\_ARCHIVE\_PVC** `string` : Kubernetes Persistent Volume Claim. Required on Kubernetes: existing Filesystem PVC in the Odigos namespace with ReadWriteMany access. Leave empty on VMs. * This field is optional * **FILE\_ARCHIVE\_FORMAT** `string` : OTLP Encoding. JSON is newline-delimited OTLP and can be replayed with otlpjsonfile. Protobuf uses 4-byte big-endian length-prefixed batches. * This field is required and defaults to `json` * **FILE\_ARCHIVE\_COMPRESSION** `string` : Compression. Bundled exporter supports zstd. By default compressed batches use 4-byte length framing; they are not plain .zst streams and cannot be replayed directly by otlpjsonfile. * This field is required and defaults to `none` * **FILE\_ARCHIVE\_MAX\_MEGABYTES** `number` : Rotation Size (MiB). Maximum size per signal file. Set 0 to disable rotation and append across restarts; disk use is then unbounded. A batch larger than the limit is rejected. * This field is required and defaults to `100` * **FILE\_ARCHIVE\_MAX\_BACKUPS** `number` : Maximum Rotated Files. Maximum backups per signal and writer directory; must be at least 1. * This field is required and defaults to `10` * **FILE\_ARCHIVE\_MAX\_DAYS** `number` : Rotated File Retention (Days). Retention for rotated files; 0 disables age-based deletion. Pod directories from removed pods need external lifecycle cleanup. * This field is required and defaults to `7` ### Adding Destination to Odigos There are two primary methods for configuring destinations in Odigos: ##### **Using the UI** **Step 1** Use the [Odigos CLI](https://docs.odigos.io/cli/odigos_ui.md) to access the UI ```bash theme={null} odigos ui ``` **Step 2** Click on `Add Destination`, select `Local File Archive` and follow the on-screen instructions ##### **Using Kubernetes manifests** **Step 1** Save the YAML below to a file (e.g. `localfilearchive.yaml`) ```yaml theme={null} apiVersion: odigos.io/v1alpha1 kind: Destination metadata: name: localfilearchive-example namespace: odigos-system spec: data: FILE_ARCHIVE_COMPRESSION: '' FILE_ARCHIVE_FORMAT: '' FILE_ARCHIVE_MAX_BACKUPS: '' FILE_ARCHIVE_MAX_DAYS: '' FILE_ARCHIVE_MAX_MEGABYTES: '' FILE_ARCHIVE_PATH: # Note: The commented fields below are optional. # FILE_ARCHIVE_PVC: destinationName: localfilearchive signals: - TRACES - METRICS - LOGS type: localfilearchive ``` **Step 2** Apply the YAML using `kubectl` ```bash theme={null} kubectl apply -f localfilearchive.yaml ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.