AIPerf Server Metrics Parquet Export Schema | NVIDIA AIPerf Documentation

Schema reference for the server_metrics_export.parquet file. Optimized for SQL analytics with DuckDB, pandas, and Polars.

Overview

The Parquet export provides raw time-series data with cumulative delta calculations applied at each timestamp. Uses a normalized schema where histogram buckets are separate rows (not wide columns), producing ~50% smaller files.

Enable Parquet Export

aiperf profile --model MODEL ... --server-metrics-formats json csv parquet

Delta Calculations

All values are deltas from a reference point (last sample before profiling period):

Metric Type	Value Semantics
Gauge	Raw value at timestamp (no delta)
Counter	Cumulative delta from reference (`value[t] - value[ref]`)
Histogram	Cumulative deltas for `sum`, `count`, and each `bucket_count`

Negative deltas (counter resets) are clamped to 0.

Schema Definition

Fixed Columns

Column	Type	Nullable	Description
`endpoint_url`	`string`	No	Prometheus endpoint URL (e.g., `http://localhost:8000/metrics`)
`metric_name`	`string`	No	Metric name (e.g., `vllm:kv_cache_usage_perc`)
`metric_type`	`string`	No	`gauge`, `counter`, `histogram`, or `unknown` (Prometheus `# TYPE foo untyped`)
`unit`	`string`	Yes	Inferred unit (`seconds`, `tokens`, `requests`, `ratio`, etc.)
`description`	`string`	Yes	Metric HELP text from Prometheus
`timestamp_ns`	`int64`	No	Collection timestamp in nanoseconds since epoch

Value Columns

Column	Type	Nullable	Used By	Description
`value`	`float64`	Yes	Gauge, Counter	Metric value (raw for gauge, delta for counter)
`sum`	`float64`	Yes	Histogram	Cumulative sum delta from reference
`count`	`float64`	Yes	Histogram	Cumulative count delta from reference
`bucket_le`	`string`	Yes	Histogram	Bucket upper bound (e.g., `0.1`, `+Inf`)
`bucket_count`	`float64`	Yes	Histogram	Cumulative bucket count delta (observations <= `bucket_le`)

Dynamic Label Columns

Prometheus labels become individual columns (alphabetically sorted):

Column	Type	Nullable	Description
`engine`	`string`	Yes	vLLM engine ID
`engine_type`	`string`	Yes	Engine type (`trtllm`, `unified`, `prefill`, `decode`)
`finished_reason`	`string`	Yes	Request completion reason
`reason`	`string`	Yes	vLLM waiting reason or Triton failure reason
`sleep_state`	`string`	Yes	vLLM engine sleep state
`source`	`string`	Yes	vLLM prompt-token source
`position`	`string`	Yes	vLLM speculative-decoding draft position
`transfer_type`	`string`	Yes	vLLM KV offload transfer type
`model_name`	`string`	Yes	Model identifier
`dynamo_component`	`string`	Yes	Dynamo worker component
`worker_id`	`string`	Yes	Dynamo worker identifier
`worker_type`	`string`	Yes	Dynamo worker type (`prefill`, `decode`, etc.)
`router_id`	`string`	Yes	Dynamo router identifier
`operation`	`string`	Yes	Dynamo operation name
`migration_type`	`string`	Yes	Dynamo request migration type
`event_type`	`string`	Yes	Dynamo KV publisher event type
`worker`	`string`	Yes	Tokio worker index
`pool`	`string`	Yes	Dynamo KVBM logical pool name
`instance_id`	`string`	Yes	Dynamo KVBM external instance label
`tp_rank`	`string`	Yes	Tensor parallel rank
`pp_rank`	`string`	Yes	Pipeline parallel rank
`moe_ep_rank`	`string`	Yes	SGLang MoE expert-parallel rank
`dp_rank`	`string`	Yes	SGLang data-parallel rank
`priority`	`string`	Yes	SGLang priority-scheduling value
`stage`	`string`	Yes	SGLang processing stage
`mode`	`string`	Yes	SGLang token/CUDA graph mode
`category`	`string`	Yes	SGLang forward execution category
`cache_source`	`string`	Yes	SGLang cache source (`device`, `host`, `storage_*`, `total`)
`num_prefill_ranks`	`string`	Yes	SGLang DP cooperation prefill-rank count
`input_estimation`	`string`	Yes	SGLang prefill-delayer input estimate
`output_allow`	`string`	Yes	SGLang prefill-delayer output allowance
`output_reason`	`string`	Yes	SGLang prefill-delayer output reason
`actual_execution`	`string`	Yes	SGLang prefill-delayer execution outcome
`forward_mode`	`string`	Yes	SGLang expert-parallel forward mode
`layer`	`string`	Yes	SGLang model layer
`request_type`	`string`	Yes	Triton/TensorRT-LLM backend request type
`model_namespace`	`string`	Yes	Triton model namespace
`gpu_uuid`	`string`	Yes	Triton GPU UUID
`_custom_tag`	`string`	Yes	Triton model tag labels (actual column name uses the configured tag name prefixed with `_`)
`memory_type`	`string`	Yes	TensorRT-LLM backend memory type
`kv_cache_block_type`	`string`	Yes	TensorRT-LLM backend KV-cache block type
`disaggregated_serving_type`	`string`	Yes	TensorRT-LLM backend disaggregated-serving metric type
`version`	`string`	Yes	Triton model version
(others)	`string`	Yes	Any additional Prometheus labels

