Skip to content

Telemetry reference ​

This page describes the SDK batch payload accepted by the ingest API. It does not promise that every SDK or integration records every field. See Integration coverage for collection paths and Troubleshooting guide to choose signals for a problem.

Field paths here are payload paths. Analytics exposes a flattened representation, so SQL column names can differ. For example, payload inference.output_meta.tokens_in is queried as tokens_in. See the API reference for request constraints and gateway guide for mapped gateway columns.

Event types ​

EventPayload blockMeaning
model_downloaddownloadModel weight transfer
model_loadloadModel initialization
inferenceinferenceOne model invocation
model_unloadunloadModel release
feedbackfeedbackFeedback linked to an inference
errorerrorA reported error
spanspanA timed application step

The batch validator requires the corresponding payload block. Every event except span requires a model_id present in the batch model registry. A span may omit model_id.

memory_warning, accelerator_fallback, and context_truncation are not accepted standalone event types in the current batch API. Do not assume SDK APIs or protocol proposals imply server support for those event types.

Reading the field tables ​

  • Required means required by the ingest schema, not automatically collected.
  • Optional fields can be omitted or null. Treat missing measurements as unknown.
  • int is an integer, float is numeric, and bool is true or false. Arrays use list[...].
  • Durations ending in _ms use milliseconds. Sizes ending in _bytes use bytes. CPU frequencies use MHz. Temperatures use Celsius.
  • Nested blocks have their own tables below. Their field names are relative to that block.

Batch envelope ​

FieldTypePresenceMeaning or unit
protocol_versionstrRequiredProtocol version.
deviceDeviceInfoSchemaRequiredNested payload. See the corresponding table.
modelsdict[str, ModelRegistryEntrySchema]RequiredNested payload. See the corresponding table.
session_idstrRequiredSDK session identifier.
batch_idstrRequiredBatch id.
created_atstrRequiredISO 8601 batch creation time.
sent_atstrRequiredISO 8601 batch send time.
eventslist[EventSchema]RequiredNested payload. See the corresponding table.

Event envelope ​

FieldTypePresenceMeaning or unit
event_idstrRequiredEvent id.
event_typestrRequiredEvent type.
timestampstrRequiredISO 8601 event time.
model_idstrOptionalKey into the batch model registry.
trace_idstrOptionalTrace id.
span_idstrOptionalSpan id.
parent_span_idstrOptionalParent span id.
run_idstrOptionalRun id.
agent_idstrOptionalAgent id.
step_indexintOptionalStep index.
conversation_idstrOptionalConversation id.
attributesobjectOptionalFlat scalar map. Nested objects and arrays are rejected. Event and span attributes share a configured size limit.
gatewaystrOptionalGateway.
telemetryTelemetryContextSchemaOptionalNested payload. See the corresponding table.
serviceServiceContextSchemaOptionalNested payload. See the corresponding table.
request_idstrOptionalRequest id.
requested_model_idstrOptionalRequested model id.
span_rolestring enumOptionalgateway_request, provider_attempt, or internal. Role constraints apply.
reported_costReportedCostSchemaOptionalGateway-reported amount and provenance. Not a universal SDK price calculation.
cache_hitboolOptionalCache hit.
retry_of_span_idstrOptionalProvider-attempt reference. Requires trace_id and span_id.
fallback_of_span_idstrOptionalProvider-attempt reference. Requires trace_id and span_id.
downloadDownloadEventDataSchemaOptionalNested payload. See the corresponding table.
loadLoadEventDataSchemaOptionalNested payload. See the corresponding table.
inferenceInferenceEventDataSchemaOptionalNested payload. See the corresponding table.
unloadUnloadEventDataSchemaOptionalNested payload. See the corresponding table.
feedbackFeedbackEventDataSchemaOptionalNested payload. See the corresponding table.
errorErrorEventDataSchemaOptionalNested payload. See the corresponding table.
spanSpanEventDataSchemaOptionalNested payload. See the corresponding table.
attachmentslist[AttachmentRefSchema]OptionalNested payload. See the corresponding table.
customobjectOptionalCustom JSON. Review supplied values for sensitive content.

