pi-mono/packages/agent/docs/telemetry-schema.md

Pi Agent Telemetry Schemas

AI request schema

Schema version: 1

pi.ai.request

One logical request to an AI provider

• Parents: root or any caller span
• Default status: ok
• Error when: The operation throws or returns an error result

Start attributes

Name	Type	Required	Values	Notes	Description
pi.ai.operation	string	yes	stream, fetch_deferred, cancel_deferred, generate_images		Logical provider operation
pi.ai.provider	string	yes			Selected provider id
pi.ai.model	string	yes			Requested model id
pi.ai.api	string	yes			Provider API id
pi.ai.streaming	boolean	yes			Whether this operation returns a stream
pi.ai.deferred	boolean	no			Whether the operation requests or participates in deferred execution

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.ai.response.model	string			Concrete response model
pi.ai.response.id	string		high cardinality	Provider response id
pi.ai.response.stop_reason	string	stop, length, tool_use, error, aborted, deferred		Normalized terminal response reason
pi.ai.http.status_code	number			Final HTTP status
pi.ai.usage.input_tokens	number			Reported input tokens
pi.ai.usage.output_tokens	number			Reported output tokens
pi.ai.usage.cache_read_tokens	number			Reported cache-read tokens
pi.ai.usage.cache_write_tokens	number			Reported cache-write tokens
pi.ai.usage.reasoning_tokens	number			Reported reasoning tokens
pi.ai.usage.total_tokens	number			Reported total tokens
pi.ai.usage.cost	number			Reported total cost
pi.ai.stream.chunk_count	number			Streamed update chunk count
pi.ai.stream.time_to_first_chunk_ms	number			Elapsed milliseconds to first update chunk
pi.ai.error.type	string		low cardinality	Provider or transport error class

Events

No declared span events.

Harness schema

Schema version: 1

pi.harness.run

One admitted in-process run invocation

• Parents: root or caller-owned external span
• Default status: ok
• Error when: The run fails or throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.session.id	string	yes		high cardinality	Session id
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.operation.recovery	boolean	yes			Whether this invocation resumes durable work
pi.operation.kind	string	yes	run		Run operation kind

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.operation.outcome	string	completed, aborted, failed, suspended		Run invocation outcome
pi.error.code	string		low cardinality	Stable operation error code
pi.error.type	string		low cardinality	Low-cardinality operation error class

Events

No declared span events.

pi.harness.compaction

One admitted in-process manual compaction invocation

• Parents: root or caller-owned external span
• Default status: ok
• Error when: The compaction fails or throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.session.id	string	yes		high cardinality	Session id
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.operation.recovery	boolean	yes			Whether this invocation resumes durable work
pi.operation.kind	string	yes	compaction		Compaction operation kind

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.operation.outcome	string	completed, declined, aborted, failed		Compaction invocation outcome
pi.error.code	string		low cardinality	Stable operation error code
pi.error.type	string		low cardinality	Low-cardinality operation error class

Events

No declared span events.

pi.harness.navigation

One admitted in-process navigation invocation

• Parents: root or caller-owned external span
• Default status: ok
• Error when: The navigation fails or throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.session.id	string	yes		high cardinality	Session id
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.operation.recovery	boolean	yes			Whether this invocation resumes durable work
pi.operation.kind	string	yes	navigation		Navigation operation kind

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.operation.outcome	string	completed, declined, aborted, failed		Navigation invocation outcome
pi.error.code	string		low cardinality	Stable operation error code
pi.error.type	string		low cardinality	Low-cardinality operation error class

Events

No declared span events.

pi.harness.checkpoint

One run checkpoint

• Parents: pi.harness.run
• Default status: ok
• Error when: Checkpoint work throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.checkpoint.kind	string	yes	normal, failure_drain, abort_reconcile		Checkpoint purpose

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
none

Events

No declared span events.

pi.harness.turn

One assistant response and its tool batch

• Parents: pi.harness.run
• Default status: ok
• Error when: Turn work throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.turn.id	string	yes		high cardinality	Invocation-local turn id

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
none