Label columns vary by endpoint/model. Use union_by_name=true for cross-file queries.

Note: Prometheus labels that conflict with reserved column names (endpoint_url, metric_name, metric_type, unit, description, timestamp_ns, value, sum, count, bucket_le, bucket_count) are silently excluded.

Row Structure by Metric Type

Column order: fixed columns → label columns (alphabetically) → value columns.

Gauge/Counter: One Row per Timestamp

endpoint_url | metric_name              | metric_type | unit  | description |timestamp_ns        | model_name   | value | sum  | count | bucket_le | bucket_count
-------------|--------------------------|-------------|-------|-------------|---------------------|--------------|-------|------|-------|-----------|-------------
http://...   | vllm:kv_cache_usage_perc | gauge       | ratio | KV-cache... | 1765793061967310848 | Qwen/Qwen3-0.6B | 0.72  | null | null  | null      | null
http://...   | vllm:request_success     | counter     | null  | Count of... | 1765793061967310848 | Qwen/Qwen3-0.6B | 150.0 | null | null  | null      | null

Histogram: N Rows per Timestamp (One per Bucket)

endpoint_url | metric_name                      | metric_type | unit    | description  | timestamp_ns        | model_name      | value | sum    | count | bucket_le | bucket_count
-------------|----------------------------------|-------------|---------|--------------|---------------------|-----------------|-------|--------|-------|-----------|-------------
http://...   | vllm:e2e_request_latency_seconds | histogram   | seconds | Histogram... | 1765793061967310848 | Qwen/Qwen3-0.6B | null  | 259.87 | 19.0  | 0.3       | 0.0
http://...   | vllm:e2e_request_latency_seconds | histogram   | seconds | Histogram... | 1765793061967310848 | Qwen/Qwen3-0.6B | null  | 259.87 | 19.0  | 1.0       | 1.0
http://...   | vllm:e2e_request_latency_seconds | histogram   | seconds | Histogram... | 1765793061967310848 | Qwen/Qwen3-0.6B | null  | 259.87 | 19.0  | 5.0       | 3.0
http://...   | vllm:e2e_request_latency_seconds | histogram   | seconds | Histogram... | 1765793061967310848 | Qwen/Qwen3-0.6B | null  | 259.87 | 19.0  | +Inf      | 19.0

File Metadata

Parquet file metadata (accessible via pq.read_metadata()) includes:

Key	Description
`aiperf.schema_version`	Schema version (`1.0`)
`aiperf.version`	AIPerf version
`aiperf.benchmark_id`	Unique benchmark UUID
`aiperf.exporter`	Exporter class name (`ServerMetricsParquetExporter`)
`aiperf.export_timestamp_utc`	Export timestamp (ISO 8601)
`aiperf.time_filter_start_ns`	Profiling period start (nanoseconds)
`aiperf.time_filter_end_ns`	Profiling period end (nanoseconds)
`aiperf.profiling_duration_ns`	Profiling duration (nanoseconds)
`aiperf.profiling_duration_seconds`	Profiling duration (seconds)
`aiperf.endpoint_urls`	JSON array of endpoint URLs
`aiperf.endpoint_count`	Number of endpoints
`aiperf.label_columns`	JSON array of label column names
`aiperf.label_count`	Number of label columns
`aiperf.metric_count`	Total unique metrics
`aiperf.metric_type_counts`	JSON object: `{"gauge": N, "counter": N, "histogram": N, "unknown": N}`
`aiperf.model_names`	JSON array of model names
`aiperf.concurrency`	Benchmark concurrency setting
`aiperf.request_rate`	Benchmark request rate (if set)
`aiperf.input_config`	Full user configuration (JSON)
`aiperf.hostname`	Collection host
`aiperf.python_version`	Python version
`aiperf.pyarrow_version`	PyArrow version
`aiperf.schema_note`	Cross-file query hint

Compression: Snappy (good compression ratio with fast decompression)

Example Queries

DuckDB

-- Time-series for a specific metric
SELECT timestamp_ns, value
FROM 'server_metrics_export.parquet'
WHERE metric_name = 'vllm:kv_cache_usage_perc'
ORDER BY timestamp_ns;
-- Filter by label
SELECT timestamp_ns, value
FROM 'server_metrics_export.parquet'
WHERE metric_name = 'vllm:request_success'
  AND model_name = 'Qwen/Qwen3-0.6B'
