docs(spicepod): Flight batch_size and ipc_compression, OTLP temporality, runtime.tracing, and the tokenizerConfig file type by spiceemma · Pull Request #2443 · spiceai/docs

spiceemma · 2026-10-27T14:58:01Z

Summary

A Gaps sweep of the spicepod-schema inventory compared .schema/spicepod.schema.json and the crates/spicepod/src structs on spiceai/spiceai origin/trunk with website/docs/reference/spicepod/. This PR fills five of the gaps it found. Four are Spicepod properties with no row on any docs page. The fifth is an enum value that the reference spells in a form the runtime does not accept.

Each property exists unchanged at v2.4.0 and v2.3.3, so the rows go into the three maintained versions: vNext, 2.4.x, and 2.3.x. The files[].type value is wrong in every version, so that correction goes into all 13 models.md copies.

runtime.telemetry.otel_exporter.temporality: delta (default), cumulative, or low_memory.
runtime.flight.batch_size: mode: adaptive (default, with max: 131072) or mode: default.
runtime.flight.ipc_compression: none (default), lz4_frame, or zstd.
runtime.tracing: zipkin_enabled and zipkin_endpoint. Before this PR it was documented only on the Zipkin monitoring page.
models[].files[].type: the reference listed tokenizer_config. ModelFileType is #[serde(rename_all = "camelCase")] with no alias, so the accepted value is tokenizerConfig.

Reproduction

Item 5: `tokenizer_config` vs `tokenizerConfig` (Reproduced, name claim)

Doc said (website/docs/reference/spicepod/models.md:103 at docs 31f71082, and the same line in every versioned_docs/version-*/reference/spicepod/models.md): - `tokenizer_config`: Tokenizer configuration

Code says (crates/spicepod/src/component/model.rs at origin/trunk 814e639e):

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schemars", derive(JsonSchema))]
#[serde(rename_all = "camelCase")]
pub enum ModelFileType {
    Weights,
    Config,
    Tokenizer,
    TokenizerConfig,
    GenerationConfig,
}

Same at every release the docs cover:

$ for v in 1.5 ... 2.4; do <latest vX.Y.* tag>: grep rename_all and alias count on ModelFileType; done
1.5 v1.5.2 ... rename_all = "camelCase" aliases=0
1.6 v1.6.1 ... rename_all = "camelCase" aliases=0
1.7 v1.7.3 ... rename_all = "camelCase" aliases=0
1.8 v1.8.3 ... rename_all = "camelCase" aliases=0
1.9 v1.9.2.d2541e8 ... rename_all = "camelCase" aliases=0
1.10 v1.10.4 ... rename_all = "camelCase" aliases=0
1.11 v1.11.6 ... rename_all = "camelCase" aliases=0
2.0 v2.0.1 ... rename_all = "camelCase" aliases=0
2.1 v2.1.5 ... rename_all = "camelCase" aliases=0
2.2 v2.2.2 ... rename_all = "camelCase" aliases=0
2.3 v2.3.3 ... rename_all = "camelCase" aliases=0
2.4 v2.4.0 ... rename_all = "camelCase" aliases=0

Behavior claim, that a Spicepod with type: tokenizer_config fails to load: not run, because there is no spiced build on this machine. The claim follows from serde's rename_all = "camelCase" with no alias. Unverified, code inspection only.

Items 1–4: missing rows (Gaps, additions)

The sweep found no row for these properties on any page:

$ grep -c 'temporality\|batch_size\|ipc_compression\|zipkin' website/{docs,versioned_docs/version-2.4.x,versioned_docs/version-2.3.x}/reference/spicepod/runtime.md
0 / 0 / 0

Verification

Read on origin/trunk 814e639e8eb55eacbe3f3fadaad2ec0aaf712c05. Each struct field is also present at v2.4.0 and v2.3.3:

pub temporality: OtelTemporality: trunk=1 v2.4.0=1 v2.3.3=1
pub batch_size: FlightBatchSize: trunk=1 v2.4.0=1 v2.3.3=1
pub ipc_compression: FlightIpcCompression: trunk=1 v2.4.0=1 v2.3.3=1
pub zipkin_endpoint: trunk=1 v2.4.0=1 v2.3.3=1
DEFAULT_FLIGHT_ADAPTIVE_BATCH_SIZE_MAX: usize = 131_072: trunk=1 v2.4.0=1 v2.3.3=1

crates/spicepod/src/component/runtime.rs
  #[serde(rename_all = "snake_case")] pub enum OtelTemporality { #[default] Delta, Cumulative, LowMemory }
  /// This setting only affects the OTLP push exporter; the runtime's Prometheus scrape endpoint always exposes cumulative metrics regardless of this value.
  #[serde(rename_all = "snake_case", tag = "mode")] pub enum FlightBatchSize { Default, Adaptive { max: usize } }
  impl Default for FlightBatchSize { fn default() -> Self { Self::Adaptive { max: DEFAULT_FLIGHT_ADAPTIVE_BATCH_SIZE_MAX } } }
  #[serde(rename_all = "snake_case")] pub enum FlightIpcCompression { #[default] None, Lz4Frame, Zstd }
  pub struct TracingConfig { pub zipkin_enabled: bool, pub zipkin_endpoint: Option<String> }
crates/runtime/src/datafusion/query.rs:607   adaptive_flight_batch_size: only for Protocol::Flight | Protocol::FlightSQL; raises the batch size from planner statistics, capped by `max`
crates/runtime/src/flight/mod.rs:335-339     FlightIpcCompression::{None => None, Lz4Frame => LZ4_FRAME, Zstd => ZSTD} -> IpcWriteOptions::try_with_compression
bin/spiced/src/tracing.rs:507-508            return Err("zipkin_endpoint is required when zipkin_enabled is true".into());
bin/spiced/src/tracing.rs:511-514            eprintln!("Zipkin endpoint '{zipkin_endpoint}' is not reachable. Skipping Zipkin exporter initialization."); return Ok(None);

Files changed: 16 (3 runtime.md and 13 models.md).

Propagation:

$ grep -rln '`tokenizer_config`: Tokenizer configuration' website/ | wc -l
0

Build: NODE_OPTIONS=--max-old-space-size=12288 npm run build:

[SUCCESS] Generated static files in "build".
exit=0

Style grep over the added lines: no hits.

Test plan

cd website && npm run build passes (output above)
Versioned-docs propagation checked (grep above)
Files updated: 16

Review gate

Adversarial review: skipped — codex not installed (receipt: attempt=codex result=not-installed, engine=none)
/security-review: not run — docs-only Markdown diff; the same review on the sibling docs-only PR docs: request-context metric labels, HTTPS redirect guard, ORC metadata limit, scalar function memory, OTLP log record size #2440 found nothing
/simplify: not run — docs-only diff, no code

…mporality, runtime.tracing, and the tokenizerConfig model file type

github-actions · 2026-10-27T14:58:13Z

✅ Pull with Spice Passed

Passing checks:

✅ Title meets minimum length requirement (10 characters)
✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
✅ No banned labels detected
✅ Has at least one assignee: spiceemma

github-actions · 2026-10-27T15:04:28Z

🚀 deployed to https://4fdaa511.spiceai-org-website.pages.dev

Copilot

🟡 Changes recommended

The low_memory description misstates counter temporality in all three runtime references, which could lead readers to interpret exported metrics incorrectly.

1 open issue

Correct low_memory metric temporality documentation · New

What changed in this PR

This documentation-only PR fills gaps in the Spicepod configuration reference and corrects the tokenizer configuration file type to match the runtime’s accepted value.

Changes:

Documents Flight batch sizing and IPC compression, OTLP temporality, and Zipkin tracing for vNext, 2.4.x, and 2.3.x.
Corrects tokenizer_config to tokenizerConfig in all 13 model references.