Device metadata ​

FieldTypePresenceMeaning or unit
device_idstrRequiredIdentifier supplied by the SDK. Generation and hashing depend on the SDK.
device_typestrRequiredandroid, ios, linux, windows, macos, or embedded.
device_modelstrOptionalDevice model.
os_versionstrOptionalOs version.
app_versionstrOptionalApp version.
sdk_versionstrOptionalSdk version.
localestrOptionalLocale.
timezonestrOptionalTimezone.
cpu_archstrOptionalCpu arch.
cpu_coresintOptionalCpu cores.
ram_total_bytesintOptionalBytes.
disk_total_bytesintOptionalBytes.
acceleratorslist[str]OptionalAccelerators.
gpu_namestrOptionalGpu name.

Model registry ​

FieldTypePresenceMeaning or unit
model_namestrRequiredModel name.
model_familystrOptionalModel family.
model_versionstrOptionalModel version.
model_sourcestrRequiredhuggingface
model_formatstrRequiredonnx
quantizationstrOptionalf32
providerstrOptionalProvider.

Inference ​

FieldTypePresenceMeaning or unit
inference_idstrRequiredIdentifier for the inference.
duration_msintRequiredElapsed time in milliseconds.
input_modalitystrOptionalimage
output_modalitystrOptionalOutput modality.
input_metaInputMetaSchemaOptionalNested payload. See the corresponding table.
output_metaOutputMetaSchemaOptionalNested payload. See the corresponding table.
generation_configGenerationConfigSchemaOptionalNested payload. See the corresponding table.
hardwareHardwareContextSchemaOptionalNested payload. See the corresponding table.
api_metaApiMetaSchemaOptionalNested payload. See the corresponding table.
successboolRequiredOutcome reported by the producer.
error_codestrOptionalError code.

Input measurements ​

FieldTypePresenceMeaning or unit
widthintOptionalWidth.
heightintOptionalHeight.
channelsintOptionalChannels.
formatstrOptionalFormat.
sourcestrOptionalSource.
histogram_summaryHistogramSummarySchemaOptionalNested payload. See the corresponding table.
duration_msintOptionalElapsed time in milliseconds.
sample_rateintOptionalAudio sample rate in Hz.
bit_depthintOptionalBit depth.
codecstrOptionalCodec.
is_streamingboolOptionalIs streaming.
snr_dbfloatOptionalSnr db.
volume_dbfloatOptionalVolume db.
speech_ratiofloatOptionalSpeech ratio.
clipping_detectedboolOptionalClipping detected.
char_countintOptionalChar count.
word_countintOptionalWord count.
token_countintOptionalToken count.
languagestrOptionalLanguage.
language_confidencefloatOptionalLanguage confidence.
encodingstrOptionalEncoding.
contains_codeboolOptionalContains code.
prompt_typestrOptionalPrompt type.
turn_indexintOptionalTurn index.

Image statistics ​

FieldTypePresenceMeaning or unit
brightness_meanfloatOptionalBrightness mean.
brightness_stddevfloatOptionalBrightness stddev.
brightness_bucketslist[int]OptionalBrightness buckets.
contrastfloatOptionalContrast.
saturation_meanfloatOptionalSaturation mean.
blur_scorefloatOptionalBlur score.
noise_scorefloatOptionalNoise score.

Output measurements ​

FieldTypePresenceMeaning or unit
taskstrOptionalTask.
num_predictionsintOptionalNum predictions.
top_klist[TopKPredictionSchema]OptionalNested payload. See the corresponding table.
avg_confidencefloatOptionalAvg confidence.
tokens_inintOptionalTokens in.
tokens_outintOptionalTokens out.
cached_input_tokensintOptionalCached input tokens.
cache_write_input_tokensintOptionalNonnegative integer.
reasoning_tokens_outintOptionalReasoning tokens out.
time_to_first_token_msintOptionalMilliseconds.
tokens_per_secondfloatOptionalTokens per second.
stop_reasonstrOptionalStop reason.
context_usedintOptionalContext used.
avg_token_entropyfloatOptionalAvg token entropy.
safety_triggeredboolOptionalSafety triggered.
dimensionsintOptionalDimensions.
mask_widthintOptionalMask width.
mask_heightintOptionalMask height.
num_classesintOptionalNum classes.

