This is documentation for the next version of Grafana Tempo documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Tempobreadcrumb arrow Configurebreadcrumb arrow Apache Parquet
Open source

Apache Parquet block format

Tempo has a default columnar block format based on Apache Parquet. This format is required for tags-based search as well as TraceQL, the query language for traces. The columnar block format improves search performance and enables an ecosystem of tools, including Tempo CLI, to access the underlying trace data.

Starting in Tempo 3.1, Tempo writes new blocks in vParquet5 by default. Existing vParquet4 and vParquet3 blocks remain readable. No data migration is required.

Considerations

The Parquet block format has been the default since Tempo 2.0 and is the only supported block format in Tempo 3.x.

If you install using the Tempo Helm charts, then Parquet is enabled by default. No data conversion or upgrade process is necessary. As soon as a block format version is enabled, Tempo starts writing data in that format, leaving existing data as-is.

Block format versions

Warning

The v2 block format has been removed in Tempo 3.0. vParquet3 is deprecated. Tempo 3.x still reads existing vParquet3 blocks. Write new blocks in vParquet5 (default) or vParquet4.

Only Parquet-based formats are supported.

vParquet5

vParquet5 is the default block format as of Tempo 3.1. It builds on vParquet4 with the following improvements:

  • Expanded dedicated columns: Up to 20 dedicated string columns and 5 dedicated integer columns per scope (span, resource, and event), compared with 10 string columns per scope in vParquet4.
  • Event-scoped dedicated columns: Dedicated attribute columns can target event-scoped attributes such as exception.message.
  • Blob column support: High-cardinality or high-length string attributes (for example, stack traces or UUIDs) can use zstd compression instead of dictionary encoding for better efficiency.
  • Array-valued dedicated columns: Dedicated columns can store multiple values per attribute using the options: ["array"] configuration.
  • Materialized timestamp columns for faster metrics queries using common step intervals of 15s, 60s, 300s, and 1h, and any even multiples of those. The best value is chosen by automatically based on the query time range when the step interval is left as auto. For details on configuring dedicated attribute columns with vParquet5 features, refer to Dedicated attribute columns.

vParquet4

vParquet4 is available as an opt-in alternative to the default vParquet5 format.

vParquet4 introduces columns that enable querying for data in array attributes as well as events and links. For more information, refer to Dedicated attribute columns.

Change the block format version

To change the block format version, set the version option in the Storage section of the configuration file:

YAML 
storage:
  trace:
    block:
      version: <version>

If you omit version, Tempo writes vParquet5. Replace <version> with vParquet4 or vParquet5.

To keep writing the previous vParquet4 format, set the version option to vParquet4.

Parquet configuration parameters

Some parameters in the Tempo configuration are specific to Parquet. For more information, refer to the storage configuration documentation.

Trace search parameters

These configuration options impact trace search.

ParameterDefault valueDescription
[read_buffer_size_bytes: <int>]10485676Size of read buffers used when performing search on a vParquet block. This value times the read_buffer_count is the total amount of bytes used for buffering when performing search on a Parquet block.
[read_buffer_count: <int>]32Number of read buffers used when performing search on a vParquet block. This value times the read_buffer_size_bytes is the total amount of bytes used for buffering when performing search on a Parquet block.

The cache_control section contains the follow parameters for Parquet metadata objects:

ParameterDefault valueDescription
[footer: | default = false]falseSpecifies if the footer should be cached
[column_index: <bool> | default = false]falseSpecifies if the column index should be cached
[offset_index: <bool> | default = false]falseSpecifies if the offset index should be cached