File	Description
`website/versioned_docs/version-2.4.x/reference/spicepod/runtime.md`	Documents missing runtime settings for 2.4.x.
`website/versioned_docs/version-2.4.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-2.3.x/reference/spicepod/runtime.md`	Documents missing runtime settings for 2.3.x.
`website/versioned_docs/version-2.3.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-2.2.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-2.1.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-2.0.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.9.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.8.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.7.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.6.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.5.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.11.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/versioned_docs/version-1.10.x/reference/spicepod/models.md`	Corrects the tokenizer file type.
`website/docs/reference/spicepod/runtime.md`	Documents missing runtime settings for vNext.
`website/docs/reference/spicepod/models.md`	Corrects the tokenizer file type.

_{Review effort: Balanced}

…ers and histograms

spiceemma · 2026-10-27T15:08:52Z

Copilot review #2443 (review) (low_memory temporality): fixed in 7cde3c5 in vNext, version-2.4.x and version-2.3.x, verified against opentelemetry_sdk 0.32.1 src/metrics/instrument.rs:62-68 as pinned at v2.3.3, v2.4.0 and trunk; details in #2443 (comment).

Copilot

🟢 Approved

The documentation matches the referenced implementation, includes the prior temporality correction, and has no unresolved blocking issues.

No open issues 🎉

1 resolved since last review

Correct low_memory metric temporality documentation

_{Review effort: Balanced}

github-actions · 2026-10-27T15:14:30Z

🚀 deployed to https://2f20c13f.spiceai-org-website.pages.dev

docs: runtime.flight batch_size and ipc_compression, otel_exporter te…

b25a95e

…mporality, runtime.tracing, and the tokenizerConfig model file type

spiceemma requested a review from a team as a code owner October 27, 2026 14:58

spiceemma added area/docs area/config kind/bug kind/documentation labels Oct 27, 2026

Copilot AI balanced review requested due to automatic review settings October 27, 2026 14:58

spiceemma self-assigned this Oct 27, 2026

Copilot started reviewing on behalf of spiceemma October 27, 2026 14:58

View session

github-actions Bot deployed to preview October 27, 2026 15:04

View deployment

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Comment thread website/docs/reference/spicepod/runtime.md Outdated

docs(spicepod): low_memory temporality is delta for synchronous count…

7cde3c5

…ers and histograms

Copilot AI balanced review requested due to automatic review settings October 27, 2026 15:08

Copilot started reviewing on behalf of spiceemma October 27, 2026 15:09

View session

Copilot AI approved these changes Oct 27, 2026

View reviewed changes

github-actions Bot deployed to preview October 27, 2026 15:14

View deployment

lukekim approved these changes Oct 27, 2026

View reviewed changes

lukekim merged commit d9c1257 into trunk Oct 27, 2026
8 checks passed

lukekim deleted the docs-sync/2026-10-27-spicepod-reference-gaps branch October 27, 2026 16:54

spiceemma mentioned this pull request Oct 27, 2026

docs(spicepod): describe OTLP low_memory temporality as the OpenTelemetry SDK applies it spiceai/spiceai#15699

Merged

2 of 3 tasks

Navigation Menu

Repository navigation

docs(spicepod): Flight batch_size and ipc_compression, OTLP temporality, runtime.tracing, and the tokenizerConfig file type - #2443

docs(spicepod): Flight batch_size and ipc_compression, OTLP temporality, runtime.tracing, and the tokenizerConfig file type#2443
lukekim merged 2 commits into
trunkfrom
docs-sync/2026-10-27-spicepod-reference-gaps

spiceemma commented Oct 27, 2026

Uh oh!

github-actions Bot commented Oct 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

spiceemma commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Oct 27, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

spiceemma commented Oct 27, 2026

Summary

Reproduction

Item 5: tokenizer_config vs tokenizerConfig (Reproduced, name claim)

Items 1–4: missing rows (Gaps, additions)

Verification

Test plan

Review gate

Uh oh!

github-actions Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull with Spice Passed

Passing checks:

Uh oh!

github-actions Bot commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

spiceemma commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approved

Uh oh!

github-actions Bot commented Oct 27, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Item 5: `tokenizer_config` vs `tokenizerConfig` (Reproduced, name claim)

github-actions Bot commented Oct 27, 2026 •

edited

Loading