Predictions ​

FieldTypePresenceMeaning or unit
labelstrRequiredLabel.
confidencefloatOptionaldetection/classification confidence
bboxlist[int]Optional[x_min, y_min, x_max, y_max] in input or mask coordinates.
coverage_ratiofloatOptionalFraction of pixels assigned to the class.

Generation settings ​

FieldTypePresenceMeaning or unit
temperaturefloatOptionalTemperature.
top_pfloatOptionalTop p.
top_kintOptionalTop k.
max_tokensintOptionalMax tokens.
repetition_penaltyfloatOptionalRepetition penalty.
frequency_penaltyfloatOptionalFrequency penalty.
presence_penaltyfloatOptionalPresence penalty.
seedintOptionalSeed.
stop_sequences_countintOptionalStop sequences count.

Hardware snapshot ​

FieldTypePresenceMeaning or unit
thermalThermalContextSchemaOptionalNested payload. See the corresponding table.
battery_levelfloatOptionalFraction from 0 to 1.
battery_chargingboolOptionalBattery charging.
memory_available_bytesintOptionalBytes.
cpu_freq_mhzintOptionalMHz.
cpu_freq_max_mhzintOptionalMHz.
accelerator_actualstrOptionalReported execution target. Not a chipset identifier or proof of a fallback.

Thermal snapshot ​

FieldTypePresenceMeaning or unit
statestrOptionalnominal
state_rawstrOptionalplatform-native value
cpu_temp_celsiusfloatOptionalDegrees Celsius.

Provider metadata ​

FieldTypePresenceMeaning or unit
resolved_model_idstrOptionalResolved model id.
system_fingerprintstrOptionalSystem fingerprint.
service_tierstrOptionalService tier.
requested_model_idstrOptionalRequested model id.

Model download ​

FieldTypePresenceMeaning or unit
source_urlstrRequiredDownload source. URLs may contain application-supplied content.
source_typestrRequiredhuggingface
file_size_bytesintRequiredBytes.
downloaded_bytesintRequiredBytes.
duration_msintRequiredElapsed time in milliseconds.
bandwidth_bpsintOptionalTransfer rate in bits per second.
network_typestrRequiredwifi
network_generationstrOptionalNetwork generation.
resumedboolRequiredResumed.
resume_offset_bytesintOptionalBytes.
retry_countintOptionalRetry count.
cache_hitboolRequiredCache hit.
checksum_verifiedboolOptionalChecksum verified.
checksum_algorithmstrOptionalChecksum algorithm.
decompression_time_msintOptionalMilliseconds.
storage_typestrOptionalStorage type.
storage_available_bytesintOptionalBytes.
http_statusintOptionalHttp status.
cdn_edgestrOptionalCdn edge.
successboolRequiredOutcome reported by the producer.
error_codestrOptionalError code.
adapterAdapterDownloadSchemaOptionalNested payload. See the corresponding table.

Download adapter ​

FieldTypePresenceMeaning or unit
adapter_idstrRequiredAdapter id.
adapter_typestrRequiredlora
for_base_modelstrRequiredFor base model.
rankintOptionalRank.

Model load ​