ORDER BY timestamp_ns;
-- Histogram bucket distribution at final timestamp
SELECT bucket_le, bucket_count
FROM 'server_metrics_export.parquet'
WHERE metric_name = 'vllm:e2e_request_latency_seconds'
  AND timestamp_ns = (SELECT MAX(timestamp_ns) FROM 'server_metrics_export.parquet'
                      WHERE metric_name = 'vllm:e2e_request_latency_seconds')
ORDER BY CAST(REPLACE(bucket_le, '+Inf', '999999') AS DOUBLE);
-- Aggregate across multiple runs (handles schema differences)
SELECT metric_name, AVG(value) as avg_value
FROM read_parquet('artifacts/*/server_metrics_export.parquet', union_by_name=true)
WHERE metric_type = 'gauge'
GROUP BY metric_name;
-- Compare endpoints
SELECT endpoint_url, metric_name, AVG(value) as avg_value
FROM 'server_metrics_export.parquet'
WHERE metric_type = 'gauge'
GROUP BY endpoint_url, metric_name;

pandas

import pandas as pd
df = pd.read_parquet('server_metrics_export.parquet')
# Filter to gauge metrics
gauges = df[df['metric_type'] == 'gauge']
# Time-series plot
kv_usage = df[df['metric_name'] == 'vllm:kv_cache_usage_perc']
kv_usage.plot(x='timestamp_ns', y='value', title='KV Cache Usage')
# Pivot histogram buckets
hist = df[df['metric_name'] == 'vllm:e2e_request_latency_seconds']
pivot = hist.pivot(index='timestamp_ns', columns='bucket_le', values='bucket_count')

Polars

import polars as pl
df = pl.read_parquet('server_metrics_export.parquet')
# Filter and aggregate
result = (
    df.filter(pl.col('metric_type') == 'gauge')
    .group_by('metric_name')
    .agg([
        pl.col('value').mean().alias('avg'),
        pl.col('value').max().alias('max'),
    ])
)
# Lazy scan for large files
lazy = pl.scan_parquet('artifacts/*/server_metrics_export.parquet')
result = lazy.filter(pl.col('metric_name') == 'vllm:kv_cache_usage_perc').collect()

Reading Metadata

import pyarrow.parquet as pq
import json
metadata = pq.read_metadata('server_metrics_export.parquet')
schema_metadata = metadata.schema.to_arrow_schema().metadata
# Access specific fields
benchmark_id = schema_metadata[b'aiperf.benchmark_id'].decode()
config = json.loads(schema_metadata[b'aiperf.input_config'])
label_columns = json.loads(schema_metadata[b'aiperf.label_columns'])

Best Practices

Cross-File Analysis

Label columns vary by endpoint and model. Always use union_by_name:

-- DuckDB
SELECT * FROM read_parquet('run_*/server_metrics_export.parquet', union_by_name=true);

# pandas
import pandas as pd
from pathlib import Path
dfs = [pd.read_parquet(p) for p in Path('.').glob('run_*/server_metrics_export.parquet')]
combined = pd.concat(dfs, ignore_index=True)

Histogram Percentile Estimation

Reconstruct percentiles from bucket data. Note that bucket_count values are cumulative (each bucket includes all observations with value <= bucket_le), matching Prometheus histogram semantics:

import numpy as np
def estimate_percentile(bucket_les, bucket_counts, percentile):
    """Estimate percentile from histogram buckets using linear interpolation."""
    # Convert bucket_le strings to floats (handle +Inf)
    bounds = [float(b) if b != '+Inf' else np.inf for b in bucket_les]
    counts = np.array(bucket_counts)
    total = counts[-1]  # +Inf bucket has cumulative total
    target = total * (percentile / 100)
    for i, (le, count) in enumerate(zip(bounds, counts)):
        if count >= target:
            if i == 0:
                return le
            prev_le = bounds[i-1] if i > 0 else 0
            prev_count = counts[i-1] if i > 0 else 0
            # Linear interpolation within bucket
            fraction = (target - prev_count) / (count - prev_count) if count > prev_count else 0
            return prev_le + fraction * (le - prev_le)
    return bounds[-2]  # Return last finite bound

Memory-Efficient Processing

For large files, use lazy evaluation:

# Polars lazy scan
import polars as pl
df = pl.scan_parquet('server_metrics_export.parquet') \
    .filter(pl.col('metric_name') == 'vllm:kv_cache_usage_perc') \
    .collect()
# DuckDB direct query (doesn't load entire file)
import duckdb
result = duckdb.query("""
    SELECT AVG(value) FROM 'server_metrics_export.parquet'
    WHERE metric_name = 'vllm:kv_cache_usage_perc'
""").fetchone()

Schema Version History

Version	Changes
`1.0`	Initial schema with normalized histogram buckets

For aggregated statistics, see JSON Schema. For metric definitions, see Server Metrics Reference. For usage examples, see the Server Metrics Tutorial.