Events

No declared span events.

pi.harness.step

One durable retry attempt

• Parents: pi.harness.turn, pi.harness.checkpoint, pi.harness.compaction, pi.harness.navigation
• Default status: ok
• Error when: The attempt retries, fails, or throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.step.kind	string	yes	assistant, compaction, branch_summary		Retryable step kind
pi.step.attempt	number	yes			One-based durable attempt number
pi.compaction.reason	string	no	manual, threshold, overflow		Compaction trigger

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.step.outcome	string	succeeded, retry, failed, aborted, deferred, overflow		Attempt outcome

Events

No declared span events.

pi.harness.tool

One raw phase-2 tool execution

• Parents: pi.harness.turn, pi.harness.run
• Default status: ok
• Error when: Raw phase-2 execution returns an error

Start attributes

Name	Type	Required	Values	Notes	Description
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.turn.id	string	no		high cardinality	Invocation-local live turn id
pi.tool.name	string	yes			Tool name
pi.tool.call_id	string	yes		high cardinality	Tool call id
pi.tool.replay	string	yes	never, safe		Declared replay policy
pi.tool.recovery	boolean	yes			Whether this is recovery execution

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.tool.is_error	boolean			Whether raw phase-2 execution returned an error

Events

No declared span events.

pi.harness.hook

One registered hook handler invocation

• Parents: root or any caller span
• Default status: ok
• Error when: The handler throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.lane.name	string	yes		high cardinality	Lane name
pi.operation.id	string	no		high cardinality	Durable operation id when accepted
pi.hook.name	string	yes	before_run, before_drive, before_run_end, transform_context, before_request, before_payload, after_response, before_tool, after_tool, before_compaction, before_navigation		Hook name
pi.hook.registration_id	string	no			Optional hook registration metadata

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.hook.outcome	string	completed, skipped, blocked, failed		Handler outcome

Events

No declared span events.

pi.harness.sleep

One retry delay

• Parents: pi.harness.run, pi.harness.compaction, pi.harness.navigation, pi.harness.turn, pi.harness.checkpoint
• Default status: ok
• Error when: Sleep work throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.operation.id	string	yes		high cardinality	Durable operation id
pi.sleep.delay_ms	number	yes			Requested delay in milliseconds

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.sleep.outcome	string	elapsed, aborted		Delay outcome

Events

No declared span events.

pi.harness.event_handler

One passive event listener invocation

• Parents: root or any caller span
• Default status: ok
• Error when: The listener throws

Start attributes

Name	Type	Required	Values	Notes	Description
pi.event.type	string	yes	run_start, run_resume, run_suspend, run_abort, run_end, fault, handler_error, turn_start, turn_end, retry_scheduled, retry_start, retry_end, message_start, message_update, message_end, tool_start, tool_update, tool_end, entry_added, write_pending, queue_update, value_update, config_update, compaction_start, compaction_end, navigation_start, navigation_end, lane_created, usage	low cardinality	Delivered harness event type
pi.lane.name	string	no		high cardinality	Lane name for lane-scoped events

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
none

Events

No declared span events.

pi.session.write

One committed session transaction

• Parents: root or any caller span
• Default status: ok
• Error when: Storage rejects the transaction

Start attributes

Name	Type	Required	Values	Notes	Description
pi.session.id	string	yes		high cardinality	Session id
pi.lane.name	string	no		high cardinality	Lane name when supplied by the caller
pi.operation.id	string	no		high cardinality	Durable operation id when supplied by the caller
pi.session.item_count	number	yes			Number of writes in the transaction
pi.session.item_kinds	string[]	yes	elements: entry, usage, value, list		Distinct write kinds in the transaction

End attributes

All end attributes are optional completion enrichment.

Name	Type	Values	Notes	Description
pi.session.first_seq	number			First committed sequence in the transaction
pi.session.last_seq	number			Last committed sequence in the transaction

Events

No declared span events.