Event Lifecycle
Understanding agent sessions, event ordering, and the lifecycle of telemetry data.
Agent and Session Management
Section titled “Agent and Session Management”Session ID
Section titled “Session ID”A session is identified by assigning the same session_id value to all events that belong to that session. To group events together, simply use a consistent session_id across those events.
Agent ID
Section titled “Agent ID”You can assign an agent_id to an event. This helps identify multiple agents in the same session. If the agent_id is not set, Cylestio will automatically identify it based on the session and the configured prompt.
Event Ordering and Timeline
Section titled “Event Ordering and Timeline”Events in a session follow a predictable lifecycle pattern. Understanding this order helps ensure proper telemetry collection and analysis.
Session Lifecycle
Section titled “Session Lifecycle”- session.start — Agent session begins, user context and initial configuration established (Required: session_id, agent_id (optional), user context)
- llm.call.* & tool.* events — LLM interactions, function executions, and agent decision-making events (May include: llm.call.start, llm.call.finish, tool.execution, tool.result)
- session.end — Session completion with summary metrics and final state (Includes: total_events, session_duration_ms, completion_status)
Event Flow Visualization
Section titled “Event Flow Visualization”- session.start → Agent initialization
- llm.call.start → LLM request initiated
- llm.call.finish → LLM response received
- tool.execution → Function execution begins
- tool.result → Function execution completes
- session.end → Session completion
Event Correlation
Section titled “Event Correlation”Trace and Span IDs
Section titled “Trace and Span IDs”Trace ID
Section titled “Trace ID”- trace_id: 32-character hex string
- Links all events in a distributed session
- OpenTelemetry compatible format
Span ID
Section titled “Span ID”- span_id: 16-character hex string
- Identifies individual operations
- Enables hierarchical event tracking
Best Practices
Section titled “Best Practices”Async Event Sending
Section titled “Async Event Sending”Send events asynchronously to avoid impacting proxy performance. Cylestio Perimeter gateway continues operation even if event sending fails.
Data Minimization
Section titled “Data Minimization”Only performance and behavioral metadata is collected. PII data can be omitted from request payloads.
Consistent Session IDs
Section titled “Consistent Session IDs”Use consistent session_id values across all related events to enable proper session analysis and correlation.
Proper Timestamps
Section titled “Proper Timestamps”Use ISO 8601 timestamps with timezone support for accurate event ordering and analysis.