FieldTypePresenceMeaning or unit
duration_msintRequiredElapsed time in milliseconds.
memory_bytesintOptionalBytes.
peak_memory_bytesintOptionalBytes.
memory_mappedboolOptionalMemory mapped.
acceleratorstrRequiredRequested execution target.
gpu_layersintOptionalGpu layers.
threadsintOptionalThreads.
context_lengthintOptionalContext length.
kv_cache_bytesintOptionalBytes.
kv_cache_quantizationstrOptionalKv cache quantization.
flash_attentionboolOptionalFlash attention.
rope_scalingstrOptionalRope scaling.
cold_startboolOptionalCold start.
compile_time_msintOptionalMilliseconds.
adapterAdapterLoadSchemaOptionalNested payload. See the corresponding table.
successboolRequiredOutcome reported by the producer.
error_codestrOptionalError code.

Load adapter ​

FieldTypePresenceMeaning or unit
adapter_idstrRequiredAdapter id.
adapter_typestrRequiredAdapter type.
adapter_sourcestrOptionalAdapter source.
size_bytesintOptionalBytes.
rankintOptionalRank.
alphaintOptionalAlpha.
target_moduleslist[str]OptionalTarget modules.
load_duration_msintOptionalMilliseconds.

Model unload ​

FieldTypePresenceMeaning or unit
duration_msintRequiredElapsed time in milliseconds.
reasonstrRequiredexplicit
memory_freed_bytesintOptionalBytes.
peak_memory_bytesintOptionalBytes.
uptime_msintOptionalhow long the model was loaded

Feedback ​

FieldTypePresenceMeaning or unit
related_inference_idstrRequiredRelated inference id.
feedback_typestrRequiredaccept
delay_msintOptionalMilliseconds.
edit_distanceintOptionalEdit distance.

Error ​

FieldTypePresenceMeaning or unit
error_codestrRequiredError code.
error_messagestrOptionalOptional text. May contain application or provider content.
stack_trace_hashstrOptionalStack trace hash.
related_event_idstrOptionalRelated event id.
http_statusintOptionalHttp status.
provider_error_codestrOptionale.g. insufficient_quota
duration_msintOptionalElapsed time in milliseconds.

Span ​

FieldTypePresenceMeaning or unit
kindstrRequiredagent_step
namestrRequiredName.
duration_msintRequiredElapsed time in milliseconds.
statusstrRequiredok
input_summarystrOptionalOptional content preview. Rejected if it exceeds the configured length limit.
output_summarystrOptionalOptional content preview. Rejected if it exceeds the configured length limit.
attributesobjectOptionalFlat scalar map. Nested objects and arrays are rejected. Event and span attributes share a configured size limit.

Attachment reference ​

FieldTypePresenceMeaning or unit
attachment_idstrRequiredAttachment id.
rolestrRequiredinput
content_typestrRequiredContent type.

Telemetry source ​

FieldTypePresenceMeaning or unit
sourcestring enumRequiredSource.
mapping_versionstrOptionalMapping version.
emitter_versionstrOptionalEmitter version.

Service identity ​

FieldTypePresenceMeaning or unit
namestrOptionalName.
namespacestrOptionalNamespace.
instance_idstrOptionalInstance id.
deployment_environmentstrOptionalDeployment environment.
cloud_regionstrOptionalCloud region.

Reported cost ​

FieldTypePresenceMeaning or unit
amountstrRequiredNonnegative decimal text. Up to 10 integral and 10 fractional digits.
currencystrRequiredThree uppercase letters, for example USD.
sourcestrRequiredSource.
scopestring enumRequiredattempt or request. Must match the span role.
is_estimatedboolOptionalIs estimated.

Content and identifiers ​

Input measurements such as token count, image size, or brightness are metadata. Labels, URLs, errors, attributes, summaries, custom JSON, and attachments can contain content. Do not treat telemetry as inherently free of personal or application data.

Attachments upload separately. Events carry their references, not file bytes. See Captured content for collection controls.

Device identity behavior varies by SDK and version. Do not infer a universal hashing or cross-project isolation guarantee from the device_id field definition.

Source and scope ​

These tables were checked against the server ingest schema on October 30, 2026. They cover accepted payload fields, not an automatic collection matrix or a guarantee of query availability for every field. Server configuration controls size limits. SDK and gateway guides document producer behavior.